From 310dd76ddfa12f1f3321669ebdb1ff07180be66e Mon Sep 17 00:00:00 2001 From: schickling-assistant <261620128+schickling-assistant@users.noreply.github.com> Date: Sat, 8 Aug 2026 23:50:35 +0200 Subject: [PATCH] docs(cli): the spec described a command that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `context/cli/spec.md` was extracted from a repository where this tool was a subcommand called `axe vrs`. It is now its own binary called `intent`, and the document had not moved: 25 of its invocations named a command no reader can run. Renamed in this commit, spec.md only: axe vrs -> intent 25 sites (25 -> 0) Axe / non-Axe -> reworded 11 sites (11 -> 0) The eight wire-contract sites are deliberately untouched and verified byte-identical to the previous commit, line numbers included: the seven `axe.vrs.*.vN` `schema_version` values and the one `` placeholder. Those are parsed by consumers rather than read by humans, so renaming them would convert a documentation change into a silent breaking change. One of them points the other way from the rest — it is produced by an external review backend and only validated here, so moving it unilaterally would break this tool rather than its consumers. Two things are held back on purpose. **The requirement ids are not renamed.** The `AXE.VRS-R*` population spans both documents — 19 definitions in `requirements.md` and one citation here, at the graph extraction example. Renaming only the citation would leave it naming a requirement that does not exist, which `VRS.REQ-R09` forbids in the same commit. The id space is left uniformly at `AXE.VRS-R`, so `skills/intent.md`'s statement that those ids are held stable remains true. `requirements.md` is untouched in this commit. **One reworded line is a judgement, not a rename**, and is worth a reviewer's eye. The anti-goal "do not create a competing top-level `vrs` CLI until there is evidence that non-Axe users need it" had its premise removed by the extraction — this *is* the top-level CLI now. It reads "users need one separate from `intent`", preserving the anti-goal against a second CLI while dropping a condition that no longer parses. Restating the tradeoff behind it would be a requirements decision rather than a rename, so it is flagged rather than made. Verified by running the checker over `context/` before and after, in place: identical diagnostics, none introduced or removed. The four remaining warnings are pre-existing broken links in `requirements.md`, which this commit does not touch. Note that CI's corpus gate runs `intent check intent` and never reads `context/`, so a green run says nothing about this diff. Co-Authored-By: Claude Opus 5 agent-tool: Claude Code agent-tool-version: 2.1.220 agent-runtime: Claude Code 2.1.220 agent-session-lookup: unavailable tooling-profile: dotfiles@unknown-dirty --- context/cli/spec.md | 70 ++++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/context/cli/spec.md b/context/cli/spec.md index 2d56af8..c5e6d00 100644 --- a/context/cli/spec.md +++ b/context/cli/spec.md @@ -1,6 +1,6 @@ -# Spec: Axe VRS +# Spec: intent CLI -This document specifies the `axe vrs` command realization. It builds on +This document specifies the `intent` command realization. It builds on [requirements.md](./requirements.md). ## Status @@ -11,8 +11,8 @@ Draft. Defines: -- `axe vrs` command surface; -- routing between Axe, the VRS checker engine, Nix checks, and future Plan +- `intent` command surface; +- routing between the CLI, the VRS checker engine, Nix checks, and future Plan evidence; - output schema and migration-ratchet behavior for deterministic VRS checks; - semantic review routing through the portable Coding Agent Invocation Contract. @@ -30,7 +30,7 @@ Does not define: ```text human / coding agent / repo check - -> axe vrs + -> intent -> vrs-check engine -> parse Markdown VRS artifacts -> derive graph view @@ -41,23 +41,23 @@ Nix checks -> vrs-check engine -> blocking exit code for strict rules -axe vrs review +intent review -> vrs-check engine diagnostics -> Coding Agent Invocation Contract -> provider backend in read-only review mode -> schema-validated semantic findings ``` -`axe vrs` is an operator and agent UX. The checker engine is the reusable +`intent` is an operator and agent UX. The checker engine is the reusable implementation boundary. Meta-VRS remains the semantic authority. ## Command Surface ```text -axe vrs check [path] [--profile local|strict] [--warnings-as-errors] [--json] -axe vrs graph [path] [--json] -axe vrs review [path] [--profile local|strict] [--backend ] [--coding-agent ] [--report ] -axe vrs review-fixtures [path] [--fixture ]... [--backend ] [--coding-agent ] [--json] [--report ] +intent check [path] [--profile local|strict] [--warnings-as-errors] [--json] +intent graph [path] [--json] +intent review [path] [--profile local|strict] [--backend ] [--coding-agent ] [--report ] +intent review-fixtures [path] [--fixture ]... [--backend ] [--coding-agent ] [--json] [--report ] ``` Default `path` is `context/vrs`, and @@ -76,14 +76,14 @@ meta-VRS-supported child node shapes. | `vrs links` | checker engine link pass | Git working tree/current commit | | `vrs ids` | checker engine ID pass | Meta-VRS ID contract | | `vrs graph` | checker engine graph extraction | Markdown VRS artifacts are source; graph is derived | -| `vrs review` | checker diagnostics plus `$CODING_AGENT` review invocation | VRS/Axe own prompt and schema; Coding Agent Invocation Contract owns provider portability | -| `vrs review-fixtures` | same review invocation over a materialized fixture copy, graded against fixture assertions | VRS evaluation owns fixtures and assertion semantics; Axe owns the runner | -| `vrs doctor` | Axe command plus checker metadata | Axe for UX; checker for rule/migration state | +| `vrs review` | checker diagnostics plus `$CODING_AGENT` review invocation | VRS/CLI own prompt and schema; Coding Agent Invocation Contract owns provider portability | +| `vrs review-fixtures` | same review invocation over a materialized fixture copy, graded against fixture assertions | VRS evaluation owns fixtures and assertion semantics; the CLI owns the runner | +| `vrs doctor` | CLI command plus checker metadata | CLI for UX; checker for rule/migration state | | Nix check | checker engine strict profile | Nix check is blocking gate | ## Checker Engine Boundary -The checker engine should be callable without the Axe CLI. It owns: +The checker engine should be callable without the `intent` CLI. It owns: - filesystem discovery of VRS nodes; - Markdown parsing needed for deterministic rules; @@ -94,7 +94,7 @@ The checker engine should be callable without the Axe CLI. It owns: - derived graph JSON; - diagnostic JSON. -Axe owns: +The CLI owns: - CLI argument parsing; - problems-first human rendering; @@ -109,12 +109,12 @@ Nix owns: - reproducible local/CI execution. The Coding Agent Invocation Contract owns provider-portable non-interactive -agent invocation. `axe vrs review` consumes it; it does not call provider CLIs +agent invocation. `intent review` consumes it; it does not call provider CLIs directly. ## Implementation Order -The first `axe vrs` implementation slice should build deterministic enforcement +The first `intent` implementation slice should build deterministic enforcement primitives before semantic review: 1. checker engine boundary and filesystem discovery; @@ -125,7 +125,7 @@ primitives before semantic review: facts; 6. `review` through CAIC after deterministic diagnostics are stable. -`axe vrs review` remains part of the public target surface, but it should not be +`intent review` remains part of the public target surface, but it should not be implemented before the deterministic checker can produce bounded, schema-shaped diagnostics for the review packet. @@ -182,7 +182,7 @@ when introduced. ## Derived Graph -`axe vrs graph --json` emits the mechanically extracted, resolvable subset of +`intent graph --json` emits the mechanically extracted, resolvable subset of the VRS graph with a deliberately small v0 shape: ```json @@ -247,13 +247,13 @@ emits an ambiguous-structure diagnostic rather than inventing a node or edge. ## Semantic Review -`axe vrs review` runs semantic review after deterministic checks. It builds a +`intent review` runs semantic review after deterministic checks. It builds a bounded review packet from: - the baked VRS semantic-review prompt owned at [intent/16-enforcement/review-prompt.md](../../intent/16-enforcement/review-prompt.md); - the target VRS files; -- `axe vrs check --json` diagnostics; +- `intent check --json` diagnostics; - the semantic review output schema at [intent/16-enforcement/review-result.schema.json](../../intent/16-enforcement/review-result.schema.json). @@ -280,13 +280,13 @@ Callers do not provide an arbitrary prompt. Prompt and schema changes happen in the VRS enforcement node and are validated through eval fixtures before becoming the baked review version. -Provider readiness is checked before spending model tokens. `axe vrs review` +Provider readiness is checked before spending model tokens. `intent review` first runs `$CODING_AGENT capabilities --json`, resolves `--backend ` or the advertised `default_backend`, and validates that backend against the review contract. It does not invoke `$CODING_AGENT run` until the selected backend is known to the adapter and supports all of the requested contract pieces: -| Capability | Required value for `axe vrs review` | +| Capability | Required value for `intent review` | | --- | --- | | mode | `review` | | permission | `read-only` with provider-native, agent-policy, or adapter-sandbox enforcement | @@ -298,11 +298,11 @@ known to the adapter and supports all of the requested contract pieces: Known backend support is capability-based, not provider-name-based. If the default backend or a `--backend ` override is unknown, unavailable, missing one of these capabilities, or only supports a weaker permission/config/output -contract, `axe vrs review` fails before invoking the provider. The supported -backend set may expand without changing the Axe VRS contract as long as the +contract, `intent review` fails before invoking the provider. The supported +backend set may expand without changing the `intent` CLI contract as long as the backend satisfies these same readiness criteria. -Production readiness is backend-scoped. A backend is ready for `axe vrs review` +Production readiness is backend-scoped. A backend is ready for `intent review` when its capability preflight passes, token-free fake-provider regression tests cover its provider-specific command mapping, and at least one bounded manual real-provider run against a small existing VRS subsystem has produced a @@ -314,12 +314,12 @@ Semantic findings use the diagnostic shape where possible, but their gate is `review` unless a later VRS decision makes a specific semantic rule blocking. Review mode must not write files or silently apply fixes. -Any `axe vrs review` or fixture-review mode that calls a real provider and +Any `intent review` or fixture-review mode that calls a real provider and spends model tokens is manual-only. It must not be part of CI, Nix checks, pre-commit hooks, scheduled jobs, or default automated validation. Automated validation may cover deterministic fixture shape and fake-provider invocation only. The command does not require an additional token-spend confirmation flag; -invoking `axe vrs review` is the explicit operator action. The mechanical guard +invoking `intent review` is the explicit operator action. The mechanical guard is that the command fails before provider invocation when it detects CI or other known automated environments. @@ -333,7 +333,7 @@ not imply a nonzero exit code unless a future explicit fail policy is added. ## Fixture Review Grading -`axe vrs review-fixtures` is the runner for the semantic-review fixtures owned by +`intent review-fixtures` is the runner for the semantic-review fixtures owned by [intent/15-evaluation](../../intent/15-evaluation/spec.md). It exists so the minimum-assertion contract is executable rather than descriptive. @@ -343,7 +343,7 @@ For each selected fixture it: and `schema_ref`, so the graded run uses the assets the fixture claims; 2. materializes the fixture's `input/` tree into an isolated temporary workspace, leaving the tracked corpus untouched; -3. runs the same review invocation as `axe vrs review` with that workspace as +3. runs the same review invocation as `intent review` with that workspace as both the review root and the coding-agent working directory, which makes the fixture-relative artifact paths in `assertions.json` the paths a review result reports; @@ -364,7 +364,7 @@ review could not be run at all. Fixture review spends model tokens whenever it is pointed at a real backend, so it carries the same manual-only policy and the same automated-context refusal as -`axe vrs review`, and it adds no token-spend flag. Automated coverage uses +`intent review`, and it adds no token-spend flag. Automated coverage uses fake/probe providers. ## Failure Behavior @@ -387,7 +387,7 @@ fake/probe providers. Plan may record: -- `axe vrs check --json` output as evidence; +- `intent check --json` output as evidence; - proposed VRS patches as review/proposed-patch records; - resolved durable learning routed to VRS artifacts. @@ -397,8 +397,8 @@ around VRS changes; `vrs-check` and meta-VRS keep semantic ownership. ## Anti-Goals - Do not create a competing top-level `vrs` CLI until there is evidence that - non-Axe users need it. -- Do not make Axe the authority for VRS semantics. + users need one separate from `intent`. +- Do not make the CLI the authority for VRS semantics. - Do not make generated graph JSON authoritative. - Do not make warning-mode rules permanent. - Do not silently rewrite VRS artifacts.