docs(rfc): RFC-010 verification-comment current-state fixups

[aaltshuler]

Applies the Verification comments (Codex) on RFC-010 — current-state accuracy fixups found against the now-merged 3a/3b/3c code. Kept verbatim with per-point Resolution (accepted) notes.

• graphs list marked remote-only today in the current-state table (embedded arm bails; rides GraphClient only to share the resolver).
• init noted as positional-URI-only today (no --target) — adding --target is part of the proposal, entangled with the init→cluster apply signpost, not current state.
• Validated-fact Add OpenAPI documentation endpoint and schema #1 rephrased to the post-collapse reality (GraphClient::resolve*; only the two factories call apply_server_flag) — drops the stale "16 call sites" count.
• Authority rule gains a flag-shape caveat: --graph is already a global flag requiring --server, so the cluster-managed resolver + its flag shape are deferred to a later slice; the illustrative --cluster <dir> --graph <id> spelling is marked not-final.

Docs-only. This lands before the RFC-010 Slice 1 implementation so the RFC's current-state is accurate when the code starts.

🤖 Generated with Claude Code

Greptile Summary

This docs-only PR applies four current-state accuracy fixups to RFC-010 against the now-merged RFC-009 Phases 3a–3c code, each paired with a "Resolution (accepted)" note appended as a Verification comments appendix section.

• graphs list / init table corrections: The current-state plane table now marks graphs list as remote-only today (with an explanatory note on its GraphClient routing) and adds an inline caveat that init accepts only a required positional URI today — neither --target nor config aliases.
• Validated-fact rewrite: The stale "16 call sites through apply_server_flag" description is replaced with the post-collapse reality (GraphClient::resolve*; only the two factories call apply_server_flag).
• Authority rule flag-shape deferral: The proposed --cluster <dir> --graph <id> addressing for cluster-managed maintenance is now explicitly marked "for illustration" and the whole cluster-managed resolver is deferred to a later slice, because --graph is already a global flag requiring --server with a different meaning that clap cannot disambiguate.

Confidence Score: 4/5

Safe to merge — docs-only change with no code or behavior impact.

All four fixups are accurate and well-reasoned. The one issue is a cross-section inconsistency: the authority rule now marks --cluster <dir> --graph <id> as not-final and deferred, but the target ergonomics code block still presents that same flag shape as a clean example with no matching qualification. An implementer reading the ergonomics section first would see what looks like a settled flag contract.

The target ergonomics section of docs/dev/rfc-010-cli-planes-restructure.md (the --cluster ./cluster --graph knowledge code block, ~line 147) should carry a caveat consistent with the flag-shape deferral note added to the authority rule.

Important Files Changed

Filename

Overview

docs/dev/rfc-010-cli-planes-restructure.md

Docs-only RFC fixup: updates the current-state table to mark graphs list as remote-only, calls out init's positional-URI-only addressing today, replaces the stale "16 call sites" count with the post-collapse GraphClient::resolve* description, and adds a flag-shape deferral caveat to the Authority rule. One cross-section inconsistency: the new authority-rule caveat marks --cluster <dir> --graph <id> as not-final/deferred, but the target ergonomics code block still presents that same flag shape as a clean end-state example without qualification.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[CLI invocation] --> B{Which plane?}

    B -->|Data verb| C[GraphClient resolver]
    C --> D{--server/--graph or\n--target/positional URI?}
    D -->|--server prod --graph id| E[GraphClient::resolve*\napply_server_flag in factory]
    D -->|--target / URI| F[Embedded engine\nor HTTP per config]
    E --> G[Remote HTTP execution]
    F --> H[Embedded or Remote\nper target resolution]

    B -->|Storage/Maintenance verb| I[resolve_uri /\nresolve_local_uri]
    I --> J{Addressing form?}
    J -->|positional URI| K[Direct storage\nfile:// or s3://]
    J -->|--target| L{Resolves to?}
    L -->|direct storage| K
    L -->|remote http://| M[Loud error:\nstorage-plane needs\ndirect storage]
    J -->|init today| N[Required positional URI only\nno --target today]
    K --> O[Embedded engine\non storage]

    B -->|Control verb| P[cluster directory\nreader]
    P --> Q[--config dir\nfile:// or s3://]

    style M fill:#f88,stroke:#c00
    style N fill:#ffd,stroke:#aa0

Loading

Comments Outside Diff (1)

1. docs/dev/rfc-010-cli-planes-restructure.md, line 143-148 (link)

   Target-ergonomics example inconsistent with new flag-shape caveat

   The PR adds a flag-shape caveat in the Authority rule section (lines 213–220) that explicitly marks --cluster <dir> --graph <id> as "for illustration" and defers the cluster-managed resolver to a later slice. The target ergonomics section below (this code block plus the error-message example on ~line 140) still presents omnigraph optimize --cluster ./cluster --graph knowledge and --cluster <dir> --graph <id> as committed end-state shapes without any matching qualification. An implementer of Slice 1 who reads the ergonomics section first will see what looks like a settled flag contract, then find the deferral signal only much later in the authority rule. Given AGENTS.md rule 6 ("don't lie — replace wrong text rather than leaving it silently incorrect"), a brief inline note on this block mirroring the authority-rule caveat would make the RFC self-consistent.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

   

_{Reviews (1): Last reviewed commit: "docs(rfc): RFC-010 — apply verification-..." | Re-trigger Greptile}

[greptile-apps]

aaltshuler has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.