From 95f49e25690c6deedd0e19339e7f1d80f4978e32 Mon Sep 17 00:00:00 2001 From: Victor Nyberg Date: Sun, 9 Aug 2026 20:56:23 +0200 Subject: [PATCH] Use Intent as the canonical system name --- .github/workflows/ci.yml | 24 +- .gitignore | 3 + README.md | 2 +- .../0001-use-per-backend-review-readiness.md | 14 +- ...001-claude-real-provider-review-pending.md | 26 +- .../caic-semantic-review-prototype.md | 62 ++--- context/cli/requirements.md | 97 +++---- context/cli/spec.md | 130 +++++----- crates/intent/Cargo.lock | 2 +- crates/intent/Cargo.toml | 4 +- crates/intent/README.md | 48 ++-- crates/intent/src/lib.rs | 241 +++++++++--------- crates/intent/src/main.rs | 7 +- .../tests/{vrs_check.rs => intent_check.rs} | 98 +++---- flake.nix | 4 +- ...ecision-records-with-pr-local-proposals.md | 6 +- ...-child-intent-nodes-by-formal-contract.md} | 14 +- ...use-delta-directory-for-open-divergence.md | 6 +- .../0004-open-deltas-may-exist-on-main.md | 4 +- ...add-constraints-section-to-requirements.md | 4 +- ...007-common-subsystems-not-generic-files.md | 10 +- .../0008-review-smells-live-in-meta-vrs.md | 31 --- ...iew-smells-live-in-root-intent-contract.md | 31 +++ ...se-open-questions-for-drafting-coverage.md | 6 +- .../0010-validate-load-bearing-assumptions.md | 8 +- ...-require-evidence-options-and-tradeoffs.md | 10 +- .../0012-vrs-is-the-intent-layer.md | 30 --- ...ntent-is-the-intent-interview-procedure.md | 33 +++ ...rill-vrs-is-the-vrs-interview-procedure.md | 33 --- ...valuate-intent-with-isolated-scenarios.md} | 14 +- ...lossary-handling-lives-in-grill-intent.md} | 10 +- ...-existing-intent-systems-as-references.md} | 8 +- ...se-narrow-intent-enforcement-subsystem.md} | 14 +- .../0018-identifiers-are-commit-scoped.md | 16 +- ...f-enforcement-with-deterministic-subset.md | 8 +- ...20-keep-structured-intent-roadmap-only.md} | 14 +- ...omote-link-checks-before-decision-shape.md | 6 +- ...pe-decision-shape-to-root-intent-first.md} | 16 +- ...n-semantic-review-assets-in-enforcement.md | 32 +-- ...-semantic-review-fixtures-in-evaluation.md | 24 +- ...start-semantic-review-with-smell-matrix.md | 10 +- ...review-fixtures-deterministically-first.md | 8 +- ...sertions-for-real-semantic-review-evals.md | 2 +- .../0028-real-token-evals-are-manual-only.md | 2 +- ...29-no-extra-token-spend-flag-for-review.md | 8 +- ...0030-keep-enforcement-consumer-agnostic.md | 24 +- ...ams-use-full-mermaid-previewer-advisory.md | 2 +- ...32-rename-glossary-artifact-to-ontology.md | 14 +- ...ocal-citation-carries-the-qualification.md | 2 +- ...l-exit-is-enforced-at-merge-not-relaxed.md | 6 +- ...-with-a-fresh-init-not-filtered-history.md | 37 +-- .../0036-use-intent-as-the-only-layer-name.md | 48 ++++ .../decision-shape-enforcement.md | 16 +- .../link-structure-and-symbolic-references.md | 22 +- intent/01-vision/requirements.md | 16 +- intent/01-vision/spec.md | 2 +- intent/02-requirements/requirements.md | 30 +-- intent/02-requirements/spec.md | 6 +- intent/03-spec/requirements.md | 18 +- intent/03-spec/spec.md | 2 +- .../.experiments/ontology-sota-survey.md | 34 +-- intent/04-ontology/requirements.md | 22 +- intent/04-ontology/spec.md | 4 +- intent/05-intuition/requirements.md | 18 +- intent/05-intuition/spec.md | 2 +- intent/06-decisions/requirements.md | 30 +-- intent/06-decisions/spec.md | 6 +- intent/07-experiments/requirements.md | 18 +- intent/07-experiments/spec.md | 12 +- intent/08-reference/requirements.md | 16 +- intent/08-reference/spec.md | 6 +- ...exit-is-unenforced-and-already-violated.md | 8 +- intent/09-delta/requirements.md | 24 +- intent/09-delta/spec.md | 16 +- intent/10-open-questions/requirements.md | 24 +- intent/10-open-questions/spec.md | 8 +- intent/11-roadmap/requirements.md | 18 +- intent/11-roadmap/spec.md | 6 +- intent/12-common-subsystems/requirements.md | 24 +- intent/12-common-subsystems/spec.md | 6 +- intent/13-review-smells/requirements.md | 20 +- intent/13-review-smells/spec.md | 14 +- intent/14-grill-intent/requirements.md | 37 +++ .../{14-grill-vrs => 14-grill-intent}/spec.md | 18 +- intent/14-grill-vrs/requirements.md | 37 --- intent/15-evaluation/requirements.md | 30 +-- .../semantic-review/fixture-format.md | 24 +- .../requirements-mechanism/assertions.json | 4 +- .../expected-review.json | 6 +- .../requirements-mechanism/fixture.json | 4 +- .../requirements-mechanism/requirements.md | 2 +- .../spec-rationale/assertions.json | 4 +- .../spec-rationale/expected-review.json | 4 +- .../spec-rationale/fixture.json | 4 +- .../stale-delta/assertions.json | 4 +- .../stale-delta/expected-review.json | 4 +- .../semantic-review/stale-delta/fixture.json | 4 +- .../DELTA-001-review-command-missing.md | 6 +- .../semantic-review/stale-delta/notes.md | 2 +- .../stale-open-question/assertions.json | 4 +- .../stale-open-question/expected-review.json | 4 +- .../stale-open-question/fixture.json | 4 +- .../vision-mechanism/assertions.json | 4 +- .../vision-mechanism/expected-review.json | 4 +- .../vision-mechanism/fixture.json | 4 +- intent/15-evaluation/spec.md | 32 +-- .../2026-06-19-real-provider-review-eval.md | 30 ++- .../2026-06-19-codex-review.json | 127 --------- intent/16-enforcement/requirements.md | 40 +-- intent/16-enforcement/review-prompt.md | 22 +- .../16-enforcement/review-result.schema.json | 8 +- intent/16-enforcement/spec.md | 54 ++-- intent/intuition.md | 22 +- intent/ontology.md | 38 +-- intent/requirements.md | 104 ++++---- intent/roadmap.md | 20 +- intent/spec.md | 110 ++++---- intent/vision.md | 32 +-- skills/intent.md | 15 +- 119 files changed, 1274 insertions(+), 1359 deletions(-) rename crates/intent/tests/{vrs_check.rs => intent_check.rs} (83%) rename intent/.decisions/{0002-order-child-vrs-nodes-by-formal-contract.md => 0002-order-child-intent-nodes-by-formal-contract.md} (60%) delete mode 100644 intent/.decisions/0008-review-smells-live-in-meta-vrs.md create mode 100644 intent/.decisions/0008-review-smells-live-in-root-intent-contract.md delete mode 100644 intent/.decisions/0012-vrs-is-the-intent-layer.md create mode 100644 intent/.decisions/0013-grill-intent-is-the-intent-interview-procedure.md delete mode 100644 intent/.decisions/0013-grill-vrs-is-the-vrs-interview-procedure.md rename intent/.decisions/{0014-evaluate-vrs-with-isolated-scenarios.md => 0014-evaluate-intent-with-isolated-scenarios.md} (63%) rename intent/.decisions/{0015-glossary-handling-lives-in-grill-vrs.md => 0015-glossary-handling-lives-in-grill-intent.md} (64%) rename intent/.decisions/{0016-use-existing-vrs-systems-as-references.md => 0016-use-existing-intent-systems-as-references.md} (72%) rename intent/.decisions/{0017-use-narrow-vrs-enforcement-subsystem.md => 0017-use-narrow-intent-enforcement-subsystem.md} (68%) rename intent/.decisions/{0020-keep-structured-vrs-roadmap-only.md => 0020-keep-structured-intent-roadmap-only.md} (76%) rename intent/.decisions/{0022-scope-decision-shape-to-meta-vrs-first.md => 0022-scope-decision-shape-to-root-intent-first.md} (77%) create mode 100644 intent/.decisions/0036-use-intent-as-the-only-layer-name.md create mode 100644 intent/14-grill-intent/requirements.md rename intent/{14-grill-vrs => 14-grill-intent}/spec.md (61%) delete mode 100644 intent/14-grill-vrs/requirements.md delete mode 100644 intent/16-enforcement/.experiments/real-provider-reports/2026-06-19-codex-review.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ddec9ef..cbfefb6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,12 +29,26 @@ jobs: - run: cargo build --locked --manifest-path crates/intent/Cargo.toml - run: cargo test --locked --manifest-path crates/intent/Cargo.toml - # Port of dotfiles' `axe-vrs-context-strict`. + # Strict validation of the repository's Intent corpus. corpus-strict: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - # `crates/intent` is a standalone package with no workspace root, so cargo + + - name: retired name is absent + run: | + set -euo pipefail + retired="$(printf '\166\162\163')" + if git grep -I -n -i "$retired" -- .; then + echo "::error::retired name found in tracked content" + exit 1 + fi + if git ls-files | grep -i "$retired"; then + echo "::error::retired name found in a tracked path" + exit 1 + fi + + # `crates/intent` is a standalone package with no workspace root, so cargo # writes to `crates/intent/target/` and the steps below would not find the # binary at `./target/`. `--target-dir` pins the output next to the checkout # root regardless of whether a workspace root ever appears above the crate. @@ -42,7 +56,7 @@ jobs: - name: corpus is present # `intent check` exits 0 on an empty directory and on a directory holding no - # VRS artifacts, so "the check passed" cannot by itself distinguish a healthy + # Intent artifacts, so "the check passed" cannot by itself distinguish a healthy # corpus from a missing one. Fail on absence explicitly, before checking. run: | set -euo pipefail @@ -55,7 +69,7 @@ jobs: cat report.json >&2; exit 1; } jq -e ' - .schema_version == "axe.vrs.check.v1" + .schema_version == "axe.intent.check.v1" and .profile == "strict" and (.diagnostics | length) == 0 ' report.json > /dev/null @@ -73,7 +87,7 @@ jobs: jq -e '(.nodes | length) > 0' graph.json > /dev/null \ || { echo "::error::strict check examined 0 artifacts — wrong path or empty corpus"; exit 1; } - # Port of dotfiles' `vrs-semantic-review-fixtures`. + # Validate the semantic-review fixture corpus and enforcement schema. semantic-review-fixtures: runs-on: ubuntu-latest steps: diff --git a/.gitignore b/.gitignore index 7f087a1..a52ecc3 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ # otherwise, since the crate is a standalone package with no workspace root. target/ +# Local scratch artifacts and render intermediates. +/tmp/ + # Artifacts the CI steps write into the checkout root while running. /report.json /graph.json diff --git a/README.md b/README.md index 17ded8d..84c9486 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ intent tree with its own `requirements.md` and `spec.md`. | `11-roadmap` | `roadmap.md` — directions under consideration, not a plan | | `12-common-subsystems` | recurring subsystem shapes worth naming once | | `13-review-smells` | what a reviewer should look for in an intent tree | -| `14-grill-vrs` | the procedure for interrogating a tree until it holds up | +| `14-grill-intent` | the procedure for interrogating a tree until it holds up | | `15-evaluation` | isolated evaluation runs and their fixtures | | `16-enforcement` | the rules a checker can enforce mechanically | diff --git a/context/cli/.decisions/0001-use-per-backend-review-readiness.md b/context/cli/.decisions/0001-use-per-backend-review-readiness.md index af824f9..2847cfe 100644 --- a/context/cli/.decisions/0001-use-per-backend-review-readiness.md +++ b/context/cli/.decisions/0001-use-per-backend-review-readiness.md @@ -4,19 +4,19 @@ Status: accepted ## Context -`axe vrs review` can run through multiple stock CAIC backends. Manual +`intent review` can run through multiple stock CAIC backends. Manual real-provider evals showed uneven provider state: `codex` produced a -schema-valid VRS review report for `context/vrs/16-enforcement`, while `claude` +schema-valid Intent review report for `context/intent/16-enforcement`, while `claude` still needs an authenticated isolated real-provider report after fixing its wrapper-level command mapping. -The design question was whether one provider gap should keep the whole `axe vrs +The design question was whether one provider gap should keep the whole `intent review` surface marked not production-ready. ## Evidence and Argument CAIC already exposes explicit backend ids and reports the effective backend in -result metadata. `axe vrs review` now preflights the selected backend through +result metadata. `intent review` now preflights the selected backend through `$CODING_AGENT capabilities --json` before provider invocation, so readiness can be evaluated against the same contract for each backend. @@ -35,14 +35,14 @@ backend on an unrelated provider authentication/eval gap. ## Decision -`axe vrs review` production readiness is backend-scoped. +`intent review` production readiness is backend-scoped. A backend is ready when: - its CAIC capability preflight satisfies the review contract; - token-free fake-provider tests cover its provider-specific command mapping; -- at least one bounded manual real-provider run against a small existing VRS - subsystem writes a schema-valid `axe.vrs.review.v1` report. +- at least one bounded manual real-provider run against a small existing Intent + subsystem writes a schema-valid `axe.intent.review.v1` report. ## Consequences diff --git a/context/cli/.delta/DELTA-001-claude-real-provider-review-pending.md b/context/cli/.delta/DELTA-001-claude-real-provider-review-pending.md index a781e72..82c8b67 100644 --- a/context/cli/.delta/DELTA-001-claude-real-provider-review-pending.md +++ b/context/cli/.delta/DELTA-001-claude-real-provider-review-pending.md @@ -4,14 +4,14 @@ Status: open ## Divergence -`axe vrs review` is implemented and covered by fake-provider tests. Production +`intent review` is implemented and covered by fake-provider tests. Production readiness is tracked per backend: the stock `codex` path has produced a -semantic review report for a small VRS subsystem, while the stock `claude` path +semantic review report for a small Intent subsystem, while the stock `claude` path still lacks an authenticated isolated real-provider report. -## VRS +## Intent -- [spec.md](../spec.md) defines `axe vrs review` backend readiness as +- [spec.md](../spec.md) defines `intent review` backend readiness as backend-scoped. - [0001-use-per-backend-review-readiness.md](../.decisions/0001-use-per-backend-review-readiness.md) records the readiness policy. @@ -29,12 +29,12 @@ still lacks an authenticated isolated real-provider report. ## Evidence - Improved CAIC provider-failure diagnostics exposed Codex native schema - compatibility issues in the baked `axe.vrs.review.v1` schema. + compatibility issues in the baked `axe.intent.review.v1` schema. - After adding explicit string types and requiring `gate`, - `axe vrs review context/vrs/16-enforcement --backend codex + `intent review context/intent/16-enforcement --backend codex --timeout-seconds 180 --report ...` succeeded and wrote an - `axe.vrs.review.v1` report. -- `axe vrs review context/vrs/16-enforcement --backend claude + `axe.intent.review.v1` report. +- `intent review context/intent/16-enforcement --backend claude --timeout-seconds 180 --report ...` failed with CAIC `timeout` before writing a report. - Follow-up wrapper inspection found that the Claude command path passed @@ -52,15 +52,15 @@ still lacks an authenticated isolated real-provider report. `ANTHROPIC_API_KEY` is present. The wrapper timeout class is covered by fake provider tests; the full real Claude report still requires API-key-backed isolated auth. -- The VRS/Axe decision is to treat review production readiness per backend +- The Intent/CLI decision is to treat review production readiness per backend rather than requiring every stock backend to pass before a proven backend can be used. ## Required Reconciliation -- `axe vrs review --backend claude` should complete a bounded manual - real-provider eval against a small existing VRS subsystem using isolated auth - and write an `axe.vrs.review.v1` report. +- `intent review --backend claude` should complete a bounded manual + real-provider eval against a small existing Intent subsystem using isolated auth + and write an `axe.intent.review.v1` report. - The successful Claude eval evidence should be captured under the relevant `.experiments/` directory before this delta is removed. - This delta does not block `codex` readiness. It blocks claiming Claude @@ -73,5 +73,5 @@ update implementation ## Resolution Signal Delete this delta when a bounded manual `claude` run writes a schema-valid -`axe.vrs.review.v1` report for a small existing VRS subsystem, and that report +`axe.intent.review.v1` report for a small existing Intent subsystem, and that report is captured under the owning `.experiments/` directory. diff --git a/context/cli/.experiments/caic-semantic-review-prototype.md b/context/cli/.experiments/caic-semantic-review-prototype.md index d09acd5..8a11c0f 100644 --- a/context/cli/.experiments/caic-semantic-review-prototype.md +++ b/context/cli/.experiments/caic-semantic-review-prototype.md @@ -2,16 +2,16 @@ Date: 2026-06-18 -Current status: superseded by the implemented `axe vrs review` command, the -baked assets in `context/vrs/16-enforcement/`, and the real-provider eval in -`context/vrs/16-enforcement/.experiments/2026-06-19-real-provider-review-eval.md`. +Current status: superseded by the implemented `intent review` command, the +baked assets in `context/intent/16-enforcement/`, and the real-provider eval in +`context/intent/16-enforcement/.experiments/2026-06-19-real-provider-review-eval.md`. Keep this document as historical prototype evidence, not as current remaining work. ## Question -Can `axe vrs review` use the Coding Agent Invocation Contract (CAIC) cleanly for -semantic review while keeping deterministic `axe vrs` primitives as the first +Can `intent review` use the Coding Agent Invocation Contract (CAIC) cleanly for +semantic review while keeping deterministic `intent` primitives as the first production milestone? ## Method @@ -19,8 +19,8 @@ production milestone? The prototype used the implemented `coding-agent` binary with a fake Codex provider. The temporary scenario contained: -- a small VRS node with `requirements.md` and `spec.md`; -- a generated `axe vrs check` diagnostics artifact; +- a small Intent node with `requirements.md` and `spec.md`; +- a generated `intent check` diagnostics artifact; - a candidate baked review prompt; - a task-specific JSON Schema for the review result. @@ -29,24 +29,24 @@ The command shape was: ```text $CODING_AGENT run \ --cwd \ - --prompt-file \ - --context-file normative: \ - --context-file normative: \ - --context-file generated-diagnostics: \ + --prompt-file \ + --context-file normative: \ + --context-file normative: \ + --context-file generated-diagnostics: \ --mode review \ --permission read-only \ --approval never \ --config-policy isolated \ --network-policy disabled \ --output-format json \ - --output-schema \ + --output-schema \ --backend codex ``` Candidate prompt shape: ```text -You are running `axe vrs review`. Review only the supplied VRS artifacts and +You are running `intent review`. Review only the supplied Intent artifacts and diagnostics. Return JSON matching the schema. Do not propose file edits. ``` @@ -58,7 +58,7 @@ Candidate schema shape: "type": "object", "required": ["schema_version", "summary", "findings"], "properties": { - "schema_version": { "const": "axe.vrs.review.v1" }, + "schema_version": { "const": "axe.intent.review.v1" }, "summary": { "type": "string" }, "findings": { "type": "array", @@ -90,7 +90,7 @@ Candidate schema shape: The CAIC route worked with the fake provider. The adapter: -- accepted workspace VRS files as `normative` context; +- accepted workspace Intent files as `normative` context; - accepted an outside diagnostics file only when its JSON had a generated artifact marker (`schema_version` or `producer`); - invoked the backend in `review`, `read-only`, `approval never`, @@ -103,13 +103,13 @@ The successful inner result was: ```json { - "schema_version": "axe.vrs.review.v1", + "schema_version": "axe.intent.review.v1", "summary": "1 semantic concern found", "findings": [ { - "rule": "VRS.REVIEW.spec.actionability", + "rule": "INTENT.REVIEW.spec.actionability", "severity": "warning", - "artifact": "context/vrs/spec.md", + "artifact": "context/intent/spec.md", "evidence": "Spec uses vague language: should be good and flexible.", "suggested_fix": "Replace vague qualities with observable behavior and constraints." } @@ -135,36 +135,36 @@ machine-readable generated marker, CAIC failed before provider execution: } ``` -This is desirable for `axe vrs review`: the checker output must be a generated +This is desirable for `intent review`: the checker output must be a generated artifact, not an arbitrary host file smuggled into review context. ## Tradeoffs | Option | Result | | --- | --- | -| Implement `axe vrs review` now | CAIC is ready enough, but the deterministic checker, baked prompt file, and review schema are not yet production-shaped. This would couple review quality to unstable inputs. | +| Implement `intent review` now | CAIC is ready enough, but the deterministic checker, baked prompt file, and review schema are not yet production-shaped. This would couple review quality to unstable inputs. | | Keep review experimental until primitives exist | Preserves the accepted implementation order and gives review a bounded diagnostics packet later. Delays semantic smells, but avoids noisy or ungrounded review output. | | Add only hidden/prototype review command | Useful for local tuning, but risks an untracked command contract unless it is clearly excluded from public docs and CI. | ## Conclusion -Keep production `axe vrs` focused on deterministic primitives first. In -parallel, create the baked semantic-review assets under VRS ownership: +Keep production `intent` focused on deterministic primitives first. In +parallel, create the baked semantic-review assets under Intent ownership: -- `context/vrs/16-enforcement/review-prompt.md` or a sibling prompt artifact +- `context/intent/16-enforcement/review-prompt.md` or a sibling prompt artifact with the review rubric; -- `context/vrs/16-enforcement/review-result.schema.json` for - `axe.vrs.review.v1`; -- evaluation fixtures under `context/vrs/15-evaluation/` that tune the prompt - against known good and bad VRS examples. +- `context/intent/16-enforcement/review-result.schema.json` for + `axe.intent.review.v1`; +- evaluation fixtures under `context/intent/15-evaluation/` that tune the prompt + against known good and bad Intent examples. -Once `axe vrs check --json` emits stable diagnostics, `axe vrs review` should +Once `intent check --json` emits stable diagnostics, `intent review` should compose those diagnostics with the prompt/schema and call CAIC exactly through the command route above. -## VRS Impact +## Intent Impact -This prototype informed the current Axe VRS review command, the baked -semantic-review prompt and schema owned by `context/vrs/16-enforcement`, and the +This prototype informed the current Intent CLI review command, the baked +semantic-review prompt and schema owned by `context/intent/16-enforcement`, and the manual-only real-provider eval policy. It is historical evidence only; current readiness state lives in the spec, decisions, deltas, and real-provider evals. diff --git a/context/cli/requirements.md b/context/cli/requirements.md index ab2350c..f0df1a4 100644 --- a/context/cli/requirements.md +++ b/context/cli/requirements.md @@ -1,111 +1,112 @@ -# Requirements: Axe VRS +# Requirements: Intent CLI ## Context -This document defines testable constraints for `axe vrs`, the Axe command family -for VRS hygiene, graph extraction, and enforcement diagnostics. It builds on -[../requirements.md](../requirements.md) and the meta-VRS enforcement contract in -[context/vrs/16-enforcement](../../../vrs/16-enforcement/). +This document defines testable constraints for the `intent` CLI: Intent hygiene, +graph extraction, and enforcement diagnostics. It builds on the enforcement contract in +[intent/16-enforcement](../../intent/16-enforcement/). + +The `AXE.INTENT-*` requirement namespace is a stable document identifier carried +from the originating CLI contract; it does not name an executable command. ## Assumptions -- **A01 VRS owns semantics:** The meta-VRS in [context/vrs](../../../vrs/) +- **A01 Intent owns semantics:** The root contract in [intent](../../intent/) owns artifact semantics, file contracts, review smells, and enforcement rules. -- **A02 Axe owns operator ergonomics:** `axe vrs` gives humans and agents one - discoverable command surface for VRS checks without making Axe the VRS - authority. +- **A02 CLI owns operator ergonomics:** `intent` gives humans and agents one + discoverable command surface for Intent checks without making the CLI the + Intent authority. - **A03 Checks need multiple surfaces:** Agents need interactive diagnostics and JSON; CI needs deterministic exit codes; future planning needs evidence links. - **A04 Markdown remains authoritative:** Early tooling parses Markdown-authored - VRS artifacts and may emit derived graph JSON, but generated graph output is + Intent artifacts and may emit derived graph JSON, but generated graph output is not the source of truth. -- **A05 Portable agent invocation:** Semantic VRS review can invoke a coding - agent through the portable - [Coding Agent Invocation Contract](../../22-invocation-contract/requirements.md) - instead of binding directly to a provider CLI. +- **A05 Portable agent invocation:** Semantic Intent review can invoke a coding + agent through the portable Coding Agent Invocation Contract from the + originating repository instead of binding directly to a provider CLI. ## Acceptable Tradeoffs -- **T01 Axe subcommand over top-level CLI:** Using `axe vrs` is acceptable - because coding agents already use Axe as the operator surface, but the checker - engine must remain separable from Axe command parsing. +- **T01 Shared CLI surface:** A top-level `intent` command minimizes indirection, + while the reusable library keeps the checker available to other integrations + without duplicating CLI behavior. - **T02 Warning mode during migration:** Warning-mode checks are acceptable only as a calibrated migration state that later becomes blocking or is removed. - **T03 Partial graph first:** The first graph model may cover only IDs, links, - artifact ownership, and rule diagnostics rather than a complete typed VRS + artifact ownership, and rule diagnostics rather than a complete typed Intent source model. ## Requirements ### Must Preserve Authority Boundaries -- **AXE.VRS-R01 VRS authority:** `axe vrs` must consume the meta-VRS contract; it +- **AXE.INTENT-R01 Intent authority:** `intent` must consume the root Intent contract; it must not define artifact semantics independently. -- **AXE.VRS-R02 Checker engine boundary:** Deterministic parsing, graph +- **AXE.INTENT-R02 Checker engine boundary:** Deterministic parsing, graph extraction, rule evaluation, and diagnostics must live in a reusable checker - engine that can be called by Axe and by Nix checks. -- **AXE.VRS-R03 No hidden rewrites:** `axe vrs` must not silently rewrite VRS + engine that can be called by the CLI and by Nix checks. +- **AXE.INTENT-R03 No hidden rewrites:** `intent` must not silently rewrite Intent files. Any repair mode must be explicit, previewable, and scoped. -- **AXE.VRS-R04 Nix owns blocking gates:** Merge-blocking enforcement runs - through repo checks that call the same checker engine; Axe is the operator UX, +- **AXE.INTENT-R04 Nix owns blocking gates:** Merge-blocking enforcement runs + through repo checks that call the same checker engine; the CLI is the operator UX, not the CI authority. ### Must Provide Agent-Friendly Commands -- **AXE.VRS-R05 Check command:** `axe vrs check [path]` must run deterministic - VRS hygiene checks and return problems-first human output plus +- **AXE.INTENT-R05 Check command:** `intent check [path]` must run deterministic + Intent hygiene checks and return problems-first human output plus schema-versioned JSON. -- **AXE.VRS-R06 Link command:** `axe vrs links [path]` must inspect local +- **AXE.INTENT-R06 Link command:** `intent links [path]` must inspect local Markdown links, mechanically resolvable anchors, wiki-style references, and broken or ambiguous targets. -- **AXE.VRS-R07 ID command:** `axe vrs ids [path]` must inspect ID definitions, +- **AXE.INTENT-R07 ID command:** `intent ids [path]` must inspect ID definitions, declared scopes, duplicates, legacy syntax, bare-ID ambiguity, and cross-node reference ownership. -- **AXE.VRS-R08 Graph command:** `axe vrs graph [path] --json` must emit the - derived VRS graph for tools and agents without treating that graph as +- **AXE.INTENT-R08 Graph command:** `intent graph [path] --json` must emit the + derived Intent graph for tools and agents without treating that graph as authoritative source. -- **AXE.VRS-R09 Doctor command:** `axe vrs doctor` must summarize checker +- **AXE.INTENT-R09 Doctor command:** `intent doctor` must summarize checker version, rule-set version, repository scope, migration status, allowlist status, and known blocking/warning counts. ### Must Support Enforcement Ratchets -- **AXE.VRS-R10 Warning exit criteria:** Warning-mode rules must report the +- **AXE.INTENT-R10 Warning exit criteria:** Warning-mode rules must report the migration condition that prevents strict mode and the condition that promotes the rule to blocking or deletes it. -- **AXE.VRS-R11 Rule stability:** Diagnostics must include stable rule IDs, +- **AXE.INTENT-R11 Rule stability:** Diagnostics must include stable rule IDs, severity, gate mode, artifact path, owner, evidence, and suggested fix. -- **AXE.VRS-R12 Scoped execution:** Commands must support checking a specific - VRS node, a subtree, or the whole repo so agents can run fast local checks +- **AXE.INTENT-R12 Scoped execution:** Commands must support checking a specific + Intent node, a subtree, or the whole repo so agents can run fast local checks while editing. -- **AXE.VRS-R13 Evaluation feedback:** False positives and ambiguous diagnostics - must be reproducible as isolated VRS evaluation fixtures before rules become +- **AXE.INTENT-R13 Evaluation feedback:** False positives and ambiguous diagnostics + must be reproducible as isolated Intent evaluation fixtures before rules become blocking. ### Must Compose With Planning Later -- **AXE.VRS-R14 Plan evidence:** Plan integration may attach VRS diagnostics and - graph snapshots as plan evidence, but Plan must not own VRS checking +- **AXE.INTENT-R14 Plan evidence:** Plan integration may attach Intent diagnostics and + graph snapshots as plan evidence, but Plan must not own Intent checking semantics. -- **AXE.VRS-R15 Proposed fixes:** Future planning or review workflows may carry - proposed VRS patches, but accepted truth still lands in the owning VRS +- **AXE.INTENT-R15 Proposed fixes:** Future planning or review workflows may carry + proposed Intent patches, but accepted truth still lands in the owning Intent artifact. ### Must Support Semantic Review -- **AXE.VRS-R16 Review command:** `axe vrs review [path]` must run semantic VRS +- **AXE.INTENT-R16 Review command:** `intent review [path]` must run semantic Intent review through the portable Coding Agent Invocation Contract rather than binding to a provider-specific CLI. The command must fail before provider invocation when it detects CI or another known automated environment. -- **AXE.VRS-R17 Baked review prompt:** The VRS semantic review prompt and output - schema must be owned by VRS/Axe docs and eval-tuned; callers must not provide +- **AXE.INTENT-R17 Baked review prompt:** The Intent semantic review prompt and output + schema must be owned by Intent/CLI docs and eval-tuned; callers must not provide arbitrary prompt files for this command. -- **AXE.VRS-R18 Review-only safety:** `axe vrs review` must invoke the coding - agent in read-only review mode by default and must not mutate VRS artifacts. -- **AXE.VRS-R19 Fixture review grading:** `axe vrs review-fixtures [path]` must +- **AXE.INTENT-R18 Review-only safety:** `intent review` must invoke the coding + agent in read-only review mode by default and must not mutate Intent artifacts. +- **AXE.INTENT-R19 Fixture review grading:** `intent review-fixtures [path]` must run semantic review against an isolated materialized copy of each selected semantic-review fixture and grade the returned result against that fixture's minimum finding assertions by `rule`, `severity`, `artifact`, and `owner`. It must not require matching summary, evidence, or suggested-fix wording, must report which assertions were unmet, and must obey the same automated-context - refusal as `axe vrs review` without adding a token-spend flag. + refusal as `intent review` without adding a token-spend flag. diff --git a/context/cli/spec.md b/context/cli/spec.md index c5e6d00..59de585 100644 --- a/context/cli/spec.md +++ b/context/cli/spec.md @@ -1,4 +1,4 @@ -# Spec: intent CLI +# Spec: Intent CLI This document specifies the `intent` command realization. It builds on [requirements.md](./requirements.md). @@ -12,18 +12,18 @@ Draft. Defines: - `intent` command surface; -- routing between the CLI, the VRS checker engine, Nix checks, and future Plan +- routing between the CLI, the Intent checker engine, Nix checks, and future Plan evidence; -- output schema and migration-ratchet behavior for deterministic VRS checks; +- output schema and migration-ratchet behavior for deterministic Intent checks; - semantic review routing through the portable Coding Agent Invocation Contract. Does not define: -- VRS artifact semantics, file contracts, review smells, or enforcement rules; +- Intent artifact semantics, file contracts, review smells, or enforcement rules; see [intent](../../intent/) and [intent/16-enforcement](../../intent/16-enforcement/); - semantic LLM review rubric content beyond routing diagnostics; -- future typed-source VRS authoring; +- future typed-source Intent authoring; - Plan storage or workflow semantics. ## Architecture @@ -31,25 +31,25 @@ Does not define: ```text human / coding agent / repo check -> intent - -> vrs-check engine - -> parse Markdown VRS artifacts + -> intent-check engine + -> parse Markdown Intent artifacts -> derive graph view -> run deterministic rules -> emit diagnostics Nix checks - -> vrs-check engine + -> intent-check engine -> blocking exit code for strict rules intent review - -> vrs-check engine diagnostics + -> intent-check engine diagnostics -> Coding Agent Invocation Contract -> provider backend in read-only review mode -> schema-validated semantic findings ``` `intent` is an operator and agent UX. The checker engine is the reusable -implementation boundary. Meta-VRS remains the semantic authority. +implementation boundary. The root Intent contract remains the semantic authority. ## Command Surface @@ -60,32 +60,32 @@ intent review [path] [--profile local|strict] [--backend ] [--coding-agent < intent review-fixtures [path] [--fixture ]... [--backend ] [--coding-agent ] [--json] [--report ] ``` -Default `path` is `context/vrs`, and -`context/vrs/15-evaluation/semantic-review` for `review-fixtures`. The first +Default `path` is the current directory, and +`./15-evaluation/semantic-review` for `review-fixtures`. The first implemented surfaces are `check`, `graph`, `review`, and `review-fixtures`; `links`, `ids`, and `doctor` remain target surfaces for later implementation -slices. Commands discover VRS nodes by walking for -`requirements.md`, `spec.md`, known companion directories, and -meta-VRS-supported child node shapes. +slices. Commands discover Intent nodes by walking for +`requirements.md`, `spec.md`, known companion directories, and child node shapes +supported by the root Intent contract. ## Authority Routing | Command | Route | Authority | | --- | --- | --- | -| `vrs check` | checker engine deterministic rules | Meta-VRS defines rules; checker evaluates | -| `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/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 | +| `intent check` | checker engine deterministic rules | Root Intent contract defines rules; checker evaluates | +| `intent links` | checker engine link pass | Git working tree/current commit | +| `intent ids` | checker engine ID pass | Root Intent identifier contract | +| `intent graph` | checker engine graph extraction | Markdown Intent artifacts are source; graph is derived | +| `intent review` | checker diagnostics plus `$CODING_AGENT` review invocation | Intent/CLI own prompt and schema; Coding Agent Invocation Contract owns provider portability | +| `intent review-fixtures` | same review invocation over a materialized fixture copy, graded against fixture assertions | Intent evaluation owns fixtures and assertion semantics; the CLI owns the runner | +| `intent doctor` | CLI 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 `intent` CLI. It owns: -- filesystem discovery of VRS nodes; +- filesystem discovery of Intent nodes; - Markdown parsing needed for deterministic rules; - ID definition and reference extraction; - local Markdown link and anchor resolution; @@ -96,11 +96,10 @@ The checker engine should be callable without the `intent` CLI. It owns: The CLI owns: -- CLI argument parsing; +- subcommand and argument parsing; - problems-first human rendering; -- stable command names and completion; -- command telemetry; -- exit-code mapping for operator commands. +- schema-versioned machine output; +- exit-code mapping. Nix owns: @@ -135,11 +134,11 @@ Every command that reports findings emits the same diagnostic object in JSON: ```json { - "schema_version": "axe.vrs.diagnostic.v1", - "rule": "VRS.ENF.link.local-target", + "schema_version": "axe.intent.diagnostic.v1", + "rule": "INTENT.ENF.link.local-target", "severity": "warning", "gate": "transitional | blocking | advisory | review", - "artifact": "context/vrs/spec.md", + "artifact": "context/intent/spec.md", "owner": "16-enforcement", "range": { "line": 42, "column": 1 }, "evidence": "Link target does not exist: ./missing.md", @@ -168,27 +167,27 @@ finding is a local advisory, a migration warning, or a merge blocker. ## Initial Rule Set -The first implementation calls a narrow meta-VRS enforcement subset: +The first implementation calls a narrow subset of root Intent enforcement rules: 1. local Markdown `.md` link existence; -2. strict decision-record shape for `context/vrs/.decisions/`. +2. strict decision-record shape for `context/intent/.decisions/`. Local link findings are transitional warnings in the `local` profile and -blocking in the `strict` profile once the known corpus is clean. Meta-VRS -decision-shape findings are blocking for the meta-VRS scope because the current -meta-VRS decisions have been migrated to that shape. ID, wiki-link, delta, and +blocking in the `strict` profile once the known corpus is clean. Root Intent +decision-shape findings are blocking for the root contract because its current +decisions have been migrated to that shape. ID, wiki-link, delta, and graph rules remain future deterministic primitives and must carry exit criteria when introduced. ## Derived Graph `intent graph --json` emits the mechanically extracted, resolvable subset of -the VRS graph with a deliberately small v0 shape: +the Intent graph with a deliberately small v0 shape: ```json { - "schema_version": "axe.vrs.graph.v0", - "root": "/repo/context/vrs", + "schema_version": "axe.intent.graph.v0", + "root": "/repo/context/intent", "nodes": [ { "id": "file:requirements.md", @@ -201,10 +200,10 @@ the VRS graph with a deliberately small v0 shape: "evidence": [] }, { - "id": "VRS-R27", + "id": "INTENT-R27", "kind": "requirement", "title": "Enforcement", - "path": "context/vrs/requirements.md", + "path": "context/intent/requirements.md", "status": "active", "refs": [], "refines": [], @@ -214,7 +213,7 @@ the VRS graph with a deliberately small v0 shape: "edges": [ { "source": "file:requirements.md", - "target": "VRS-R27", + "target": "INTENT-R27", "kind": "contains", "path": "requirements.md", "evidence": "structured-id" @@ -235,7 +234,7 @@ Graph v0 extracts: | Fact | Representation | | --- | --- | | Markdown artifact | `file:` node with `kind: "file"` | -| Bold structured ID such as `**AXE.VRS-R08 Graph command:**` | ID node plus `contains` edge from the artifact | +| Bold structured ID such as `**AXE.INTENT-R08 Graph command:**` | ID node plus `contains` edge from the artifact | | Local resolvable Markdown link to another Markdown artifact under the graph root | `markdown_link` edge between file nodes | | Wiki-style reference such as `[[Graph Backlog]]` | `wiki:` node with `status: "unresolved"` plus `wikilink` edge | | Inline `refines: ` text on a structured-ID line | `refines[]` on that ID node | @@ -250,9 +249,9 @@ emits an ambiguous-structure diagnostic rather than inventing a node or edge. `intent review` runs semantic review after deterministic checks. It builds a bounded review packet from: -- the baked VRS semantic-review prompt owned at +- the baked Intent semantic-review prompt owned at [intent/16-enforcement/review-prompt.md](../../intent/16-enforcement/review-prompt.md); -- the target VRS files; +- the target Intent files; - `intent check --json` diagnostics; - the semantic review output schema at [intent/16-enforcement/review-result.schema.json](../../intent/16-enforcement/review-result.schema.json). @@ -264,20 +263,20 @@ originating `schickling/dotfiles` repository): ```text $CODING_AGENT run \ --cwd \ - --prompt-file \ - --context-file normative:... \ - --context-file generated-diagnostics: \ + --prompt-file \ + --context-file normative:... \ + --context-file generated-diagnostics: \ --mode review \ --permission read-only \ --approval never \ --config-policy isolated \ --network-policy disabled \ --output-format json \ - --output-schema + --output-schema ``` 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 Intent enforcement node and are validated through eval fixtures before becoming the baked review version. Provider readiness is checked before spending model tokens. `intent review` @@ -293,25 +292,25 @@ known to the adapter and supports all of the requested contract pieces: | approval | `never`, fail-closed before provider execution if the backend may prompt | | config policy | `isolated` | | network policy | `disabled` for agent/tool/web access; provider model transport may still be required | -| output | `json` plus schema validation for `axe.vrs.review.v1` | +| output | `json` plus schema validation for `axe.intent.review.v1` | 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, `intent review` fails before invoking the provider. The supported -backend set may expand without changing the `intent` CLI contract as long as the +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 `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 -schema-valid `axe.vrs.review.v1` report. One backend's pending real-provider +real-provider run against a small existing Intent subsystem has produced a +schema-valid `axe.intent.review.v1` report. One backend's pending real-provider evidence does not block another backend that satisfies the same readiness criteria. 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` unless a later Intent decision makes a specific semantic rule blocking. Review mode must not write files or silently apply fixes. Any `intent review` or fixture-review mode that calls a real provider and @@ -324,7 +323,7 @@ is that the command fails before provider invocation when it detects CI or other known automated environments. Output defaults to stdout. On success, stdout contains the CAIC JSON result -envelope whose `result` field conforms to `axe.vrs.review.v1`; provider progress +envelope whose `result` field conforms to `axe.intent.review.v1`; provider progress and human logs remain on stderr. `--report ` writes the same final JSON envelope to a caller-chosen path and leaves stdout empty on success, matching CAIC `--final-output` semantics. Tool or schema failures use the CAIC error @@ -347,7 +346,7 @@ For each selected fixture it: 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; -4. grades the returned `axe.vrs.review.v1` result against +4. grades the returned `axe.intent.review.v1` result against `assertions.json`: every `minimum_findings` entry must be satisfied by some finding with the same `rule`, `severity`, `artifact`, and `owner`. @@ -357,7 +356,7 @@ workspace-relative form; no suffix matching, so a finding routed to the wrong artifact fails. A fixture without `assertions.json` is reported as skipped rather than passed. -The command emits an `axe.vrs.review-fixtures.v1` grading report with per-fixture +The command emits an `axe.intent.review-fixtures.v1` grading report with per-fixture `matched` and `missing` assertions. Exit code 0 means every graded assertion was met, 1 means at least one fixture had unmet assertions, and 2 means a fixture review could not be run at all. @@ -372,7 +371,7 @@ fake/probe providers. | Failure | Behavior | | --- | --- | | Path is outside repo | fail with path diagnostic | -| No VRS node found | report no-scope diagnostic, exit nonzero for `check` | +| No Intent node found | report no-scope diagnostic, exit nonzero for `check` | | Markdown parse issue | report artifact diagnostic with line evidence | | Broken link in strict profile | exit nonzero | | Transitional warning | render warning and exit success unless `--warnings-as-errors` | @@ -388,17 +387,18 @@ fake/probe providers. Plan may record: - `intent check --json` output as evidence; -- proposed VRS patches as review/proposed-patch records; -- resolved durable learning routed to VRS artifacts. +- proposed Intent patches as review/proposed-patch records; +- resolved durable learning routed to Intent artifacts. Plan must not become the checker. It records evidence and work coordination -around VRS changes; `vrs-check` and meta-VRS keep semantic ownership. +around Intent changes; `intent-check` and the root Intent contract keep semantic +ownership. ## Anti-Goals -- Do not create a competing top-level `vrs` CLI until there is evidence that - users need one separate from `intent`. -- Do not make the CLI the authority for VRS semantics. +- Do not create a second CLI separate from `intent` without evidence that users + need one. +- Do not make the CLI the authority for Intent semantics. - Do not make generated graph JSON authoritative. - Do not make warning-mode rules permanent. -- Do not silently rewrite VRS artifacts. +- Do not silently rewrite Intent artifacts. diff --git a/crates/intent/Cargo.lock b/crates/intent/Cargo.lock index 33c4b17..447b524 100644 --- a/crates/intent/Cargo.lock +++ b/crates/intent/Cargo.lock @@ -145,7 +145,7 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" [[package]] name = "intent" -version = "0.1.0" +version = "0.2.0" dependencies = [ "clap", "serde", diff --git a/crates/intent/Cargo.toml b/crates/intent/Cargo.toml index 509c5c0..2c13b10 100644 --- a/crates/intent/Cargo.toml +++ b/crates/intent/Cargo.toml @@ -1,8 +1,8 @@ [package] name = "intent" -version = "0.1.0" +version = "0.2.0" edition = "2021" -description = "Deterministic checks, graph extraction and semantic review for a VRS corpus" +description = "Deterministic checks, graph extraction and semantic review for an Intent corpus" [[bin]] name = "intent" diff --git a/crates/intent/README.md b/crates/intent/README.md index 7d25e9b..5bda625 100644 --- a/crates/intent/README.md +++ b/crates/intent/README.md @@ -1,24 +1,23 @@ # intent -Deterministic checks, graph extraction, and semantic review for a VRS corpus. +Deterministic checks, graph extraction, and semantic review for an Intent corpus. -The crate ships both a binary (`intent`) and a library. `axe vrs` embeds the -library and calls `intent::run` directly, so the binary is a thin shell over the -same entry point — anything that lived only in `main.rs` would be behavior the -embedded caller silently does not get. +The crate ships both a binary (`intent`) and a library. The binary is a thin +shell that calls `intent::run`, keeping command behavior in the reusable library +entry point rather than in `main.rs`. ## Commands | Command | What it does | | ------------------------ | ---------------------------------------------------------------- | -| `intent check ` | Deterministic VRS checks. `--profile strict\|local`, `--json`. | -| `intent graph ` | Emits the derived VRS graph subset as JSON. | +| `intent check ` | Deterministic Intent checks. `--profile strict\|local`, `--json`. | +| `intent graph ` | Emits the derived Intent graph subset as JSON. | | `intent review ` | Semantic review via the Coding Agent Invocation Contract. | | `intent review-fixtures` | Grades semantic review against evaluation-fixture assertions. | ## `check` exiting 0 does not mean it read anything -`intent check` on an empty directory, or on a path holding no VRS artifacts at all, +`intent check` on an empty directory, or on a path holding no Intent artifacts at all, exits **0** with `"diagnostics": []`. `graph` exits 0 there too, with `"nodes": []`. Neither exit code distinguishes "the corpus is clean" from "the corpus is not there", so a CI gate built on the exit code alone passes just as happily against a @@ -37,26 +36,23 @@ jq -e '(.nodes | length) > 0' graph.json # this is what proves a corpus was re `.github/workflows/ci.yml` is the worked example. Copy the pair, not just the first half. -## `axe`-flavoured identifiers in an `intent` binary +## Identifier namespaces -`check --json` reports `"schema_version": "axe.vrs.check.v1"`, diagnostics are -prefixed `axe vrs check:` / `axe vrs review:`, and the corpus's own requirement ids -are `AXE.VRS-R01..R19`. That is not an oversight. +`check --json` reports `"schema_version": "axe.intent.check.v1"`, diagnostics are +prefixed `intent check:` / `intent review:`, and the CLI contract's own +requirement IDs are `AXE.INTENT-R01..R19`. -Note the three are different surfaces, and it matters for anyone planning the rename -below. The `AXE.VRS-R*` ids are **requirement ids in the VRS documents** — this -binary never emits one. The `rule` field of a diagnostic carries a different -vocabulary entirely (`VRS.ENF.link.local-target`, `VRS.ENF.delta-shape`, and four -others). Only `schema_version` and the message prefixes are part of what a consumer -parses. +These are different surfaces. The `AXE.INTENT-R*` values are requirement IDs in +the CLI documents; this binary never emits one. Diagnostic `rule` fields +use the checker vocabulary (`INTENT.ENF.link.local-target`, +`INTENT.ENF.delta-shape`, and related rules). Schema versions retain the `axe` +producer namespace as a wire-contract identity, while every reference to the +layer, artifact system, and executable command uses Intent. -This crate was lifted out of `schickling/dotfiles`' `axe` binary, and the acceptance -bar for the lift is that behaviour is byte-identical to `axe vrs` across every -command. Renaming these strings now would destroy the differential oracle that -proves the extraction was faithful, and `axe.vrs.check.v1` is a wire contract with a -live consumer. They are carried to one coordinated rename pass — rule ids, -`schema_version`, the schema `$id` host and the message prefixes together, never -piecemeal. +The Intent rename changes rule IDs, schema versions, schema `$id`, document +grammar, and public Rust type names together. Consumers must update those +machine-readable contracts as one breaking migration rather than depending on +compatibility aliases. ## Enforcement assets resolve under the corpus, never the repository @@ -82,7 +78,7 @@ missing and the corpus it was missing from: ```console $ intent review ./some-corpus -axe vrs review: missing review asset 16-enforcement/review-prompt.md under corpus /abs/path/to/some-corpus +intent review: missing review asset 16-enforcement/review-prompt.md under corpus /abs/path/to/some-corpus ``` Naming both matters: the asset alone does not say which of several corpora was diff --git a/crates/intent/src/lib.rs b/crates/intent/src/lib.rs index 8bfa80e..36f41de 100644 --- a/crates/intent/src/lib.rs +++ b/crates/intent/src/lib.rs @@ -17,18 +17,18 @@ const REVIEW_PROMPT_ASSET: &str = "16-enforcement/review-prompt.md"; const REVIEW_SCHEMA_ASSET: &str = "16-enforcement/review-result.schema.json"; #[derive(Parser, Debug)] -pub struct VrsCli { +pub struct IntentCli { #[command(subcommand)] - pub cmd: VrsCmd, + pub cmd: IntentCmd, } #[derive(Subcommand, Debug)] -pub enum VrsCmd { - /// Run deterministic VRS checks. +pub enum IntentCmd { + /// Run deterministic Intent checks. Check(CheckArgs), - /// Emit the derived VRS graph subset. + /// Emit the derived Intent graph subset. Graph(GraphArgs), - /// Run semantic VRS review through the Coding Agent Invocation Contract. + /// Run semantic Intent review through the Coding Agent Invocation Contract. Review(ReviewArgs), /// Grade semantic review against evaluation-fixture minimum assertions. ReviewFixtures(ReviewFixturesArgs), @@ -36,7 +36,7 @@ pub enum VrsCmd { #[derive(Parser, Debug)] pub struct CheckArgs { - /// VRS root to check. + /// Intent root to check. pub root: Option, /// Rule profile to run. @@ -54,7 +54,7 @@ pub struct CheckArgs { #[derive(Parser, Debug)] pub struct GraphArgs { - /// VRS root to graph. + /// Intent root to graph. pub root: Option, /// Emit machine-readable graph JSON. @@ -64,7 +64,7 @@ pub struct GraphArgs { #[derive(Parser, Debug)] pub struct ReviewArgs { - /// VRS root to review. + /// Intent root to review. pub root: Option, /// Rule profile to use for the deterministic diagnostics packet. @@ -188,11 +188,12 @@ pub struct GraphEdge { /// Where to look when the caller gave no path. /// -/// Which directory holds a corpus is the embedding repository's layout policy, not -/// something a reusable checker can know: `intent` defaults to the directory it is -/// run in, while `axe vrs` supplies dotfiles' own `context/vrs`. Baking one repo's -/// layout in here is what made the tool unusable anywhere else, and a wrong default -/// is invisible — checking a path that holds no VRS artifacts exits 0. +/// Which directory holds a corpus is the embedding repository's layout policy, +/// not something a reusable checker can know: `intent` defaults to the directory +/// it is run in, while an embedding caller may supply a repository-specific root. +/// Baking one repo's layout in here makes the tool unusable elsewhere, and a +/// wrong default is invisible — checking a path that holds no Intent artifacts +/// exits 0. pub struct Defaults { corpus_root: PathBuf, } @@ -221,18 +222,18 @@ impl Default for Defaults { } } -pub fn run(cli: VrsCli) -> ExitCode { +pub fn run(cli: IntentCli) -> ExitCode { run_with(cli, &Defaults::default()) } -/// `run` with the caller's layout policy. `axe vrs` uses this to keep its own -/// `context/vrs` default, so extracting this crate did not change its behavior. -pub fn run_with(cli: VrsCli, defaults: &Defaults) -> ExitCode { +/// `run` with the caller's layout policy so an embedding can select its corpus +/// root without changing the standalone default. +pub fn run_with(cli: IntentCli, defaults: &Defaults) -> ExitCode { match cli.cmd { - VrsCmd::Check(args) => run_check(args, defaults), - VrsCmd::Graph(args) => run_graph(args, defaults), - VrsCmd::Review(args) => run_review(args, defaults), - VrsCmd::ReviewFixtures(args) => run_review_fixtures(args, defaults), + IntentCmd::Check(args) => run_check(args, defaults), + IntentCmd::Graph(args) => run_graph(args, defaults), + IntentCmd::Review(args) => run_review(args, defaults), + IntentCmd::ReviewFixtures(args) => run_review_fixtures(args, defaults), } } @@ -241,7 +242,7 @@ fn run_check(args: CheckArgs, defaults: &Defaults) -> ExitCode { let report = match check_root(&root, args.profile) { Ok(report) => report, Err(error) => { - eprintln!("axe vrs check: {error}"); + eprintln!("intent check: {error}"); return ExitCode::from(2); } }; @@ -254,12 +255,12 @@ fn run_check(args: CheckArgs, defaults: &Defaults) -> ExitCode { match serde_json::to_string_pretty(&report) { Ok(json) => println!("{json}"), Err(error) => { - eprintln!("axe vrs check: failed to render json: {error}"); + eprintln!("intent check: failed to render json: {error}"); return ExitCode::from(2); } } } else if report.diagnostics.is_empty() { - println!("axe vrs check: ok"); + println!("intent check: ok"); } else { for diagnostic in &report.diagnostics { println!( @@ -284,7 +285,7 @@ fn run_graph(args: GraphArgs, defaults: &Defaults) -> ExitCode { let report = match graph_root(&root) { Ok(report) => report, Err(error) => { - eprintln!("axe vrs graph: {error}"); + eprintln!("intent graph: {error}"); return ExitCode::from(2); } }; @@ -293,13 +294,13 @@ fn run_graph(args: GraphArgs, defaults: &Defaults) -> ExitCode { match serde_json::to_string_pretty(&report) { Ok(json) => println!("{json}"), Err(error) => { - eprintln!("axe vrs graph: failed to render json: {error}"); + eprintln!("intent graph: failed to render json: {error}"); return ExitCode::from(2); } } } else { println!( - "axe vrs graph: {} nodes, {} edges", + "intent graph: {} nodes, {} edges", report.nodes.len(), report.edges.len() ); @@ -311,12 +312,12 @@ fn run_graph(args: GraphArgs, defaults: &Defaults) -> ExitCode { fn run_review(args: ReviewArgs, defaults: &Defaults) -> ExitCode { let args_root = defaults.root_or_default(args.root); if let Some(indicator) = automated_context_indicator() { - eprintln!("axe vrs review: refusing semantic review in automated context ({indicator})"); + eprintln!("intent review: refusing semantic review in automated context ({indicator})"); return ExitCode::from(2); } if let Err(error) = preflight_review_backend(&args.coding_agent, args.backend.as_deref()) { - eprintln!("axe vrs review: {error}"); + eprintln!("intent review: {error}"); return ExitCode::from(2); } @@ -324,31 +325,28 @@ fn run_review(args: ReviewArgs, defaults: &Defaults) -> ExitCode { Ok(root) => root, Err(error) => { eprintln!( - "axe vrs review: invalid root {}: {error}", + "intent review: invalid root {}: {error}", args_root.display() ); return ExitCode::from(2); } }; if !root.is_dir() { - eprintln!( - "axe vrs review: root is not a directory: {}", - root.display() - ); + eprintln!("intent review: root is not a directory: {}", root.display()); return ExitCode::from(2); } let workspace = review_workspace(&root); let prompt = match corpus_asset(&root, REVIEW_PROMPT_ASSET) { Ok(path) => path, Err(error) => { - eprintln!("axe vrs review: {error}"); + eprintln!("intent review: {error}"); return ExitCode::from(2); } }; let schema = match corpus_asset(&root, REVIEW_SCHEMA_ASSET) { Ok(path) => path, Err(error) => { - eprintln!("axe vrs review: {error}"); + eprintln!("intent review: {error}"); return ExitCode::from(2); } }; @@ -367,7 +365,7 @@ fn run_review(args: ReviewArgs, defaults: &Defaults) -> ExitCode { let mut plan = match prepare_review(&invocation) { Ok(plan) => plan, Err(error) => { - eprintln!("axe vrs review: {}", error.message); + eprintln!("intent review: {}", error.message); return ExitCode::from(error.exit_code); } }; @@ -376,7 +374,7 @@ fn run_review(args: ReviewArgs, defaults: &Defaults) -> ExitCode { Ok(output) => output, Err(error) => { eprintln!( - "axe vrs review: failed to start CAIC executable {}: {error}", + "intent review: failed to start CAIC executable {}: {error}", args.coding_agent.display() ); return ExitCode::from(2); @@ -394,7 +392,7 @@ struct ReviewInvocation<'a> { coding_agent: &'a Path, backend: Option<&'a str>, timeout_seconds: Option, - /// VRS tree to review. + /// Intent tree to review. root: &'a Path, /// Directory the coding agent runs in. Finding artifact paths are reported /// relative to it, so it decides what an artifact path in a review result means. @@ -426,7 +424,7 @@ impl ReviewSetupError { } /// Build the CAIC invocation for one semantic review, including the deterministic -/// diagnostics packet. Shared by `axe vrs review` and `axe vrs review-fixtures` so +/// diagnostics packet. Shared by the operator and fixture-review commands so /// fixture grading exercises the same invocation the operator command uses. fn prepare_review(invocation: &ReviewInvocation<'_>) -> Result { let target_files = match markdown_files(invocation.root) { @@ -434,7 +432,7 @@ fn prepare_review(invocation: &ReviewInvocation<'_>) -> Result { return Err(ReviewSetupError { message: format!( - "no markdown VRS artifacts found under {}", + "no markdown Intent artifacts found under {}", invocation.root.display() ), exit_code: 1, @@ -442,7 +440,7 @@ fn prepare_review(invocation: &ReviewInvocation<'_>) -> Result { return Err(ReviewSetupError::tool(format!( - "failed to collect VRS artifacts: {error}" + "failed to collect Intent artifacts: {error}" ))) } }; @@ -462,9 +460,9 @@ fn prepare_review(invocation: &ReviewInvocation<'_>) -> Result ExitCod let args_root = defaults.fixtures_or_default(args.root.clone()); if let Some(indicator) = automated_context_indicator() { eprintln!( - "axe vrs review-fixtures: refusing fixture review in automated context ({indicator})" + "intent review-fixtures: refusing fixture review in automated context ({indicator})" ); return ExitCode::from(2); } if let Err(error) = preflight_review_backend(&args.coding_agent, args.backend.as_deref()) { - eprintln!("axe vrs review-fixtures: {error}"); + eprintln!("intent review-fixtures: {error}"); return ExitCode::from(2); } @@ -579,14 +577,14 @@ fn run_review_fixtures(args: ReviewFixturesArgs, defaults: &Defaults) -> ExitCod Ok(root) if root.is_dir() => root, Ok(root) => { eprintln!( - "axe vrs review-fixtures: fixtures root is not a directory: {}", + "intent review-fixtures: fixtures root is not a directory: {}", root.display() ); return ExitCode::from(2); } Err(error) => { eprintln!( - "axe vrs review-fixtures: invalid fixtures root {}: {error}", + "intent review-fixtures: invalid fixtures root {}: {error}", args_root.display() ); return ExitCode::from(2); @@ -596,7 +594,7 @@ fn run_review_fixtures(args: ReviewFixturesArgs, defaults: &Defaults) -> ExitCod let selected = match select_fixtures(&root, &args.fixtures) { Ok(selected) => selected, Err(error) => { - eprintln!("axe vrs review-fixtures: {error}"); + eprintln!("intent review-fixtures: {error}"); return ExitCode::from(2); } }; @@ -606,7 +604,7 @@ fn run_review_fixtures(args: ReviewFixturesArgs, defaults: &Defaults) -> ExitCod let workspaces = match tempfile::tempdir() { Ok(workspaces) => workspaces, Err(error) => { - eprintln!("axe vrs review-fixtures: failed to create eval workspace: {error}"); + eprintln!("intent review-fixtures: failed to create eval workspace: {error}"); return ExitCode::from(2); } }; @@ -626,7 +624,7 @@ fn run_review_fixtures(args: ReviewFixturesArgs, defaults: &Defaults) -> ExitCod let errored = grades.iter().filter(|g| g.status == "errored").count(); let skipped = grades.iter().filter(|g| g.status == "skipped").count(); let report = FixtureGradingReport { - schema_version: "axe.vrs.review-fixtures.v1", + schema_version: "axe.intent.review-fixtures.v1", fixtures_root: root.display().to_string(), backend: args.backend.clone(), fixtures: grades, @@ -639,14 +637,14 @@ fn run_review_fixtures(args: ReviewFixturesArgs, defaults: &Defaults) -> ExitCod let json = match serde_json::to_string_pretty(&report) { Ok(json) => json, Err(error) => { - eprintln!("axe vrs review-fixtures: failed to render grading report: {error}"); + eprintln!("intent review-fixtures: failed to render grading report: {error}"); return ExitCode::from(2); } }; if let Some(path) = &args.report { if let Err(error) = fs::write(path, format!("{json}\n")) { eprintln!( - "axe vrs review-fixtures: failed to write grading report {}: {error}", + "intent review-fixtures: failed to write grading report {}: {error}", path.display() ); return ExitCode::from(2); @@ -685,7 +683,7 @@ fn print_fixture_grades(report: &FixtureGradingReport) { } } println!( - "axe vrs review-fixtures: {} passed, {} failed, {} errored, {} skipped", + "intent review-fixtures: {} passed, {} failed, {} errored, {} skipped", report.passed, report.failed, report.errored, report.skipped ); } @@ -1040,7 +1038,7 @@ fn validate_review_capabilities( Ok(()) } else { Err(format!( - "backend {backend_id} does not satisfy axe vrs review preflight: missing {}", + "backend {backend_id} does not satisfy intent review preflight: missing {}", missing.join(", ") )) } @@ -1081,14 +1079,14 @@ pub fn check_root( check_markdown_links(&root, path, profile, &mut diagnostics)?; } - let decision_dir = meta_vrs_decision_dir(&root); + let decision_dir = root_intent_decision_dir(&root); if decision_dir.is_dir() { check_meta_decision_shape(&root, &decision_dir, profile, &mut diagnostics)?; } check_companion_directories(&root, profile, &mut diagnostics)?; Ok(CheckReport { - schema_version: "axe.vrs.check.v1", + schema_version: "axe.intent.check.v1", root: root.display().to_string(), profile: match profile { Profile::Local => "local", @@ -1193,18 +1191,18 @@ pub fn graph_root(root: &Path) -> Result } Ok(GraphReport { - schema_version: "axe.vrs.graph.v0", + schema_version: "axe.intent.graph.v0", root: root.display().to_string(), nodes: nodes.into_iter().collect(), edges: edges.into_iter().collect(), }) } -// Corpus-relative only. The old second branch guessed `context/vrs/.decisions` to -// cover being handed a repository root instead of a corpus root — a guess that was -// silently wrong for any repository laid out differently, and that let a misaimed -// invocation look like a clean one. Pointing this at a corpus is the caller's job. -fn meta_vrs_decision_dir(root: &Path) -> PathBuf { +// Corpus-relative only. A removed fallback guessed a repository-specific +// `.decisions` path when handed a repository root. That was silently wrong for +// other layouts and let a misaimed invocation look clean. Pointing this at a +// corpus is the caller's job. +fn root_intent_decision_dir(root: &Path) -> PathBuf { root.join(".decisions") } @@ -1226,7 +1224,7 @@ fn check_markdown_links( diagnostics.push(diagnostic( root, path, - "VRS.ENF.link.local-target", + "INTENT.ENF.link.local-target", format!("Local anchor `#{anchor_part}` does not resolve."), "Update the anchor or heading in this file.", link_severity(profile), @@ -1240,7 +1238,7 @@ fn check_markdown_links( diagnostics.push(diagnostic( root, path, - "VRS.ENF.link.local-target", + "INTENT.ENF.link.local-target", format!("Markdown link target `{target}` does not exist."), "Update the link target or add the referenced artifact.", link_severity(profile), @@ -1255,7 +1253,7 @@ fn check_markdown_links( diagnostics.push(diagnostic( root, path, - "VRS.ENF.link.local-target", + "INTENT.ENF.link.local-target", format!("Markdown link anchor `{target}` does not resolve."), "Update the anchor or add the referenced heading.", link_severity(profile), @@ -1388,7 +1386,7 @@ fn check_proposed_decisions( diagnostics.push(diagnostic( root, &path, - "VRS.ENF.proposed-decision", + "INTENT.ENF.proposed-decision", "Proposed decision records are PR-local and must not merge.".to_string(), "Accept the decision, fold it into requirements/spec, move it to open questions, or delete it before merge.", Severity::Error, @@ -1408,7 +1406,7 @@ fn check_delta_shape( diagnostics.push(diagnostic( root, &path, - "VRS.ENF.delta-shape", + "INTENT.ENF.delta-shape", format!("Delta filename `{file_name}` must match `DELTA-001-.md`."), "Rename the delta with a stable `DELTA-NNN-.md` identifier.", Severity::Error, @@ -1421,7 +1419,7 @@ fn check_delta_shape( Some(status) => diagnostics.push(diagnostic( root, &path, - "VRS.ENF.delta-shape", + "INTENT.ENF.delta-shape", format!("Delta status `{status}` is not `open`."), "Keep only open delta records; close resolved deltas by deleting the file.", Severity::Error, @@ -1429,7 +1427,7 @@ fn check_delta_shape( None => diagnostics.push(diagnostic( root, &path, - "VRS.ENF.delta-shape", + "INTENT.ENF.delta-shape", "Delta record is missing `Status: open`.".to_string(), "Add `Status: open` or delete the delta if it is resolved.", Severity::Error, @@ -1439,7 +1437,7 @@ fn check_delta_shape( let sections = sections(&content); for heading in [ "Divergence", - "VRS", + "Intent", "Implementation", "Direction", "Resolution Signal", @@ -1449,7 +1447,7 @@ fn check_delta_shape( &path, §ions, heading, - "VRS.ENF.delta-shape", + "INTENT.ENF.delta-shape", "Fill the required delta section or delete the stale delta.", Severity::Error, diagnostics, @@ -1461,12 +1459,12 @@ fn check_delta_shape( .find(|section| section.heading == "Direction") { let value = direction.body.trim(); - if !matches!(value, "update implementation" | "update VRS" | "decide") { + if !matches!(value, "update implementation" | "update Intent" | "decide") { diagnostics.push(diagnostic( root, &path, - "VRS.ENF.delta-shape", - format!("Delta direction `{value}` must be `update implementation`, `update VRS`, or `decide`."), + "INTENT.ENF.delta-shape", + format!("Delta direction `{value}` must be `update implementation`, `update Intent`, or `decide`."), "Set `## Direction` to one of the accepted delta direction values.", Severity::Error, )); @@ -1485,13 +1483,19 @@ fn check_experiment_shape( for path in markdown_files_direct(experiment_dir)? { let content = fs::read_to_string(&path)?; let sections = sections(&content); - for heading in ["Question", "Method", "Result", "Conclusion", "VRS Impact"] { + for heading in [ + "Question", + "Method", + "Result", + "Conclusion", + "Intent Impact", + ] { require_section( root, &path, §ions, heading, - "VRS.ENF.experiment-shape", + "INTENT.ENF.experiment-shape", "Fill the required experiment evidence section or move speculative work out of `.experiments/`.", companion_shape_severity(profile), diagnostics, @@ -1513,7 +1517,7 @@ fn check_reference_shape( diagnostics.push(diagnostic( root, &path, - "VRS.ENF.reference-shape", + "INTENT.ENF.reference-shape", "Reference record is missing `Source:`.".to_string(), "Add the URL, file, command, or system that supplied the reference facts.", companion_shape_severity(profile), @@ -1521,14 +1525,14 @@ fn check_reference_shape( } let sections = sections(&content); - for heading in ["Relevant Facts", "VRS Impact"] { + for heading in ["Relevant Facts", "Intent Impact"] { require_section( root, &path, §ions, heading, - "VRS.ENF.reference-shape", - "Fill the required reference section or delete source material that has no VRS impact.", + "INTENT.ENF.reference-shape", + "Fill the required reference section or delete source material that has no Intent impact.", companion_shape_severity(profile), diagnostics, ); @@ -1537,10 +1541,9 @@ fn check_reference_shape( Ok(()) } -// Eight arguments, one over clippy's threshold. Left as-is deliberately: this crate -// is a lift of `axe vrs`, whose acceptance bar is that it behaves identically, and -// grouping these into a struct is a refactor whose only motivation is a style lint. -// Worth doing later, on its own, where a regression would be attributable. +// Eight arguments, one over clippy's threshold. Grouping these into a struct is +// unrelated to the identifier migration and is best handled as an isolated +// refactor where any behavioral regression is attributable. #[allow(clippy::too_many_arguments)] fn require_section( root: &Path, @@ -1620,10 +1623,10 @@ fn markdown_files_direct(dir: &Path) -> Result, Box PathBuf { for ancestor in root.ancestors() { if ancestor.join(".git").exists() { @@ -1683,9 +1686,9 @@ fn visit_markdown( } if path.is_dir() { // Semantic-review fixture `input/` trees are deliberately broken synthetic - // artifacts. They are neither real VRS artifacts for deterministic checks nor + // artifacts. They are neither real Intent artifacts for deterministic checks nor // normative review context; collecting them would ship planted smells to the - // provider as genuine VRS. + // provider as genuine Intent. if is_semantic_review_fixture_input(root, &path) { continue; } @@ -1817,7 +1820,7 @@ fn structured_id_in_line(line: &str) -> Option { let label = line[start..end].trim().trim_end_matches(':').trim(); let mut parts = label.splitn(2, char::is_whitespace); let id = parts.next()?.trim(); - if !looks_like_vrs_id(id) { + if !looks_like_intent_id(id) { return None; } let title = parts.next().unwrap_or("").trim().to_string(); @@ -1835,7 +1838,7 @@ fn structured_id_in_line(line: &str) -> Option { }) } -fn looks_like_vrs_id(value: &str) -> bool { +fn looks_like_intent_id(value: &str) -> bool { value.len() >= 2 && value.chars().any(|ch| ch.is_ascii_digit()) && value @@ -1849,7 +1852,7 @@ fn refs_in_text(text: &str) -> Vec { }) .filter_map(|part| { let candidate = part.trim_matches('.'); - looks_like_vrs_id(candidate).then(|| candidate.to_string()) + looks_like_intent_id(candidate).then(|| candidate.to_string()) }) .collect() } @@ -2096,7 +2099,7 @@ fn decision_shape_diagnostic( diagnostic( root, path, - "VRS.ENF.meta-decision-shape", + "INTENT.ENF.meta-decision-shape", evidence, suggested_fix, Severity::Error, @@ -2126,7 +2129,7 @@ fn diagnostic( severity: Severity, ) -> Diagnostic { Diagnostic { - schema_version: "axe.vrs.diagnostic.v1", + schema_version: "axe.intent.diagnostic.v1", kind: "deterministic", gate: match severity { Severity::Error => "blocking", @@ -2173,9 +2176,9 @@ mod tests { #[test] fn valid_fixture_passes_strict_checks() { let tempdir = tempfile::tempdir().unwrap(); - let root = tempdir.path().join("context/vrs"); + let root = tempdir.path().join("context/intent"); fs::create_dir_all(&root).unwrap(); - write_valid_vrs(&root); + write_valid_intent(&root); let report = check_root(&root, Profile::Strict).unwrap(); assert!( @@ -2188,9 +2191,9 @@ mod tests { #[test] fn broken_links_and_decisions_are_reported() { let tempdir = tempfile::tempdir().unwrap(); - let root = tempdir.path().join("context/vrs"); + let root = tempdir.path().join("context/intent"); fs::create_dir_all(&root).unwrap(); - write_valid_vrs(&root); + write_valid_intent(&root); fs::write( root.join("spec.md"), "# Spec\n\nSee [missing](./missing.md) and [bad anchor](./requirements.md#missing).\n", @@ -2204,8 +2207,8 @@ mod tests { let report = check_root(&root, Profile::Strict).unwrap(); let rules: Vec<_> = report.diagnostics.iter().map(|d| d.rule).collect(); - assert!(rules.contains(&"VRS.ENF.link.local-target")); - assert!(rules.contains(&"VRS.ENF.meta-decision-shape")); + assert!(rules.contains(&"INTENT.ENF.link.local-target")); + assert!(rules.contains(&"INTENT.ENF.meta-decision-shape")); assert!(report .diagnostics .iter() @@ -2215,7 +2218,7 @@ mod tests { #[test] fn local_profile_still_blocks_for_decision_shape() { let tempdir = tempfile::tempdir().unwrap(); - let root = tempdir.path().join("context/vrs"); + let root = tempdir.path().join("context/intent"); fs::create_dir_all(root.join(".decisions")).unwrap(); fs::write( root.join(".decisions/0001-bad.md"), @@ -2224,22 +2227,20 @@ mod tests { .unwrap(); let report = check_root(&root, Profile::Local).unwrap(); - assert!(report - .diagnostics - .iter() - .any(|d| { d.rule == "VRS.ENF.meta-decision-shape" && d.severity == Severity::Error })); + assert!(report.diagnostics.iter().any(|d| { + d.rule == "INTENT.ENF.meta-decision-shape" && d.severity == Severity::Error + })); } - // The extraction's acceptance bar is that `axe vrs` behaves identically, and the - // only thing holding that up is the caller keeping its own default. Locked here + // Embedded callers keep their own corpus default. Lock that behavior here // because a regression is silent: the wrong root still exits 0. #[test] fn an_absent_argument_falls_back_to_the_callers_layout() { - let axe = Defaults::corpus_root("context/vrs"); - assert_eq!(axe.root_or_default(None), PathBuf::from("context/vrs")); + let axe = Defaults::corpus_root("context/intent"); + assert_eq!(axe.root_or_default(None), PathBuf::from("context/intent")); assert_eq!( axe.fixtures_or_default(None), - PathBuf::from("context/vrs/15-evaluation/semantic-review") + PathBuf::from("context/intent/15-evaluation/semantic-review") ); // Standalone `intent` checks the corpus it is run in. @@ -2253,7 +2254,7 @@ mod tests { #[test] fn an_explicit_argument_always_beats_the_default() { - let defaults = Defaults::corpus_root("context/vrs"); + let defaults = Defaults::corpus_root("context/intent"); let explicit = PathBuf::from("/somewhere/else"); assert_eq!(defaults.root_or_default(Some(explicit.clone())), explicit); assert_eq!( @@ -2262,9 +2263,9 @@ mod tests { ); } - // Covers the branch that replaced the `context/vrs` sentinel. It is only ever - // reached where there is no `.git` — a Nix build sandbox or a vendored source - // tree — so it is invisible to any interactive run. + // Covers the fallback used when there is no `.git`, such as a Nix build + // sandbox or vendored source tree. Interactive runs normally take the + // enclosing-repository branch instead. #[test] fn review_workspace_falls_back_to_the_corpus_when_there_is_no_git() { let tempdir = tempfile::tempdir().unwrap(); @@ -2301,12 +2302,12 @@ mod tests { ); // A repository-relative copy must NOT satisfy a corpus-relative lookup. - fs::create_dir_all(repo.join("context/vrs/16-enforcement")).unwrap(); - fs::write(repo.join("context/vrs").join(REVIEW_SCHEMA_ASSET), "{}").unwrap(); + fs::create_dir_all(repo.join("context/intent/16-enforcement")).unwrap(); + fs::write(repo.join("context/intent").join(REVIEW_SCHEMA_ASSET), "{}").unwrap(); assert!(corpus_asset(&corpus, REVIEW_SCHEMA_ASSET).is_err()); } - fn write_valid_vrs(root: &Path) { + fn write_valid_intent(root: &Path) { fs::create_dir(root.join(".decisions")).unwrap(); fs::write( root.join("requirements.md"), diff --git a/crates/intent/src/main.rs b/crates/intent/src/main.rs index cfedecf..b553139 100644 --- a/crates/intent/src/main.rs +++ b/crates/intent/src/main.rs @@ -1,9 +1,8 @@ use clap::Parser; use std::process::ExitCode; -// The binary is a thin shell over the library entry point on purpose: `axe vrs` -// calls `intent::run` directly, so anything that lived here would be behavior the -// embedded caller silently does not get. +// The binary is a thin shell over the library entry point so standalone and +// embedded callers execute the same checker behavior. fn main() -> ExitCode { - intent::run(intent::VrsCli::parse()) + intent::run(intent::IntentCli::parse()) } diff --git a/crates/intent/tests/vrs_check.rs b/crates/intent/tests/intent_check.rs similarity index 83% rename from crates/intent/tests/vrs_check.rs rename to crates/intent/tests/intent_check.rs index 5f69d4e..889d967 100644 --- a/crates/intent/tests/vrs_check.rs +++ b/crates/intent/tests/intent_check.rs @@ -1,4 +1,4 @@ -//! Integration tests ported from `flakes/axe/tests/vrs_check.rs` in +//! Integration tests ported from `flakes/axe/tests/intent_check.rs` in //! `schickling/dotfiles`, where the suite stayed behind when the checker was lifted //! into this crate. They drive the built `intent` binary end to end and are the //! differential oracle for the extraction. @@ -55,22 +55,22 @@ impl Harness { fn new() -> Self { let tempdir = tempfile::tempdir().expect("tempdir"); let repo = tempdir.path().join("repo"); - fs::create_dir_all(repo.join("context/vrs/.decisions")).expect("repo"); - fs::create_dir_all(repo.join("context/vrs/16-enforcement")).expect("enforcement"); - fs::write(repo.join("context/vrs/spec.md"), "# Spec\n").expect("spec"); + fs::create_dir_all(repo.join("context/intent/.decisions")).expect("repo"); + fs::create_dir_all(repo.join("context/intent/16-enforcement")).expect("enforcement"); + fs::write(repo.join("context/intent/spec.md"), "# Spec\n").expect("spec"); fs::write( - repo.join("context/vrs/16-enforcement/review-prompt.md"), - "Return a schema-valid fake VRS review result.", + repo.join("context/intent/16-enforcement/review-prompt.md"), + "Return a schema-valid fake Intent review result.", ) .expect("review prompt"); fs::write( - repo.join("context/vrs/16-enforcement/review-result.schema.json"), + repo.join("context/intent/16-enforcement/review-result.schema.json"), r#"{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": ["schema_version", "summary", "findings"], "properties": { - "schema_version": { "const": "axe.vrs.review.v1" }, + "schema_version": { "const": "axe.intent.review.v1" }, "summary": { "type": "string" }, "findings": { "type": "array" } }, @@ -80,7 +80,7 @@ impl Harness { ) .expect("review schema"); fs::write( - repo.join("context/vrs/.decisions/0001-good.md"), + repo.join("context/intent/.decisions/0001-good.md"), r#"# Good Decision Status: accepted @@ -118,7 +118,7 @@ Choose A because it fits the current scope. fn check(&self, args: &[&str]) -> Output { Command::new(&self.intent) .arg("check") - .arg(self.repo.join("context/vrs")) + .arg(self.repo.join("context/intent")) .args(args) .output() .expect("intent check") @@ -127,7 +127,7 @@ Choose A because it fits the current scope. fn graph(&self, args: &[&str]) -> Output { Command::new(&self.intent) .arg("graph") - .arg(self.repo.join("context/vrs")) + .arg(self.repo.join("context/intent")) .args(args) .output() .expect("intent graph") @@ -169,12 +169,12 @@ fn bash_path() -> PathBuf { fn graph_json_exposes_files_ids_links_and_wikilinks() { let h = Harness::new(); fs::write( - h.repo.join("context/vrs/requirements.md"), - "# Requirements\n\n- **AXE.VRS-R08 Graph command:** emit graph JSON; refines: VRS-R27.\n", + h.repo.join("context/intent/requirements.md"), + "# Requirements\n\n- **AXE.INTENT-R08 Graph command:** emit graph JSON; refines: INTENT-R27.\n", ) .expect("requirements"); fs::write( - h.repo.join("context/vrs/spec.md"), + h.repo.join("context/intent/spec.md"), "# Spec\n\nSee [requirements](./requirements.md) and [[Graph Backlog|graph work]].\n\n```text\n[[IgnoredInFence]]\n```\n", ) .expect("spec"); @@ -187,21 +187,21 @@ fn graph_json_exposes_files_ids_links_and_wikilinks() { String::from_utf8_lossy(&output.stderr) ); let graph = stdout_json(&output); - assert_eq!(graph["schema_version"], "axe.vrs.graph.v0"); + assert_eq!(graph["schema_version"], "axe.intent.graph.v0"); let nodes = graph["nodes"].as_array().unwrap(); assert!(nodes .iter() .any(|node| { node["id"] == "file:requirements.md" && node["kind"] == "file" })); assert!(nodes.iter().any(|node| { - node["id"] == "AXE.VRS-R08" + node["id"] == "AXE.INTENT-R08" && node["kind"] == "requirement" && node["title"] == "Graph command" && node["refines"] .as_array() .unwrap() .iter() - .any(|id| id == "VRS-R27") + .any(|id| id == "INTENT-R27") })); assert!(nodes .iter() @@ -214,7 +214,7 @@ fn graph_json_exposes_files_ids_links_and_wikilinks() { let edges = graph["edges"].as_array().unwrap(); assert!(edges.iter().any(|edge| { edge["source"] == "file:requirements.md" - && edge["target"] == "AXE.VRS-R08" + && edge["target"] == "AXE.INTENT-R08" && edge["kind"] == "contains" })); assert!(edges.iter().any(|edge| { @@ -230,7 +230,7 @@ fn graph_json_exposes_files_ids_links_and_wikilinks() { } #[test] -fn valid_minimal_vrs_tree_passes_json_check() { +fn valid_minimal_intent_tree_passes_json_check() { let h = Harness::new(); let output = h.check(&["--json"]); @@ -241,7 +241,7 @@ fn valid_minimal_vrs_tree_passes_json_check() { String::from_utf8_lossy(&output.stderr) ); let report = stdout_json(&output); - assert_eq!(report["schema_version"], "axe.vrs.check.v1"); + assert_eq!(report["schema_version"], "axe.intent.check.v1"); assert_eq!(report["diagnostics"].as_array().unwrap().len(), 0); } @@ -249,7 +249,7 @@ fn valid_minimal_vrs_tree_passes_json_check() { fn missing_local_markdown_links_are_transitional_locally_and_blocking_in_strict_profile() { let h = Harness::new(); fs::write( - h.repo.join("context/vrs/spec.md"), + h.repo.join("context/intent/spec.md"), "# Spec\n\nSee [missing](./missing.md).\n", ) .expect("broken link"); @@ -259,7 +259,7 @@ fn missing_local_markdown_links_are_transitional_locally_and_blocking_in_strict_ let local_report = stdout_json(&local); assert_eq!( local_report["diagnostics"][0]["rule"], - "VRS.ENF.link.local-target" + "INTENT.ENF.link.local-target" ); assert_eq!(local_report["diagnostics"][0]["severity"], "warning"); assert_eq!(local_report["diagnostics"][0]["gate"], "transitional"); @@ -272,10 +272,10 @@ fn missing_local_markdown_links_are_transitional_locally_and_blocking_in_strict_ } #[test] -fn meta_vrs_decision_shape_is_blocking() { +fn root_intent_decision_shape_is_blocking() { let h = Harness::new(); fs::write( - h.repo.join("context/vrs/.decisions/0002-bad.md"), + h.repo.join("context/intent/.decisions/0002-bad.md"), r#"# Bad Decision Status: @@ -298,7 +298,7 @@ No comparison table. let report = stdout_json(&output); let diagnostics = report["diagnostics"].as_array().unwrap(); assert!(diagnostics.iter().any(|diagnostic| { - diagnostic["rule"] == "VRS.ENF.meta-decision-shape" + diagnostic["rule"] == "INTENT.ENF.meta-decision-shape" && diagnostic["artifact"] .as_str() .unwrap() @@ -309,10 +309,10 @@ No comparison table. #[test] fn proposed_decision_records_are_blocking() { let h = Harness::new(); - fs::create_dir_all(h.repo.join("context/vrs/.decisions/.proposed")).expect("proposed dir"); + fs::create_dir_all(h.repo.join("context/intent/.decisions/.proposed")).expect("proposed dir"); fs::write( h.repo - .join("context/vrs/.decisions/.proposed/revisit-scope.md"), + .join("context/intent/.decisions/.proposed/revisit-scope.md"), "# Proposed\n", ) .expect("proposed decision"); @@ -322,7 +322,7 @@ fn proposed_decision_records_are_blocking() { let report = stdout_json(&output); let diagnostics = report["diagnostics"].as_array().unwrap(); assert!(diagnostics.iter().any(|diagnostic| { - diagnostic["rule"] == "VRS.ENF.proposed-decision" + diagnostic["rule"] == "INTENT.ENF.proposed-decision" && diagnostic["severity"] == "error" && diagnostic["artifact"] .as_str() @@ -334,18 +334,18 @@ fn proposed_decision_records_are_blocking() { #[test] fn delta_record_shape_is_blocking() { let h = Harness::new(); - fs::create_dir_all(h.repo.join("context/vrs/.delta")).expect("delta dir"); + fs::create_dir_all(h.repo.join("context/intent/.delta")).expect("delta dir"); fs::write( - h.repo.join("context/vrs/.delta/DELTA-001-good.md"), + h.repo.join("context/intent/.delta/DELTA-001-good.md"), r#"# DELTA-001: Good Status: open ## Divergence -The implementation and VRS differ. +The implementation and Intent differ. -## VRS +## Intent See [spec](../spec.md). @@ -355,7 +355,7 @@ Observed in a local check. ## Direction -update VRS +update Intent ## Resolution Signal @@ -364,7 +364,7 @@ The spec reflects the implementation. ) .expect("good delta"); fs::write( - h.repo.join("context/vrs/.delta/delta-bad.md"), + h.repo.join("context/intent/.delta/delta-bad.md"), r#"# Bad Delta Status: closed @@ -381,7 +381,7 @@ This is stale. let report = stdout_json(&output); let diagnostics = report["diagnostics"].as_array().unwrap(); assert!(diagnostics.iter().any(|diagnostic| { - diagnostic["rule"] == "VRS.ENF.delta-shape" + diagnostic["rule"] == "INTENT.ENF.delta-shape" && diagnostic["severity"] == "error" && diagnostic["artifact"] .as_str() @@ -397,10 +397,10 @@ This is stale. } #[test] -fn semantic_review_fixture_inputs_are_not_treated_as_real_vrs_artifacts() { +fn semantic_review_fixture_inputs_are_not_treated_as_real_intent_artifacts() { let h = Harness::new(); let fixture_delta = h.repo.join( - "context/vrs/15-evaluation/semantic-review/stale-delta/input/context/stale-delta/.delta", + "context/intent/15-evaluation/semantic-review/stale-delta/input/context/stale-delta/.delta", ); fs::create_dir_all(&fixture_delta).expect("fixture delta dir"); fs::write( @@ -429,15 +429,15 @@ fn semantic_review_fixture_inputs_are_not_treated_as_real_vrs_artifacts() { #[test] fn experiment_and_reference_shape_are_transitional_locally_and_blocking_in_strict_profile() { let h = Harness::new(); - fs::create_dir_all(h.repo.join("context/vrs/.experiments")).expect("experiments dir"); - fs::create_dir_all(h.repo.join("context/vrs/.reference")).expect("reference dir"); + fs::create_dir_all(h.repo.join("context/intent/.experiments")).expect("experiments dir"); + fs::create_dir_all(h.repo.join("context/intent/.reference")).expect("reference dir"); fs::write( - h.repo.join("context/vrs/.experiments/smoke.md"), + h.repo.join("context/intent/.experiments/smoke.md"), "# Smoke\n\n## Question\n\nWhat happens?\n", ) .expect("experiment"); fs::write( - h.repo.join("context/vrs/.reference/provider.md"), + h.repo.join("context/intent/.reference/provider.md"), "# Provider\n\n## Relevant Facts\n\nFact.\n", ) .expect("reference"); @@ -447,12 +447,12 @@ fn experiment_and_reference_shape_are_transitional_locally_and_blocking_in_stric let local_report = stdout_json(&local); let local_diagnostics = local_report["diagnostics"].as_array().unwrap(); assert!(local_diagnostics.iter().any(|diagnostic| { - diagnostic["rule"] == "VRS.ENF.experiment-shape" + diagnostic["rule"] == "INTENT.ENF.experiment-shape" && diagnostic["severity"] == "warning" && diagnostic["gate"] == "transitional" })); assert!(local_diagnostics.iter().any(|diagnostic| { - diagnostic["rule"] == "VRS.ENF.reference-shape" + diagnostic["rule"] == "INTENT.ENF.reference-shape" && diagnostic["severity"] == "warning" && diagnostic["gate"] == "transitional" })); @@ -462,12 +462,12 @@ fn experiment_and_reference_shape_are_transitional_locally_and_blocking_in_stric let strict_report = stdout_json(&strict); let strict_diagnostics = strict_report["diagnostics"].as_array().unwrap(); assert!(strict_diagnostics.iter().any(|diagnostic| { - diagnostic["rule"] == "VRS.ENF.experiment-shape" + diagnostic["rule"] == "INTENT.ENF.experiment-shape" && diagnostic["severity"] == "error" && diagnostic["gate"] == "blocking" })); assert!(strict_diagnostics.iter().any(|diagnostic| { - diagnostic["rule"] == "VRS.ENF.reference-shape" + diagnostic["rule"] == "INTENT.ENF.reference-shape" && diagnostic["severity"] == "error" && diagnostic["gate"] == "blocking" })); @@ -479,7 +479,7 @@ fn review_refuses_likely_automated_context() { let output = Command::new(&h.intent) .arg("review") - .arg(h.repo.join("context/vrs")) + .arg(h.repo.join("context/intent")) .arg("--coding-agent") .arg(&h.coding_agent) .env("CI", "true") @@ -504,7 +504,7 @@ fn review_refuses_backend_without_review_contract_before_invoking_caic_run() { let output = Command::new(&h.intent) .arg("review") - .arg(h.repo.join("context/vrs")) + .arg(h.repo.join("context/intent")) .arg("--coding-agent") .arg(fake_coding_agent) .env("FAKE_CAIC_RUN_MARKER", &marker) @@ -516,7 +516,7 @@ fn review_refuses_backend_without_review_contract_before_invoking_caic_run() { assert_eq!(output.status.code(), Some(2)); let stderr = String::from_utf8_lossy(&output.stderr); assert!( - stderr.contains("backend opencode does not satisfy axe vrs review preflight"), + stderr.contains("backend opencode does not satisfy intent review preflight"), "stderr:\n{stderr}" ); assert!( @@ -533,7 +533,7 @@ fn review_refuses_backend_without_review_contract_before_invoking_caic_run() { ); assert!( !marker.exists(), - "axe vrs review must not invoke CAIC run after a failed capabilities preflight" + "intent review must not invoke CAIC run after a failed capabilities preflight" ); } diff --git a/flake.nix b/flake.nix index 2dc9051..ab8bab8 100644 --- a/flake.nix +++ b/flake.nix @@ -1,5 +1,5 @@ { - description = "intent - deterministic checks, graph extraction and semantic review for a VRS corpus"; + description = "intent - deterministic checks, graph extraction and semantic review for an Intent corpus"; inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; @@ -58,7 +58,7 @@ # version. meta = { - description = "Deterministic checks, graph extraction and semantic review for a VRS corpus"; + description = "Deterministic checks, graph extraction and semantic review for an Intent corpus"; homepage = "https://github.com/compoundingtech/intent"; mainProgram = "intent"; }; diff --git a/intent/.decisions/0001-use-decision-records-with-pr-local-proposals.md b/intent/.decisions/0001-use-decision-records-with-pr-local-proposals.md index 99294eb..79360a9 100644 --- a/intent/.decisions/0001-use-decision-records-with-pr-local-proposals.md +++ b/intent/.decisions/0001-use-decision-records-with-pr-local-proposals.md @@ -4,7 +4,7 @@ Status: accepted ## Context -VRS needs a durable log for consequential choices, but those choices are not +Intent needs a durable log for consequential choices, but those choices are not limited to architecture. Agents also need a branch-local way to keep working through unresolved decisions without letting tentative records merge to main. @@ -13,7 +13,7 @@ through unresolved decisions without letting tentative records merge to main. The repo already uses `decisions/` and `.decisions/` widely for non-architecture choices. The user's Notion notes asked about `.adr`, proposed records for autonomous mode, and whether ADR is general enough. ADR practice is recognizable -but usually architecture-framed; VRS explicitly covers product, operational, +but usually architecture-framed; Intent explicitly covers product, operational, data, interface, validation, and design choices too. ## Options @@ -29,4 +29,4 @@ data, interface, validation, and design choices too. Use **Decision Record** as the canonical term and store durable records under `.decisions/000N-.md`. Proposed records may live under `.decisions/.proposed/` while a PR is open, but must be accepted, folded into -another VRS artifact, deferred to `open-questions.md`, or deleted before merge. +another Intent artifact, deferred to `open-questions.md`, or deleted before merge. diff --git a/intent/.decisions/0002-order-child-vrs-nodes-by-formal-contract.md b/intent/.decisions/0002-order-child-intent-nodes-by-formal-contract.md similarity index 60% rename from intent/.decisions/0002-order-child-vrs-nodes-by-formal-contract.md rename to intent/.decisions/0002-order-child-intent-nodes-by-formal-contract.md index 6308f34..ce42665 100644 --- a/intent/.decisions/0002-order-child-vrs-nodes-by-formal-contract.md +++ b/intent/.decisions/0002-order-child-intent-nodes-by-formal-contract.md @@ -1,18 +1,18 @@ -# Order child VRS nodes by formal contract +# Order child Intent nodes by formal contract Status: accepted ## Context -The meta-VRS needs child nodes for each artifact kind. The order communicates +The root Intent contract needs child nodes for each artifact kind. The order communicates how readers should approach the system and how agents should project the skill onto the normative contract. ## Evidence and Argument -The user explicitly rejected putting `intuition` first and preferred "VRS first, +The user explicitly rejected putting `intuition` first and preferred "Intent first, then glossary after the spec, and then intuition after the glossary." Existing -VRS practice treats Vision, Requirements, and Spec as the formal chain, while +Intent practice treats Vision, Requirements, and Spec as the formal chain, while glossary and intuition support that chain. ## Options @@ -20,12 +20,12 @@ glossary and intuition support that chain. | Option | Tradeoffs | | --- | --- | | Intuition first | Good reader onboarding, but makes the narrative entry point look like the first normative layer. | -| Lifecycle order | Useful for workflow, but obscures the VRS contract structure. | -| Formal contract first | Preserves VRS semantics: `vision` -> `requirements` -> `spec`, then language and narrative supports. | +| Lifecycle order | Useful for workflow, but obscures the Intent contract structure. | +| Formal contract first | Preserves Intent semantics: `vision` -> `requirements` -> `spec`, then language and narrative supports. | ## Decision -Order meta-VRS child nodes by the formal VRS contract first: `vision`, +Order root Intent contract child nodes by the formal Intent contract first: `vision`, `requirements`, and `spec`. `glossary` follows the spec because language is shared by the formal documents, and `intuition` follows the glossary because it is narrative support rather than the first normative layer. Numeric prefixes diff --git a/intent/.decisions/0003-use-delta-directory-for-open-divergence.md b/intent/.decisions/0003-use-delta-directory-for-open-divergence.md index 4a2d2f7..1d79752 100644 --- a/intent/.decisions/0003-use-delta-directory-for-open-divergence.md +++ b/intent/.decisions/0003-use-delta-directory-for-open-divergence.md @@ -22,11 +22,11 @@ closed records, so an archive section would duplicate history. | --- | --- | | `implementation-delta.md` | Visible and simple, but tends to grow into a stale ledger. | | `.delta/DELTA-*.md` | Consistent with companion directories and makes current open divergence easy to prune. | -| Planning-system tasks only | Avoids another VRS surface, but hides contract/reality drift from VRS readers. | +| Planning-system tasks only | Avoids another Intent surface, but hides contract/reality drift from Intent readers. | ## Decision -Track confirmed VRS/implementation divergence in a lazy `.delta/` companion +Track confirmed Intent/implementation divergence in a lazy `.delta/` companion directory with one file per open delta. Delta records are current-state -artifacts, not history; resolved or stale deltas are deleted after the VRS or +artifacts, not history; resolved or stale deltas are deleted after the Intent or implementation is corrected. diff --git a/intent/.decisions/0004-open-deltas-may-exist-on-main.md b/intent/.decisions/0004-open-deltas-may-exist-on-main.md index 23b0933..2303c44 100644 --- a/intent/.decisions/0004-open-deltas-may-exist-on-main.md +++ b/intent/.decisions/0004-open-deltas-may-exist-on-main.md @@ -4,13 +4,13 @@ Status: accepted ## Context -After choosing `.delta/`, VRS needed to decide whether open deltas are merge +After choosing `.delta/`, Intent needed to decide whether open deltas are merge blockers or accepted current-state documentation. ## Evidence and Argument The user confirmed that open deltas should be allowed on main. A delta is a -truthful statement that VRS and implementation diverge; blocking all merges on +truthful statement that Intent and implementation diverge; blocking all merges on known drift would incentivize hiding or deleting useful context. The risk is stale debt, which is handled by freshness rules rather than a blanket merge ban. diff --git a/intent/.decisions/0006-add-constraints-section-to-requirements.md b/intent/.decisions/0006-add-constraints-section-to-requirements.md index 5a482f5..f5ab3fe 100644 --- a/intent/.decisions/0006-add-constraints-section-to-requirements.md +++ b/intent/.decisions/0006-add-constraints-section-to-requirements.md @@ -5,7 +5,7 @@ Status: accepted ## Context The Notion notes asked to add a constraints section to `requirements.md` and -called out external systems, resource bounds, and references as important VRS +called out external systems, resource bounds, and references as important Intent areas. Requirements needed a way to distinguish desired behavior from non-negotiable boundaries. @@ -27,7 +27,7 @@ references. ## Decision -VRS requirements files include a first-class `## Constraints` section for +Intent requirements files include a first-class `## Constraints` section for non-negotiable environmental, operational, platform, regulatory, resource, or integration limits. Constraints derived from external systems must cite `.reference/` material. The constraint is normative; the reference preserves the diff --git a/intent/.decisions/0007-common-subsystems-not-generic-files.md b/intent/.decisions/0007-common-subsystems-not-generic-files.md index 769089f..3a7c141 100644 --- a/intent/.decisions/0007-common-subsystems-not-generic-files.md +++ b/intent/.decisions/0007-common-subsystems-not-generic-files.md @@ -4,16 +4,16 @@ Status: accepted ## Context -The Notion notes proposed a separate `datamodel.md` and listed other good VRS +The Notion notes proposed a separate `datamodel.md` and listed other good Intent areas: surface areas, data models, verification loops, external-system assumptions, and resource bounds. The user clarified that data model should be a -common VRS subsystem rather than a generic companion file. +common Intent subsystem rather than a generic companion file. ## Evidence and Argument Data models and interfaces often need their own requirements, constraints, specs, references, and verification. A single `datamodel.md` companion file -would create a special case and compete with the hierarchical VRS model. Common +would create a special case and compete with the hierarchical Intent model. Common subsystem candidates preserve the pattern without forcing every topic to create them. @@ -23,11 +23,11 @@ them. | --- | --- | | Add generic `datamodel.md` | Convenient for one concern, but special-cases data and does not generalize to interfaces or operations. | | Keep all data model content in root `spec.md` | Simple for small systems, but large schemas overwhelm the root spec. | -| Treat data model and peers as common child subsystems | Scales through normal VRS composition and keeps companion files for lifecycle artifacts. | +| Treat data model and peers as common child subsystems | Scales through normal Intent composition and keeps companion files for lifecycle artifacts. | ## Decision Treat recurring areas such as data model, interfaces, verification, integrations, and operations as common subsystem candidates. A substantial data -model becomes a child VRS node with its own `requirements.md` and `spec.md`, not +model becomes a child Intent node with its own `requirements.md` and `spec.md`, not `datamodel.md`. diff --git a/intent/.decisions/0008-review-smells-live-in-meta-vrs.md b/intent/.decisions/0008-review-smells-live-in-meta-vrs.md deleted file mode 100644 index 1e3972b..0000000 --- a/intent/.decisions/0008-review-smells-live-in-meta-vrs.md +++ /dev/null @@ -1,31 +0,0 @@ -# Review smells live in meta-VRS - -Status: accepted - -## Context - -The Notion notes called out VRS smells and bad patterns. The user chose to put -those checks in the meta-VRS rather than a separate per-topic artifact or only -in the skill. - -## Evidence and Argument - -Smells are review rules for VRS authors and agents. They are not durable facts -about each documented system, so per-topic `smells.md` files would drift and -create noise. Keeping smells in the meta-VRS lets skills apply the same review -contract uniformly. - -## Options - -| Option | Tradeoffs | -| --- | --- | -| Per-topic `smells.md` | Local and visible, but likely noisy and stale. | -| Skill-only guidance | Easy to apply operationally, but not normative outside the skill. | -| Meta-VRS review-smells node | Central, normative, and reusable by skills without becoming a topic artifact. | - -## Decision - -VRS smells and bad patterns live in the meta-VRS contract. They guide review of -all VRS documents but are not per-topic artifacts. This centralizes checks such -as stale open-question pruning, wrong-artifact ownership, and generic README -usage. diff --git a/intent/.decisions/0008-review-smells-live-in-root-intent-contract.md b/intent/.decisions/0008-review-smells-live-in-root-intent-contract.md new file mode 100644 index 0000000..4c1ebdf --- /dev/null +++ b/intent/.decisions/0008-review-smells-live-in-root-intent-contract.md @@ -0,0 +1,31 @@ +# Review smells live in root Intent contract + +Status: accepted + +## Context + +The Notion notes called out Intent smells and bad patterns. The user chose to put +those checks in the root Intent contract rather than a separate per-topic artifact or only +in the skill. + +## Evidence and Argument + +Smells are review rules for Intent authors and agents. They are not durable facts +about each documented system, so per-topic `smells.md` files would drift and +create noise. Keeping smells in the root Intent contract lets skills apply the same review +contract uniformly. + +## Options + +| Option | Tradeoffs | +| --- | --- | +| Per-topic `smells.md` | Local and visible, but likely noisy and stale. | +| Skill-only guidance | Easy to apply operationally, but not normative outside the skill. | +| Root Intent contract review-smells node | Central, normative, and reusable by skills without becoming a topic artifact. | + +## Decision + +Intent smells and bad patterns live in the root Intent contract. They guide review of +all Intent documents but are not per-topic artifacts. This centralizes checks such +as stale open-question pruning, wrong-artifact ownership, and generic README +usage. diff --git a/intent/.decisions/0009-use-open-questions-for-drafting-coverage.md b/intent/.decisions/0009-use-open-questions-for-drafting-coverage.md index e45f0ca..a684272 100644 --- a/intent/.decisions/0009-use-open-questions-for-drafting-coverage.md +++ b/intent/.decisions/0009-use-open-questions-for-drafting-coverage.md @@ -11,7 +11,7 @@ unless clearly blocked. ## Evidence and Argument -Initial VRS drafting naturally produces uncertainty and unexplored areas. A +Initial Intent drafting naturally produces uncertainty and unexplored areas. A separate checklist artifact would add another file type that must later be cleaned up. `open-questions.md` already has lifecycle rules and can absorb temporary drafting coverage if agents apply resolution pressure before @@ -27,6 +27,6 @@ finalizing. ## Decision -Initial VRS drafting may use `open-questions.md` as the temporary coverage -surface. Before finalizing VRS work, agents must try to resolve every question; +Initial Intent drafting may use `open-questions.md` as the temporary coverage +surface. Before finalizing Intent work, agents must try to resolve every question; any remaining question must name the blocker that prevents resolution. diff --git a/intent/.decisions/0010-validate-load-bearing-assumptions.md b/intent/.decisions/0010-validate-load-bearing-assumptions.md index 125124b..d5bae5a 100644 --- a/intent/.decisions/0010-validate-load-bearing-assumptions.md +++ b/intent/.decisions/0010-validate-load-bearing-assumptions.md @@ -5,12 +5,12 @@ Status: accepted ## Context The Notion notes asked for e2e verification, research, prototypes, and gap -finding during VRS design. The user clarified that assumptions should always be +finding during Intent design. The user clarified that assumptions should always be validated in the best possible way, including proofs and independent critique. ## Evidence and Argument -Assumptions are where weak VRS documents often smuggle uncertainty into durable +Assumptions are where weak Intent documents often smuggle uncertainty into durable truth. Validation can take many shapes depending on the claim: user confirmation for intent, references for external behavior, benchmarks or e2e experiments for runtime claims, prototypes for feasibility, proofs for deterministic claims, @@ -22,13 +22,13 @@ independent pressure-testing. | Option | Tradeoffs | | --- | --- | | Require experiments for every assumption | Strong evidence, but too heavy and wrong for assumptions better validated by proof, reference, or user confirmation. | -| Only record assumptions without validation | Low friction, but lets speculation harden into VRS truth. | +| Only record assumptions without validation | Low friction, but lets speculation harden into Intent truth. | | Require best feasible validation or a blocked open question | Proportional rigor while preserving progress when validation is not yet possible. | ## Decision Load-bearing assumptions must be validated in the best feasible way before they -become durable VRS truth. Valid forms include user confirmation, research, +become durable Intent truth. Valid forms include user confirmation, research, benchmarks, e2e experiments, prototypes, proofs, implementation evidence, or independent critique from another agent. If validation is not feasible yet, the assumption remains an open question with a clear blocker and resolution signal. diff --git a/intent/.decisions/0011-decisions-require-evidence-options-and-tradeoffs.md b/intent/.decisions/0011-decisions-require-evidence-options-and-tradeoffs.md index 776d472..3c24072 100644 --- a/intent/.decisions/0011-decisions-require-evidence-options-and-tradeoffs.md +++ b/intent/.decisions/0011-decisions-require-evidence-options-and-tradeoffs.md @@ -4,7 +4,7 @@ Status: accepted ## Context -Earlier VRS decision records used a minimal "what and why" shape. That is useful +Earlier Intent decision records used a minimal "what and why" shape. That is useful for low-friction capture, but it can let weakly justified choices harden into durable contract without showing why alternatives lost. @@ -12,7 +12,7 @@ durable contract without showing why alternatives lost. The user explicitly wants each decision to show evidence for the best approach, principled options, proofs or arguments, tradeoffs, and the reason the selected -option is best. This also matches the VRS goal of helping future readers avoid +option is best. This also matches the Intent goal of helping future readers avoid re-litigating hidden reasoning. The user also clarified that evidence often should be plural: at least one @@ -30,9 +30,9 @@ experiments plus user confirmation, or proofs plus implementation evidence. ## Decision -VRS durable decision records must include evidence or argument, principled +Intent durable decision records must include evidence or argument, principled options with tradeoffs, and a clear reason the chosen option is best under the -current VRS context. They must include at least one applicable evidence form and +current Intent context. They must include at least one applicable evidence form and should include multiple independent evidence forms when the decision is important, risky, or expensive to reverse. This keeps the record broad enough for non-architecture decisions while preventing unsupported choices from @@ -88,7 +88,7 @@ attribution claims (who said X) as much as to factual ones: they are checkable in the record and are not a softer category. **Limit.** This is a discipline, not a gate. The companion enforcement in -`context/vrs/.decisions/0033` constrains *citations* (an ordinal must resolve; +`intent/.decisions/0033` constrains *citations* (an ordinal must resolve; a label must match its target); it cannot see a *claim* — prose asserting a fact about the tree passes every structural check while being false. The enforcement narrows what needs re-derivation; it does not remove the diff --git a/intent/.decisions/0012-vrs-is-the-intent-layer.md b/intent/.decisions/0012-vrs-is-the-intent-layer.md deleted file mode 100644 index 09b97aa..0000000 --- a/intent/.decisions/0012-vrs-is-the-intent-layer.md +++ /dev/null @@ -1,30 +0,0 @@ -# VRS is the intent layer - -Status: accepted - -## Context - -The Notion notes suggested describing VRS as the "intent layer" or intent -programming. The meta-VRS needed to decide whether that is a rename, a concept, -or out of scope. - -## Evidence and Argument - -The root vision already describes VRS as durable structured knowledge that -constrains skills, plans, and code. "Intent layer" captures that role well, but -renaming the artifact system would create churn and ambiguity because `VRS` -already names the concrete document contract. - -## Options - -| Option | Tradeoffs | -| --- | --- | -| Rename VRS to intent layer | Conceptually rich, but breaks existing skill and repo language. | -| Ignore intent-layer framing | Avoids new terminology, but loses a useful explanation of VRS's role. | -| Use intent layer as conceptual role | Clarifies purpose while preserving VRS as the artifact/system name. | - -## Decision - -Describe VRS as the project's **intent layer**: durable, structured intent that -constrains code, plans, skills, and agent behavior without replacing -implementation truth. Keep `VRS` as the concrete artifact and system name. diff --git a/intent/.decisions/0013-grill-intent-is-the-intent-interview-procedure.md b/intent/.decisions/0013-grill-intent-is-the-intent-interview-procedure.md new file mode 100644 index 0000000..c0da386 --- /dev/null +++ b/intent/.decisions/0013-grill-intent-is-the-intent-interview-procedure.md @@ -0,0 +1,33 @@ +# Grill Intent is the Intent interview procedure + +Status: accepted + +## Context + +The user asked to recommend using Intent with a grilling procedure and suggested +the name `grill-intent`. The root Intent contract needs to define whether that skill is a peer +documentation system, a consumer of Intent, or the operating procedure for Intent +sessions. + +## Evidence and Argument + +The existing procedure already acts as a Socratic interview loop that updates +Intent-like artifacts. As the root Intent contract becomes normative, keeping full artifact +rules duplicated in the skill would create drift. A `grill-intent` name better +describes the actual job: grilling the Intent layer until the contract is +precise. + +## Options + +| Option | Tradeoffs | +| --- | --- | +| Keep the generic docs-oriented name | Avoids rename churn, but keeps a generic name and encourages duplicated doc rules. | +| Rename to `grill-intent` and make it procedural | Aligns name with purpose and lets root Intent contract own artifact rules. | +| Fold grilling entirely into `intent.md` | One fewer skill, but loses the explicit interview mode and one-question discipline. | + +## Decision + +Use `grill-intent` as the preferred name for the Socratic interview/update +procedure that applies Intent. Intent owns artifacts and lifecycle rules; `grill-intent` +owns the questioning, pressure-testing, validation, and inline update procedure. +The operational skill is named `grill-intent`. diff --git a/intent/.decisions/0013-grill-vrs-is-the-vrs-interview-procedure.md b/intent/.decisions/0013-grill-vrs-is-the-vrs-interview-procedure.md deleted file mode 100644 index b292a61..0000000 --- a/intent/.decisions/0013-grill-vrs-is-the-vrs-interview-procedure.md +++ /dev/null @@ -1,33 +0,0 @@ -# Grill VRS is the VRS interview procedure - -Status: accepted - -## Context - -The user asked to recommend using VRS with a grilling procedure and suggested -the name `grill-vrs`. The meta-VRS needs to define whether that skill is a peer -documentation system, a consumer of VRS, or the operating procedure for VRS -sessions. - -## Evidence and Argument - -The existing procedure already acts as a Socratic interview loop that updates -VRS-like artifacts. As the meta-VRS becomes normative, keeping full artifact -rules duplicated in the skill would create drift. A `grill-vrs` name better -describes the actual job: grilling the VRS intent layer until the contract is -precise. - -## Options - -| Option | Tradeoffs | -| --- | --- | -| Keep the generic docs-oriented name | Avoids rename churn, but keeps a generic name and encourages duplicated doc rules. | -| Rename to `grill-vrs` and make it procedural | Aligns name with purpose and lets meta-VRS own artifact rules. | -| Fold grilling entirely into `vrs.md` | One fewer skill, but loses the explicit interview mode and one-question discipline. | - -## Decision - -Use `grill-vrs` as the preferred name for the Socratic interview/update -procedure that applies VRS. VRS owns artifacts and lifecycle rules; `grill-vrs` -owns the questioning, pressure-testing, validation, and inline update procedure. -The operational skill is named `grill-vrs`. diff --git a/intent/.decisions/0014-evaluate-vrs-with-isolated-scenarios.md b/intent/.decisions/0014-evaluate-intent-with-isolated-scenarios.md similarity index 63% rename from intent/.decisions/0014-evaluate-vrs-with-isolated-scenarios.md rename to intent/.decisions/0014-evaluate-intent-with-isolated-scenarios.md index 83379f0..845a06b 100644 --- a/intent/.decisions/0014-evaluate-vrs-with-isolated-scenarios.md +++ b/intent/.decisions/0014-evaluate-intent-with-isolated-scenarios.md @@ -1,16 +1,16 @@ -# Evaluate VRS with isolated scenarios +# Evaluate Intent with isolated scenarios Status: accepted ## Context -After defining the meta-VRS and renaming `grill-vrs`, the user asked to run an -end-to-end eval in a separate agent and to create a sub-VRS for the eval +After defining the root Intent contract and renaming `grill-intent`, the user asked to run an +end-to-end eval in a separate agent and to create a sub-Intent for the eval approach. ## Evidence and Argument -The meta-VRS is self-recursive and skill-driven, so paper review is not enough. +The root Intent contract is self-recursive and skill-driven, so paper review is not enough. An isolated scenario can exercise artifact routing, decision evidence, glossary handling, open questions, references, experiments, deltas, and skill behavior without polluting the real repo. Running it in a separate agent gives a partial @@ -21,11 +21,11 @@ independent critique signal. | Option | Tradeoffs | | --- | --- | | Review the docs manually only | Fast, but misses usability failures in the actual procedure. | -| Eval directly in the repo | Realistic, but risks polluting tracked files and confusing real VRS with test artifacts. | +| Eval directly in the repo | Realistic, but risks polluting tracked files and confusing real Intent with test artifacts. | | Eval in isolated temporary scenarios | Produces inspectable evidence while keeping durable findings review-gated. | ## Decision -Evaluate VRS and VRS skills through isolated temporary scenarios. The eval -worker must not modify tracked repo files; it reports evidence and proposed VRS +Evaluate Intent and Intent skills through isolated temporary scenarios. The eval +worker must not modify tracked repo files; it reports evidence and proposed Intent updates for the owner agent to review and apply. diff --git a/intent/.decisions/0015-glossary-handling-lives-in-grill-vrs.md b/intent/.decisions/0015-glossary-handling-lives-in-grill-intent.md similarity index 64% rename from intent/.decisions/0015-glossary-handling-lives-in-grill-vrs.md rename to intent/.decisions/0015-glossary-handling-lives-in-grill-intent.md index 00d8578..6771525 100644 --- a/intent/.decisions/0015-glossary-handling-lives-in-grill-vrs.md +++ b/intent/.decisions/0015-glossary-handling-lives-in-grill-intent.md @@ -1,11 +1,11 @@ -# Glossary handling lives in Grill VRS +# Glossary handling lives in Grill Intent Status: superseded by [0032](./0032-rename-glossary-artifact-to-ontology.md) ## Context The Notion notes asked to embrace glossary handling. The user agreed that this -should be part of `grill-vrs` rather than a separate glossary skill by default. +should be part of `grill-intent` rather than a separate glossary skill by default. ## Evidence and Argument @@ -19,11 +19,11 @@ work has shown enough independent complexity to justify it. | Option | Tradeoffs | | --- | --- | | Separate glossary skill now | Clear ownership, but premature and interrupts the design interview flow. | -| Keep glossary rules only in meta-VRS | Normative, but does not say who applies them during interviews. | -| Make `grill-vrs` apply the glossary contract | Simple flow and one less skill, while preserving the option to split later. | +| Keep glossary rules only in root Intent contract | Normative, but does not say who applies them during interviews. | +| Make `grill-intent` apply the glossary contract | Simple flow and one less skill, while preserving the option to split later. | ## Decision -`grill-vrs` handles glossary work by applying `context/vrs/04-glossary/`. +`grill-intent` handles glossary work by applying `intent/04-glossary/`. A separate glossary skill is created only if glossary work becomes complex enough to need an independently reusable procedure. diff --git a/intent/.decisions/0016-use-existing-vrs-systems-as-references.md b/intent/.decisions/0016-use-existing-intent-systems-as-references.md similarity index 72% rename from intent/.decisions/0016-use-existing-vrs-systems-as-references.md rename to intent/.decisions/0016-use-existing-intent-systems-as-references.md index 48dc67c..c9912e7 100644 --- a/intent/.decisions/0016-use-existing-vrs-systems-as-references.md +++ b/intent/.decisions/0016-use-existing-intent-systems-as-references.md @@ -1,15 +1,15 @@ -# Use existing VRS systems as references +# Use existing Intent systems as references Status: accepted ## Context -The user asked that the VRS skill mention existing VRS systems as references +The user asked that the Intent skill mention existing Intent systems as references when helpful. ## Evidence and Argument -The repo already contains multiple VRS shapes: flat topics, hierarchical +The repo already contains multiple Intent shapes: flat topics, hierarchical subsystem trees, and composable contract/realization trees. These examples help agents calibrate scope, section size, subsystem depth, and companion-artifact use. The risk is cargo-culting a shape that fit another system but not the @@ -25,5 +25,5 @@ current one. ## Decision -VRS authors should inspect existing VRS systems as references when helpful. Use +Intent authors should inspect existing Intent systems as references when helpful. Use examples for precedent and calibration, not as templates to copy blindly. diff --git a/intent/.decisions/0017-use-narrow-vrs-enforcement-subsystem.md b/intent/.decisions/0017-use-narrow-intent-enforcement-subsystem.md similarity index 68% rename from intent/.decisions/0017-use-narrow-vrs-enforcement-subsystem.md rename to intent/.decisions/0017-use-narrow-intent-enforcement-subsystem.md index da90c7f..3cb7837 100644 --- a/intent/.decisions/0017-use-narrow-vrs-enforcement-subsystem.md +++ b/intent/.decisions/0017-use-narrow-intent-enforcement-subsystem.md @@ -1,10 +1,10 @@ -# Use a narrow VRS enforcement subsystem +# Use a narrow Intent enforcement subsystem Status: accepted ## Context -After evaluating VRS and researching the remaining checklist items, the user was +After evaluating Intent and researching the remaining checklist items, the user was unsure whether a broad tooling subsystem made sense. Focused probes found that IDs, xrefs, compact records, delta upkeep, and Axe Plan integration have different semantic owners. @@ -14,12 +14,12 @@ different semantic owners. Identifier and xref rules mostly belong to requirements/spec/evaluation until a real resolver protocol exists. Compact decisions and experiments belong to their artifact contracts and review smells. Delta upkeep belongs to the delta contract -plus `grill-vrs` procedure, with tooling only for mechanical checks. Axe Plan -integration belongs to the Axe Plans VRS, not to meta-VRS tooling. +plus `grill-intent` procedure, with tooling only for mechanical checks. Axe Plan +integration belongs to the Axe Plans Intent, not to root Intent contract tooling. The remaining cross-cutting concern with enough independent surface area is enforcement: deterministic lint, semantic review, diagnostics, gates, and local -workflow integration for real repository VRS trees. +workflow integration for real repository Intent trees. ## Options @@ -31,6 +31,6 @@ workflow integration for real repository VRS trees. ## Decision -Create `16-enforcement/` as a narrow meta-VRS child node. It owns VRS hygiene +Create `16-enforcement/` as a narrow root Intent contract child node. It owns Intent hygiene checks, diagnostics, and gate semantics. It does not own artifact semantics, -`axe plan` integration, isolated evaluation, or every VRS-related tool. +`axe plan` integration, isolated evaluation, or every Intent-related tool. diff --git a/intent/.decisions/0018-identifiers-are-commit-scoped.md b/intent/.decisions/0018-identifiers-are-commit-scoped.md index c66cfaf..202b467 100644 --- a/intent/.decisions/0018-identifiers-are-commit-scoped.md +++ b/intent/.decisions/0018-identifiers-are-commit-scoped.md @@ -5,35 +5,35 @@ Status: accepted ## Context The structured-reference experiments showed that symbolic or namespaced IDs make -VRS refactors easier than path-only references, while wiki-style links are -ambiguous in hierarchical VRS trees. The user clarified that VRS IDs do not need +Intent refactors easier than path-only references, while wiki-style links are +ambiguous in hierarchical Intent trees. The user clarified that Intent IDs do not need to be long-term stable public identifiers; they need to be atomically consistent within the scope of one repository commit. ## Evidence and Argument -VRS lives in Git. A commit is the reviewable unit where requirements, specs, +Intent lives in Git. A commit is the reviewable unit where requirements, specs, references, and enforcement diagnostics must agree. Treating IDs as permanent -public API would over-constrain useful VRS refactors such as splitting a +public API would over-constrain useful Intent refactors such as splitting a requirements file, renumbering local IDs, or moving a subsystem. Treating IDs as purely local labels would make cross-document traceability and deterministic checks brittle. Commit-scoped consistency keeps the useful property: every reference in a commit must resolve unambiguously to the current intended artifact and clause. It still -allows future commits to rename, renumber, or re-scope IDs when the VRS shape +allows future commits to rename, renumber, or re-scope IDs when the Intent shape improves, as long as all references change atomically. ## Options | Option | Tradeoffs | | --- | --- | -| Long-term stable IDs | Maximizes external traceability, but makes VRS restructuring unnecessarily costly. | +| Long-term stable IDs | Maximizes external traceability, but makes Intent restructuring unnecessarily costly. | | Local numbering labels only | Easy to write, but weak for cross-document references and enforcement. | | Commit-scoped IDs | Supports refactoring while preserving review-time consistency and tooling checks. | ## Decision -VRS identifiers are commit-scoped consistency handles, not long-term public API. -They may be renamed, renumbered, or re-scoped when the VRS shape improves, but a +Intent identifiers are commit-scoped consistency handles, not long-term public API. +They may be renamed, renumbered, or re-scoped when the Intent shape improves, but a repository commit must not contain stale, ambiguous, or mismatched references. diff --git a/intent/.decisions/0019-start-xref-enforcement-with-deterministic-subset.md b/intent/.decisions/0019-start-xref-enforcement-with-deterministic-subset.md index 1413769..8a0cf75 100644 --- a/intent/.decisions/0019-start-xref-enforcement-with-deterministic-subset.md +++ b/intent/.decisions/0019-start-xref-enforcement-with-deterministic-subset.md @@ -4,15 +4,15 @@ Status: accepted ## Context -After deciding that VRS identifiers are commit-scoped consistency handles, the +After deciding that Intent identifiers are commit-scoped consistency handles, the user agreed that xref tooling should enforce this rule. The link-structure experiments showed that Markdown links are useful for navigation, wiki-style -links are ambiguous in hierarchical VRS, and symbolic or namespaced IDs make +links are ambiguous in hierarchical Intent, and symbolic or namespaced IDs make refactors easier when a resolver can check them. ## Evidence and Argument -The current VRS representation is still Markdown-authored. A full typed graph is +The current Intent representation is still Markdown-authored. A full typed graph is on the roadmap, not current infrastructure. However, a narrow deterministic xref subset can provide immediate value without requiring semantic review or a full registry: link existence, ID uniqueness within scope, spec-to-requirement @@ -26,7 +26,7 @@ is internally consistent, not that IDs stay stable forever. | Option | Tradeoffs | | --- | --- | -| Wait for typed VRS graph | Cleaner architecture later, but leaves current brittle links unchecked. | +| Wait for typed Intent graph | Cleaner architecture later, but leaves current brittle links unchecked. | | Enforce all reference semantics now | Ambitious, but likely noisy without a resolver and migration plan. | | Start with deterministic xref subset | Immediate value, low ambiguity, and compatible with future typed graph work. | diff --git a/intent/.decisions/0020-keep-structured-vrs-roadmap-only.md b/intent/.decisions/0020-keep-structured-intent-roadmap-only.md similarity index 76% rename from intent/.decisions/0020-keep-structured-vrs-roadmap-only.md rename to intent/.decisions/0020-keep-structured-intent-roadmap-only.md index 8878526..4c9fb43 100644 --- a/intent/.decisions/0020-keep-structured-vrs-roadmap-only.md +++ b/intent/.decisions/0020-keep-structured-intent-roadmap-only.md @@ -1,10 +1,10 @@ -# Keep structured VRS roadmap-only for now +# Keep structured Intent roadmap-only for now Status: accepted ## Context -VRS currently uses Markdown files plus deterministic conventions. The roadmap +Intent currently uses Markdown files plus deterministic conventions. The roadmap already identifies a future structured intent layer with symbolic references, typed records, checked schemas, and better refactoring support. The open design question is whether to introduce machine-readable structure now or keep it as a @@ -12,7 +12,7 @@ future direction until enforcement proves the need. ## Evidence and Argument -The current implementation path is still centered on Markdown-authored VRS +The current implementation path is still centered on Markdown-authored Intent artifacts and a narrow deterministic enforcement subset. The immediate checker can extract useful facts from files, links, headings, IDs, and companion directory shapes without making authors maintain frontmatter, sidecars, or typed @@ -21,7 +21,7 @@ source files. Adding structure too early would create migration and authoring overhead before the checker has demonstrated which facts it cannot infer reliably. Keeping the structured layer on the roadmap preserves the direction while letting evidence -from `axe vrs` enforcement and isolated evaluations decide the next step. +from `intent` enforcement and isolated evaluations decide the next step. ## Options @@ -30,15 +30,15 @@ from `axe vrs` enforcement and isolated evaluations decide the next step. | Roadmap only | Lowest authoring friction and preserves Markdown as the normative source, but restructuring and renumbering remain brittle until tooling matures. | | Add light frontmatter soon | Gives tooling explicit artifact metadata, but risks two sources of shape truth and premature schema churn. | | Add sidecar graph files | Improves symbolic tooling, but authored sidecars can drift unless generated-only rules are strict. | -| Move to typed VRS source | Strongest long-term tooling model, but highest migration cost and premature for the current checker maturity. | +| Move to typed Intent source | Strongest long-term tooling model, but highest migration cost and premature for the current checker maturity. | ## Decision -Keep structured VRS representation roadmap-only for now. Markdown VRS artifacts +Keep structured Intent representation roadmap-only for now. Markdown Intent artifacts remain normative. Deterministic enforcement should extract a narrow derived graph from Markdown and report ambiguous facts instead of requiring frontmatter, sidecars, or typed source in the current contract. -Revisit this decision when `axe vrs` enforcement repeatedly needs facts that +Revisit this decision when `intent` enforcement repeatedly needs facts that cannot be inferred reliably from Markdown links, headings, IDs, and companion artifact shapes. diff --git a/intent/.decisions/0021-promote-link-checks-before-decision-shape.md b/intent/.decisions/0021-promote-link-checks-before-decision-shape.md index 7bdd2f9..06d9320 100644 --- a/intent/.decisions/0021-promote-link-checks-before-decision-shape.md +++ b/intent/.decisions/0021-promote-link-checks-before-decision-shape.md @@ -4,7 +4,7 @@ Status: accepted ## Context -VRS enforcement needs a first deterministic blocking rule after migration. The +Intent enforcement needs a first deterministic blocking rule after migration. The candidates include local Markdown link existence, decision-record shape, proposed decision cleanup, and open-question blocker checks. @@ -28,7 +28,7 @@ pretending to verify decision quality semantically. | Option | Tradeoffs | | --- | --- | -| Make local Markdown link existence the first blocking rule | Low ambiguity and immediate value, but narrower than full VRS quality. | +| Make local Markdown link existence the first blocking rule | Low ambiguity and immediate value, but narrower than full Intent quality. | | Make decision-record shape blocking immediately | Improves decision hygiene, but can incentivize decorative sections without evidence quality. | | Block only on `.decisions/.proposed/` | Very crisp, but too narrow to validate the broader checker path. | | Block on open-question blockers | Process-aligned, but too semantic for an early deterministic gate. | @@ -42,7 +42,7 @@ useful and not mostly decorative. ## Consequences -- `axe vrs` enforcement should prioritize local link discovery, resolution, +- `intent` enforcement should prioritize local link discovery, resolution, diagnostics, allowlist calibration, and strict-mode promotion first. - Decision-record checks should start warning-only with explicit experiment criteria before becoming merge-blocking. diff --git a/intent/.decisions/0022-scope-decision-shape-to-meta-vrs-first.md b/intent/.decisions/0022-scope-decision-shape-to-root-intent-first.md similarity index 77% rename from intent/.decisions/0022-scope-decision-shape-to-meta-vrs-first.md rename to intent/.decisions/0022-scope-decision-shape-to-root-intent-first.md index cfccdf2..b02c3b0 100644 --- a/intent/.decisions/0022-scope-decision-shape-to-meta-vrs-first.md +++ b/intent/.decisions/0022-scope-decision-shape-to-root-intent-first.md @@ -1,21 +1,21 @@ -# Scope decision shape to meta-VRS first +# Scope decision shape to root Intent contract first Status: accepted ## Context -The decision-shape enforcement experiment found that the current meta-VRS +The decision-shape enforcement experiment found that the current root Intent contract decision records already match the proposed strict mechanical shape, while the wider `context/**/.decisions` corpus contains many older records that predate the current decision contract. The next question is whether initial enforcement should target only -`context/vrs/.decisions`, all context decisions in warning mode, changed +`intent/.decisions`, all context decisions in warning mode, changed decisions only, or all decisions with an allowlist. ## Evidence and Argument -The owning contract for decision-record shape lives in the meta-VRS decision +The owning contract for decision-record shape lives in the root Intent contract decision subsystem. Applying the strict mechanical rule there first proves the rule on the canonical examples and avoids turning legacy subsystem decisions into noisy migration work before the checker exists. @@ -31,7 +31,7 @@ rule has proven itself. | Option | Tradeoffs | | --- | --- | -| Meta-VRS only first | Cleanly proves strict shape on the owning contract and avoids legacy noise, but gives narrower coverage. | +| Root Intent contract only first | Cleanly proves strict shape on the owning contract and avoids legacy noise, but gives narrower coverage. | | All context decisions warning-only | Makes migration debt visible, but can be noisy and may distract from proving the rule. | | New or changed decisions only | Avoids legacy churn, but requires diff-aware enforcement. | | All decisions with allowlist | Comprehensive, but creates allowlist maintenance before rule maturity. | @@ -39,7 +39,7 @@ rule has proven itself. ## Decision Initial strict decision-shape enforcement applies only to -`context/vrs/.decisions/`. +`intent/.decisions/`. Broader `context/**/.decisions/` checks may be introduced later as migration diagnostics or scoped warnings after the checker has stable diagnostics and a @@ -47,9 +47,9 @@ clear migration plan. ## Consequences -- The first decision-shape checker should use the meta-VRS decisions as the +- The first decision-shape checker should use the root Intent contract decisions as the strict target corpus. - Repo-wide decision-shape findings remain migration evidence, not merge blockers. - The broader corpus can be migrated deliberately without weakening the strict - shape contract for new meta-VRS decisions. + shape contract for new root Intent contract decisions. diff --git a/intent/.decisions/0023-own-semantic-review-assets-in-enforcement.md b/intent/.decisions/0023-own-semantic-review-assets-in-enforcement.md index 87b50a2..8612580 100644 --- a/intent/.decisions/0023-own-semantic-review-assets-in-enforcement.md +++ b/intent/.decisions/0023-own-semantic-review-assets-in-enforcement.md @@ -4,58 +4,58 @@ Status: accepted ## Context -`axe vrs review` needs a baked prompt and output schema so semantic review can +`intent review` needs a baked prompt and output schema so semantic review can run through the Coding Agent Invocation Contract without accepting arbitrary caller prompts. The ownership question is whether those assets belong with the enforcement -contract, the review-smell rubric, the Axe command VRS, or packaged Axe runtime +contract, the review-smell rubric, the CLI Intent, or packaged Axe runtime assets. ## Evidence and Argument -The CAIC semantic-review prototype showed that `axe vrs review` can pass a -baked prompt, generated deterministic diagnostics, normative VRS artifacts, and +The CAIC semantic-review prototype showed that `intent review` can pass a +baked prompt, generated deterministic diagnostics, normative Intent artifacts, and an output schema through `$CODING_AGENT` in read-only review mode. It also showed that generated diagnostics need stable schema markers before review is production-ready. -Semantic review is an enforcement mode: it classifies VRS hygiene and review +Semantic review is an enforcement mode: it classifies Intent hygiene and review risk, emits findings with gates, and composes deterministic diagnostics with human or agent judgment. The review-smell catalog supplies the rubric, but does not own invocation policy or output schema. Axe owns command plumbing and packaging, but making Axe own the prompt would make a tool implementation the -source of VRS semantics. +source of Intent semantics. ## Options | Option | Tradeoffs | | --- | --- | -| `context/vrs/16-enforcement/` | Keeps prompt and schema with the enforcement contract and makes VRS the semantic owner, but puts executable review assets in a spec node. | -| `context/vrs/13-review-smells/` | Keeps the prompt close to the smell rubric, but separates review output schema and gate policy from enforcement. | -| `context/coding-agents/14-axe/12-vrs/` | Keeps assets close to the command implementation, but risks Axe becoming the semantic authority for VRS review. | -| `flakes/axe/assets/vrs-review/` | Easiest to package in the CLI, but separates normative review behavior from the VRS source of truth. | +| `intent/16-enforcement/` | Keeps prompt and schema with the enforcement contract and makes Intent the semantic owner, but puts executable review assets in a spec node. | +| `intent/13-review-smells/` | Keeps the prompt close to the smell rubric, but separates review output schema and gate policy from enforcement. | +| `context/coding-agents/14-axe/12-intent/` | Keeps assets close to the command implementation, but risks Axe becoming the semantic authority for Intent review. | +| `flakes/axe/assets/intent-review/` | Easiest to package in the CLI, but separates normative review behavior from the Intent source of truth. | ## Decision The baked semantic-review prompt and output schema are owned by -`context/vrs/16-enforcement/`. +`intent/16-enforcement/`. The first assets are: -- `context/vrs/16-enforcement/review-prompt.md`; -- `context/vrs/16-enforcement/review-result.schema.json`. +- `intent/16-enforcement/review-prompt.md`; +- `intent/16-enforcement/review-result.schema.json`. -`axe vrs review` consumes those assets. It does not define an alternative prompt +`intent review` consumes those assets. It does not define an alternative prompt contract and does not accept arbitrary prompts for the standard review mode. ## Consequences -- Prompt and schema changes are VRS changes, not Axe-only implementation +- Prompt and schema changes are Intent changes, not Axe-only implementation changes. - The review-smell catalog remains the rubric source, but enforcement owns the runnable review contract. -- Axe can package or reference the assets, but packaging must preserve VRS +- Axe can package or reference the assets, but packaging must preserve Intent ownership. - Eval fixtures should tune the prompt and schema before semantic review becomes a production gate. diff --git a/intent/.decisions/0024-put-semantic-review-fixtures-in-evaluation.md b/intent/.decisions/0024-put-semantic-review-fixtures-in-evaluation.md index c306cad..1aa8405 100644 --- a/intent/.decisions/0024-put-semantic-review-fixtures-in-evaluation.md +++ b/intent/.decisions/0024-put-semantic-review-fixtures-in-evaluation.md @@ -5,17 +5,17 @@ Status: accepted ## Context After placing the baked semantic-review prompt and schema in -`context/vrs/16-enforcement/`, VRS needs a home for the fixtures that tune and +`intent/16-enforcement/`, Intent needs a home for the fixtures that tune and regression-test those assets. -The ownership question is whether semantic-review fixtures belong with the VRS -evaluation subsystem, enforcement implementation evidence, Axe command +The ownership question is whether semantic-review fixtures belong with the Intent +evaluation subsystem, enforcement implementation evidence, CLI experiments, or tool test fixtures. ## Evidence and Argument The evaluation subsystem already owns isolated scenarios, evidence-backed -findings, and recommendation shape for VRS contract changes. Semantic-review +findings, and recommendation shape for Intent contract changes. Semantic-review fixtures are not the prompt/schema themselves; they are examples used to learn whether the prompt and schema produce useful review findings. @@ -33,25 +33,25 @@ evaluation evidence. | Option | Tradeoffs | | --- | --- | -| `context/vrs/15-evaluation/semantic-review/` | Keeps prompt-quality evidence with the evaluation subsystem and preserves VRS ownership, but requires a clear distinction between tracked fixtures and temporary eval output. | -| `context/vrs/16-enforcement/.experiments/` | Keeps fixtures near prompt/schema, but mixes reusable eval cases with enforcement implementation evidence. | -| `context/coding-agents/14-axe/12-vrs/.experiments/` | Good for CLI and CAIC integration prototypes, but makes Axe look like the owner of semantic-review quality. | -| `flakes/axe/tests/fixtures/vrs-review/` | Easy for tool tests, but separates semantic eval intent from the VRS source of truth. | +| `intent/15-evaluation/semantic-review/` | Keeps prompt-quality evidence with the evaluation subsystem and preserves Intent ownership, but requires a clear distinction between tracked fixtures and temporary eval output. | +| `intent/16-enforcement/.experiments/` | Keeps fixtures near prompt/schema, but mixes reusable eval cases with enforcement implementation evidence. | +| `context/coding-agents/14-axe/12-intent/.experiments/` | Good for CLI and CAIC integration prototypes, but makes Axe look like the owner of semantic-review quality. | +| `flakes/axe/tests/fixtures/intent-review/` | Easy for tool tests, but separates semantic eval intent from the Intent source of truth. | ## Decision Semantic-review eval fixtures live under -`context/vrs/15-evaluation/semantic-review/`. +`intent/15-evaluation/semantic-review/`. Tracked fixtures are canonical inputs and expected outcomes. Eval runs must copy or materialize them into isolated temporary workspaces before invoking -`axe vrs review`. +`intent review`. ## Consequences -- VRS evaluation owns prompt-quality evidence. +- Intent evaluation owns prompt-quality evidence. - Enforcement continues to own the baked prompt and schema. -- Axe VRS `.experiments/` remains appropriate for command-integration evidence, +- Intent CLI `.experiments/` remains appropriate for command-integration evidence, not semantic-review quality fixtures. - Tool tests may package or copy these fixtures, but must not become the source of truth for semantic-review intent. diff --git a/intent/.decisions/0025-start-semantic-review-with-smell-matrix.md b/intent/.decisions/0025-start-semantic-review-with-smell-matrix.md index 5dc10b7..0b4e1b0 100644 --- a/intent/.decisions/0025-start-semantic-review-with-smell-matrix.md +++ b/intent/.decisions/0025-start-semantic-review-with-smell-matrix.md @@ -5,20 +5,20 @@ Status: accepted ## Context Semantic-review fixtures now live under -`context/vrs/15-evaluation/semantic-review/`. The next question is which first +`intent/15-evaluation/semantic-review/`. The next question is which first fixtures should prove the baked review prompt and schema. The fixture set can start as a small smell matrix, a richer end-to-end scenario, a paired good/bad corpus for every artifact kind, or no fixtures until -`axe vrs review` is implemented. +`intent review` is implemented. ## Evidence and Argument -The baked prompt delegates review judgment to the meta-VRS review-smell catalog. +The baked prompt delegates review judgment to the root Intent contract review-smell catalog. The first fixtures should therefore exercise the highest-signal smells with one semantic concern per fixture. Narrow fixtures make prompt regressions easier to diagnose than one mixed scenario, and they avoid building a broad corpus -before `axe vrs review` has production command wiring. +before `intent review` has production command wiring. The selected smells cover core artifact-boundary drift: vision containing mechanism, requirements containing mechanism, specs containing decision @@ -44,7 +44,7 @@ The first semantic-review fixture set is a minimal review-smell matrix: - `stale-delta`. Each fixture contains one primary expected semantic finding and uses the full -`axe.vrs.review.v1` result shape. +`axe.intent.review.v1` result shape. ## Consequences diff --git a/intent/.decisions/0026-validate-semantic-review-fixtures-deterministically-first.md b/intent/.decisions/0026-validate-semantic-review-fixtures-deterministically-first.md index 2440650..291280d 100644 --- a/intent/.decisions/0026-validate-semantic-review-fixtures-deterministically-first.md +++ b/intent/.decisions/0026-validate-semantic-review-fixtures-deterministically-first.md @@ -5,7 +5,7 @@ Status: accepted ## Context The first semantic-review fixtures now exist under -`context/vrs/15-evaluation/semantic-review/`, but `axe vrs review` is not yet a +`intent/15-evaluation/semantic-review/`, but `intent review` is not yet a production command. The next question is how to validate those fixtures before a real LLM-backed review runner exists. @@ -15,14 +15,14 @@ eval, a real-provider eval, or no runner until review lands. ## Evidence and Argument The fixtures already contain structured machine-readable inputs: `fixture.json` -manifests, expected `axe.vrs.review.v1` results, fixture-relative artifact +manifests, expected `axe.intent.review.v1` results, fixture-relative artifact paths, and references to the baked prompt and schema. Those properties can be validated without invoking a coding agent. CAIC fake-provider evals prove invocation wiring but not semantic-review quality. Real-provider evals provide higher signal about prompt behavior, but they are slower and more variable than a local structural check. Waiting for -`axe vrs review` would leave the fixture corpus able to drift before it has a +`intent review` would leave the fixture corpus able to drift before it has a basic contract gate. ## Options @@ -47,7 +47,7 @@ diagnostic markers when diagnostics are present. It does not call ## Consequences - Fixture drift is caught before semantic review exists. -- Real-provider semantic evals remain a later layer after `axe vrs review` has +- Real-provider semantic evals remain a later layer after `intent review` has stable diagnostics and invocation wiring. - The deterministic checker can become a CI/Nix gate without introducing LLM flakiness. diff --git a/intent/.decisions/0027-use-minimum-assertions-for-real-semantic-review-evals.md b/intent/.decisions/0027-use-minimum-assertions-for-real-semantic-review-evals.md index 985cf43..2cb3732 100644 --- a/intent/.decisions/0027-use-minimum-assertions-for-real-semantic-review-evals.md +++ b/intent/.decisions/0027-use-minimum-assertions-for-real-semantic-review-evals.md @@ -5,7 +5,7 @@ Status: accepted ## Context Semantic-review fixtures can be checked structurally today. Later, -`axe vrs review` should run those fixtures through `$CODING_AGENT` and compare +`intent review` should run those fixtures through `$CODING_AGENT` and compare the returned review result with expected behavior. The assertion question is whether real semantic-review evals should require diff --git a/intent/.decisions/0028-real-token-evals-are-manual-only.md b/intent/.decisions/0028-real-token-evals-are-manual-only.md index 2cd55d2..c7909de 100644 --- a/intent/.decisions/0028-real-token-evals-are-manual-only.md +++ b/intent/.decisions/0028-real-token-evals-are-manual-only.md @@ -53,5 +53,5 @@ Automated checks may validate: - Real semantic-review quality checks remain available but intentional. - CI and Nix checks stay deterministic and token-free. -- Future `axe vrs review` or `axe vrs review-fixtures` commands must fail or +- Future `intent review` or `intent review-fixtures` commands must fail or refuse when invoked as automatic gates with real providers. diff --git a/intent/.decisions/0029-no-extra-token-spend-flag-for-review.md b/intent/.decisions/0029-no-extra-token-spend-flag-for-review.md index e713f1d..08e25db 100644 --- a/intent/.decisions/0029-no-extra-token-spend-flag-for-review.md +++ b/intent/.decisions/0029-no-extra-token-spend-flag-for-review.md @@ -4,17 +4,17 @@ Status: accepted ## Context -Decision 0028 established that real provider/model-token VRS evals are +Decision 0028 established that real provider/model-token Intent evals are manual-only and must not run from CI, Nix checks, hooks, scheduled jobs, or default automated validation. -The remaining question is whether `axe vrs review` also needs an extra +The remaining question is whether `intent review` also needs an extra invocation flag such as `--manual`, `--spend-tokens`, or `--allow-token-spend` to prove consent before calling a real provider. ## Evidence and Argument -`axe vrs review` is itself an explicit operator command. Requiring an additional +`intent review` is itself an explicit operator command. Requiring an additional flag makes the command more ceremonious without adding a stronger automation boundary. The actual safety property is that automated environments must not invoke a real provider. That is enforced by refusing CI and other known @@ -36,7 +36,7 @@ the command surface should stay simple. ## Decision -`axe vrs review` does not require an extra token-spend or manual-confirmation +`intent review` does not require an extra token-spend or manual-confirmation flag. The command must fail before provider invocation when it detects CI or another diff --git a/intent/.decisions/0030-keep-enforcement-consumer-agnostic.md b/intent/.decisions/0030-keep-enforcement-consumer-agnostic.md index fe51d0b..9b247f5 100644 --- a/intent/.decisions/0030-keep-enforcement-consumer-agnostic.md +++ b/intent/.decisions/0030-keep-enforcement-consumer-agnostic.md @@ -4,25 +4,25 @@ Status: accepted ## Context -The VRS enforcement spec originally included a consumer table that named -`axe vrs`, Nix checks, `grill-vrs`, and future `axe plan` behavior. A real -`codex` semantic review of `context/vrs/16-enforcement` flagged this as a +The Intent enforcement spec originally included a consumer table that named +`intent`, Nix checks, `grill-intent`, and future `axe plan` behavior. A real +`codex` semantic review of `intent/16-enforcement` flagged this as a semantic-ownership smell: enforcement was starting to assign command-surface and workflow behavior that should be owned by the consuming subsystems. The user chose a strict ownership split: enforcement should define checks, severity, evidence, semantic review assets, and reusable interfaces only; Axe -VRS and other consumers should own their command surfaces and provider +Intent and other consumers should own their command surfaces and provider invocation details. ## Evidence and Argument The ownership issue was found by a bounded manual real-provider run of -`axe vrs review context/vrs/16-enforcement --backend codex` after the initial +`intent review intent/16-enforcement --backend codex` after the initial ownership cleanup. The review succeeded but still reported -`VRS.REVIEW.semantic-ownership` against the enforcement spec's consumer table. +`INTENT.REVIEW.semantic-ownership` against the enforcement spec's consumer table. -The existing Axe VRS spec already owns CLI behavior, provider-readiness checks, +The existing Intent CLI spec already owns CLI behavior, provider-readiness checks, stdout/report routing, and CI token-spend guards. Keeping consumer behavior in the enforcement spec duplicates that contract and creates drift risk. A consumer-agnostic enforcement contract also composes better with future @@ -39,7 +39,7 @@ Axe-specific workflow semantics. ## Decision -VRS enforcement is consumer-agnostic. +Intent enforcement is consumer-agnostic. The enforcement spec defines: @@ -50,13 +50,13 @@ The enforcement spec defines: - reusable checker/review interfaces. Consumer specs define their own command surfaces, invocation policies, storage, -report routing, and exit-code behavior. In particular, the Axe VRS spec owns -`axe vrs` commands and provider execution policy. +report routing, and exit-code behavior. In particular, the Intent CLI spec owns +`intent` commands and provider execution policy. ## Consequences - Enforcement no longer enumerates concrete consumer command behavior. -- Semantic-review findings about VRS ownership should route command-surface - details to the relevant consumer VRS instead of `context/vrs/16-enforcement`. +- Semantic-review findings about Intent ownership should route command-surface + details to the relevant consumer Intent instead of `intent/16-enforcement`. - Future consumers can reuse enforcement outputs without becoming part of the enforcement contract. diff --git a/intent/.decisions/0031-diagrams-use-full-mermaid-previewer-advisory.md b/intent/.decisions/0031-diagrams-use-full-mermaid-previewer-advisory.md index b5c53e2..fece4e3 100644 --- a/intent/.decisions/0031-diagrams-use-full-mermaid-previewer-advisory.md +++ b/intent/.decisions/0031-diagrams-use-full-mermaid-previewer-advisory.md @@ -4,7 +4,7 @@ Status: accepted ## Context -VRS and `context/` docs open non-trivial sections with the clearest structural +Intent and `context/` docs open non-trivial sections with the clearest structural representation, often a Mermaid diagram (see [03-spec](../03-spec/spec.md)). Diagrams have two render paths: an inline terminal/nvim ASCII preview (`mermaid-ascii`, which parses only flowchart/graph and a minimal diff --git a/intent/.decisions/0032-rename-glossary-artifact-to-ontology.md b/intent/.decisions/0032-rename-glossary-artifact-to-ontology.md index 4127dac..311c147 100644 --- a/intent/.decisions/0032-rename-glossary-artifact-to-ontology.md +++ b/intent/.decisions/0032-rename-glossary-artifact-to-ontology.md @@ -4,12 +4,12 @@ Status: accepted ## Context -The VRS language artifact was `glossary.md`: a flat list of canonical terms and +The Intent language artifact was `glossary.md`: a flat list of canonical terms and definitions (a lookup). In practice several nodes already carried relationship structure inside it (anchors, siblings, composition seams), which a glossary does not model. Separately, the reusable discipline of *designing* a term system — relationships, leitwort hierarchy, exposure/priority — had no home; -[0015](./0015-glossary-handling-lives-in-grill-vrs.md) deferred a separate +[0015](./0015-glossary-handling-lives-in-grill-intent.md) deferred a separate skill. ## Evidence and Argument @@ -29,7 +29,7 @@ wording remains true. The separate `/sk-ontology` and `/sk-naming` disciplines also satisfy the unowned term-design concern recorded by -[0015](./0015-glossary-handling-lives-in-grill-vrs.md) without moving the VRS +[0015](./0015-glossary-handling-lives-in-grill-intent.md) without moving the Intent interview's responsibility for applying the artifact contract. ## Options @@ -42,14 +42,14 @@ interview's responsibility for applying the artifact contract. ## Decision -The VRS language artifact is `ontology.md`. An ontology is the language layer +The Intent language artifact is `ontology.md`. An ontology is the language layer (canonical terms — the former glossary, still the minimal form) plus an optional structure layer (relationships + leitwort), added lazily. The term-design discipline lives in two general skills — `/sk-ontology` (the term system) and `/sk-naming` (a single term) — which satisfy the condition -[0015](./0015-glossary-handling-lives-in-grill-vrs.md) reserved for a separate -skill. This supersedes 0015: `grill-vrs` still owns applying the ontology -contract during interviews (VRS-R24, VRS.GRILL-R08); the skills own the +[0015](./0015-glossary-handling-lives-in-grill-intent.md) reserved for a separate +skill. This supersedes 0015: `grill-intent` still owns applying the ontology +contract during interviews (INTENT-R24, INTENT.GRILL-R08); the skills own the reusable discipline it applies. The subsystem contract moves to [../04-ontology/](../04-ontology/). diff --git a/intent/.decisions/0033-decision-and-delta-ordinals-stay-subsystem-local-citation-carries-the-qualification.md b/intent/.decisions/0033-decision-and-delta-ordinals-stay-subsystem-local-citation-carries-the-qualification.md index 5b64ff2..cdae981 100644 --- a/intent/.decisions/0033-decision-and-delta-ordinals-stay-subsystem-local-citation-carries-the-qualification.md +++ b/intent/.decisions/0033-decision-and-delta-ordinals-stay-subsystem-local-citation-carries-the-qualification.md @@ -55,7 +55,7 @@ an allocation rule — a pure citation convention would leave the mechanism runn A bare ordinal is a subsystem-local name. Reading it as an identifier is legitimate only inside its own subsystem, and only if allocation keeps it unique there. Three -rules make that true; `nix/scripts/vrs-id-check/vrs-id-check.ts` enforces all three +rules make that true; `nix/scripts/intent-id-check/intent-id-check.ts` enforces all three against a ratcheting baseline, the same idiom as the link-resolution gate. **ALLOC — one ordinal, one file, per directory.** Within a `.decisions/` or `.delta/` diff --git a/intent/.decisions/0034-proposal-exit-is-enforced-at-merge-not-relaxed.md b/intent/.decisions/0034-proposal-exit-is-enforced-at-merge-not-relaxed.md index 36082b5..377028a 100644 --- a/intent/.decisions/0034-proposal-exit-is-enforced-at-merge-not-relaxed.md +++ b/intent/.decisions/0034-proposal-exit-is-enforced-at-merge-not-relaxed.md @@ -4,8 +4,8 @@ Status: accepted ## Context -`VRS.DEC-R10` confines proposed decision records to `.decisions/.proposed/` -"during a PR only", and `VRS.DEC-R11` requires every proposed record to be +`INTENT.DEC-R10` confines proposed decision records to `.decisions/.proposed/` +"during a PR only", and `INTENT.DEC-R11` requires every proposed record to be accepted, folded into another artifact, moved to `open-questions.md`, or deleted **before merge**. @@ -31,7 +31,7 @@ unenforced one becomes. Ten days unratified is already the graveyard failure the durable-state option would have had to design against, observed before the option was adopted. -The principal's stated direction is that decisions touching VRS should route +The principal's stated direction is that decisions touching Intent should route through the proposal mechanism with an explicit ratification step — which the existing contract already provides. What was missing was enforcement, not a new state. diff --git a/intent/.decisions/0035-extract-to-a-fresh-repository-with-a-fresh-init-not-filtered-history.md b/intent/.decisions/0035-extract-to-a-fresh-repository-with-a-fresh-init-not-filtered-history.md index 6530ebf..18bf72b 100644 --- a/intent/.decisions/0035-extract-to-a-fresh-repository-with-a-fresh-init-not-filtered-history.md +++ b/intent/.decisions/0035-extract-to-a-fresh-repository-with-a-fresh-init-not-filtered-history.md @@ -8,11 +8,11 @@ This corpus was authored inside `schickling/dotfiles`, a private repository, and now lives in `compoundingtech/intent`, which is destined to become public. The extraction moved two things at once: -- `context/vrs/` (106 files) became this repository's `intent/`, verbatim, with - section names and internal layout unchanged. -- `context/coding-agents/14-axe/12-vrs/` (5 files) became `context/cli/` — the - contract for the checker that enforces this corpus, which is a consumer of the - methodology rather than part of it, and so sits outside `intent/`. +- The originating corpus subtree (106 files) became this repository's `intent/`, + with section names and internal layout unchanged. +- The originating Axe checker contract (5 files) became `context/cli/`. It is a + consumer of the methodology rather than part of it, so it sits outside + `intent/`. Both were taken from `schickling/dotfiles` at commit `1b246bed551e520975e06ccdbb998f72ec8a5d9d`. @@ -28,9 +28,9 @@ The history that would have been carried over, measured against the source commi | What | Path set | Commits | | --- | --- | --- | -| The corpus | `context/vrs` | 57 | -| The corpus plus the checker source | `context/vrs`, `flakes/axe/src/vrs.rs` | 64 | -| The CLI subsystem contract | `context/coding-agents/14-axe/12-vrs` | 24 | +| The corpus | Originating corpus subtree | 57 | +| The corpus plus the checker source | Corpus subtree and checker source | 64 | +| The CLI subsystem contract | Originating Axe checker subtree | 24 | Those spans run **2026-06-18 to 2026-07-30** by committer date. Author dates begin one day earlier, 2026-06-17 — the first two corpus commits were authored that @@ -74,14 +74,15 @@ Concretely, and for the record: - **Origin:** `schickling/dotfiles`, private. - **Source commit:** `1b246bed551e520975e06ccdbb998f72ec8a5d9d`. -- **Corpus history at that commit:** 57 commits touching `context/vrs`, or 64 +- **Corpus history at that commit:** 57 commits touching the originating corpus + subtree, or 64 counting the checker source alongside it, spanning 2026-06-18 to 2026-07-30 by committer date. - **Full history remains in `schickling/dotfiles`** and is available there to anyone with access to that repository. It was not rewritten, and nothing was discarded — only not copied. -- **`context/coding-agents/14-axe/12-vrs/` moved in the same extraction**, to - `context/cli/`, and its own 24 commits are covered by the same reasoning. +- **The Axe checker contract moved in the same extraction** to `context/cli/`, + and its own 24 commits are covered by the same reasoning. ## Consequences @@ -99,13 +100,13 @@ Two consequences of the move itself are recorded here because they are otherwise invisible in the result: **The CLI subsystem lost its parent edge.** In the originating repository, -`14-axe/12-vrs/requirements.md` built on `14-axe/requirements.md`, the contract of -the host tool it was a subsystem of. That parent did not move and does not exist -here, so the edge was removed rather than rewritten to prose. Keeping any form of -it would have asserted a relationship that is no longer true while making it -unverifiable — the precise failure this corpus exists to prevent. `context/cli/` -is a root node in this repository. If it should later refine something here, that -is a deliberate authoring decision to be taken on its own merits. +the checker contract built on the contract of its host tool. That parent did not +move and does not exist here, so the edge was removed rather than rewritten to +prose. Keeping any form of it would have asserted a relationship that is no +longer true while making it unverifiable — the precise failure this corpus +exists to prevent. `context/cli/` is a root node in this repository. If it should +later refine something here, that is a deliberate authoring decision to be taken +on its own merits. **Six citations that pointed outside the corpus were rewritten.** They named records in `context/coding-agents/` and `context/observability/` that remain diff --git a/intent/.decisions/0036-use-intent-as-the-only-layer-name.md b/intent/.decisions/0036-use-intent-as-the-only-layer-name.md new file mode 100644 index 0000000..9c8704c --- /dev/null +++ b/intent/.decisions/0036-use-intent-as-the-only-layer-name.md @@ -0,0 +1,48 @@ +# Use Intent as the only layer and system name + +Status: accepted + +## Context + +The repository, corpus directory, checker crate, binary, and operational skill +already use the name Intent, while the normative corpus and machine contracts +retained a second concrete system name. The two-name model made it unclear +whether Intent named the repository, the conceptual layer, or the artifact +system itself. + +The repository owner approved completing the rename so one name covers the +layer, corpus, artifacts, checker, and public contracts. + +## Evidence and Argument + +Before the migration, the retired name appeared 1,298 times across 113 of 125 +tracked files and in 13 tracked paths. It was embedded in prose, requirement and +rule IDs, JSON schema versions, Rust public types, accepted document headings, +tests, fixtures, and CI assertions. Keeping compatibility spellings would leave +the ambiguity in precisely the machine-readable surfaces where a canonical name +matters most. + +Intent already names the repository, `intent/` corpus, `intent` CLI, crate, and +skill. Using it for the documentation system as well removes a translation rule +without changing the artifact model. + +## Options + +| Option | Tradeoffs | +| --- | --- | +| Keep two names | Avoids a breaking migration, but preserves ambiguity in prose and machine contracts. | +| Rename prose only | Improves onboarding, but leaves code, paths, rules, schemas, and fixtures teaching the retired name. | +| Use Intent everywhere | Creates one coordinated breaking change and one canonical vocabulary across every surface. | + +## Decision + +Use **Intent** as the only name for the project's intent layer, documentation +system, corpus, artifacts, nodes, checker contracts, and operational procedures. +Use lowercase `intent` for filesystem paths, command names, crate/package names, +and schema namespace components; use uppercase `INTENT` in structured IDs and +diagnostic rule namespaces. + +Rename all affected surfaces atomically. Do not retain compatibility aliases in +this repository, because an alias would preserve the two-name model. Downstream +consumers must migrate their command names, schema-version checks, rule IDs, and +document grammar in the same release boundary. diff --git a/intent/.experiments/decision-shape-enforcement.md b/intent/.experiments/decision-shape-enforcement.md index e65de48..9603435 100644 --- a/intent/.experiments/decision-shape-enforcement.md +++ b/intent/.experiments/decision-shape-enforcement.md @@ -2,12 +2,12 @@ ## Question -Can decision-record shape checks become a useful deterministic VRS enforcement +Can decision-record shape checks become a useful deterministic Intent enforcement rule without pretending to judge semantic decision quality? ## Hypothesis -Decision-record shape checks can become a useful deterministic VRS enforcement +Decision-record shape checks can become a useful deterministic Intent enforcement rule if they catch missing evidence, options, tradeoffs, and rationale without pretending to judge semantic decision quality. @@ -18,7 +18,7 @@ Three evidence paths were explored: - fixture/prototype direction: design good and bad decision records and test whether a mechanical checker distinguishes missing structure from compliant records; -- corpus dry run: scan existing decision records for the meta-VRS minimum +- corpus dry run: scan existing decision records for the root Intent contract minimum shape; - agent-eval direction: compare decision drafting with only prose guidance versus drafting with an explicit checker-style rubric. @@ -33,15 +33,15 @@ records with a simple mechanical predicate: ## Result -The meta-VRS corpus is compatible with the proposed mechanical minimum: the -current `context/vrs/.decisions/000*.md` records use the required sections and +The root Intent contract corpus is compatible with the proposed mechanical minimum: the +current `intent/.decisions/000*.md` records use the required sections and options-table shape. The wider repository corpus is not ready for repo-wide blocking promotion. A local scan found 51 durable decision records under `context/**/.decisions/` and 40 records missing at least one part of the proposed strict mechanical shape. Most misses are older or subsystem-local records that predate the current -meta-VRS decision contract. +root Intent contract decision contract. The agent-eval direction found that checker-style guidance improves authoring behavior: agents are less likely to skip evidence, options, tradeoffs, and @@ -83,9 +83,9 @@ Local Markdown link existence should remain the first blocking deterministic gate. Decision shape is a second candidate for the mechanical subset only after fixture and corpus evidence are green. -## VRS Impact +## Intent Impact Supports the deterministic enforcement scope in [16-enforcement/spec.md](../16-enforcement/spec.md): decision-shape checks are -valuable for the meta-VRS corpus, but broad blocking promotion should wait for +valuable for the root Intent contract corpus, but broad blocking promotion should wait for fixture coverage and migration of older decision records. diff --git a/intent/.experiments/link-structure-and-symbolic-references.md b/intent/.experiments/link-structure-and-symbolic-references.md index d6e34f9..ea6526e 100644 --- a/intent/.experiments/link-structure-and-symbolic-references.md +++ b/intent/.experiments/link-structure-and-symbolic-references.md @@ -2,7 +2,7 @@ ## Question -What reference structure should VRS prefer for cross-references that must remain +What reference structure should Intent prefer for cross-references that must remain internally consistent within one repository commit: relative Markdown links plus scoped IDs, wiki-style links, or symbolic references backed by a resolver? @@ -11,20 +11,20 @@ scoped IDs, wiki-style links, or symbolic references backed by a resolver? Three isolated probes compared existing repository usage and temporary refactor scenarios: -- scan existing VRS-heavy trees for Markdown links, wiki links, and ID-like +- scan existing Intent-heavy trees for Markdown links, wiki links, and ID-like references; -- simulate a VRS split/move/renumbering under `/tmp`; +- simulate an Intent split/move/renumbering under `/tmp`; - compare longer-term structured representations such as Markdown conventions, sidecar metadata, generated Markdown, and typed Markdown parsing. ## Result -Relative Markdown links dominate current VRS-like docs. In the sampled -VRS-heavy areas, Markdown links substantially outnumbered wiki links, while +Relative Markdown links dominate current Intent-like docs. In the sampled +Intent-heavy areas, Markdown links substantially outnumbered wiki links, while ID-like references were already common. Wiki-style links were concentrated in a smaller set of docs and became -ambiguous in hierarchical VRS scenarios because VRS intentionally repeats file +ambiguous in hierarchical Intent scenarios because Intent intentionally repeats file names such as `requirements.md` and `spec.md` across child nodes. The refactor simulation found that symbolic or namespaced IDs backed by a @@ -33,12 +33,12 @@ path-only references. Plain Markdown links remained useful for navigation but required manual updates after moves. The structured-representation probe favored a typed Markdown hybrid: Markdown -remains the authored medium, while tooling parses VRS artifacts into a typed +remains the authored medium, while tooling parses Intent artifacts into a typed graph for validation, backlinks, rename plans, and optional projections. ## Conclusion -Canonical VRS references should be stricter than optional wiki links: +Canonical Intent references should be stricter than optional wiki links: - use scoped, symbolic, or namespaced IDs for clause identity within the current commit; @@ -46,12 +46,12 @@ Canonical VRS references should be stricter than optional wiki links: - do not treat wiki-style links as canonical normative references unless a resolver can prove they are unique and unambiguous. -Longer term, VRS should move toward a typed Markdown graph rather than a loose +Longer term, Intent should move toward a typed Markdown graph rather than a loose collection of Markdown conventions. -## VRS Impact +## Intent Impact -Supports the roadmap entry for structured VRS representation in +Supports the roadmap entry for structured Intent representation in [roadmap.md](../roadmap.md). It should inform future updates to [02-requirements](../02-requirements/spec.md), [03-spec](../03-spec/spec.md), and diff --git a/intent/01-vision/requirements.md b/intent/01-vision/requirements.md index 21ea507..e97e266 100644 --- a/intent/01-vision/requirements.md +++ b/intent/01-vision/requirements.md @@ -1,24 +1,24 @@ -# VRS Vision — Requirements +# Intent Vision — Requirements ## Context -- This child node defines the contract for `vision.md` files in VRS nodes. -- It refines [VRS-R01](../requirements.md) and [VRS-R03](../requirements.md). +- This child node defines the contract for `vision.md` files in Intent nodes. +- It refines [INTENT-R01](../requirements.md) and [INTENT-R03](../requirements.md). ## Requirements ### Must Define Durable Intent -- **VRS.VIS-R01 Purpose:** A vision must explain why the VRS node exists and +- **INTENT.VIS-R01 Purpose:** A vision must explain why the Intent node exists and what durable success means. -- **VRS.VIS-R02 No implementation choices:** A vision must not prescribe +- **INTENT.VIS-R02 No implementation choices:** A vision must not prescribe architecture, tools, technologies, or mechanisms. -- **VRS.VIS-R03 Explicit exclusions:** A vision must say what the system is not +- **INTENT.VIS-R03 Explicit exclusions:** A vision must say what the system is not when common misreadings would otherwise expand scope. ### Must Be Protected -- **VRS.VIS-R04 Confirmed edits:** A vision change must be confirmed because it +- **INTENT.VIS-R04 Confirmed edits:** A vision change must be confirmed because it changes goals or problem framing. -- **VRS.VIS-R05 Stable criteria:** Success criteria must be measurable enough to +- **INTENT.VIS-R05 Stable criteria:** Success criteria must be measurable enough to evaluate whether the system is serving the vision. diff --git a/intent/01-vision/spec.md b/intent/01-vision/spec.md index 4f91a67..34f9433 100644 --- a/intent/01-vision/spec.md +++ b/intent/01-vision/spec.md @@ -1,4 +1,4 @@ -# VRS Vision — Spec +# Intent Vision — Spec This document specifies `vision.md` files. It builds on [requirements.md](./requirements.md). diff --git a/intent/02-requirements/requirements.md b/intent/02-requirements/requirements.md index 33fe123..9c93e70 100644 --- a/intent/02-requirements/requirements.md +++ b/intent/02-requirements/requirements.md @@ -1,37 +1,37 @@ -# VRS Requirements — Requirements +# Intent Requirements — Requirements ## Context -- This child node defines the contract for `requirements.md` files in VRS nodes. -- It refines [VRS-R01](../requirements.md), [VRS-R03](../requirements.md), and - [VRS-R06](../requirements.md). +- This child node defines the contract for `requirements.md` files in Intent nodes. +- It refines [INTENT-R01](../requirements.md), [INTENT-R03](../requirements.md), and + [INTENT-R06](../requirements.md). ## Requirements ### Must Be Testable -- **VRS.REQ-R01 Testable constraints:** Every requirement must describe an +- **INTENT.REQ-R01 Testable constraints:** Every requirement must describe an externally checkable constraint, not an implementation choice. -- **VRS.REQ-R02 Assumptions explicit:** Load-bearing assumptions must be listed +- **INTENT.REQ-R02 Assumptions explicit:** Load-bearing assumptions must be listed with IDs that are unique in their declared scope. -- **VRS.REQ-R03 Assumptions validated:** Load-bearing assumptions must be - validated in the best feasible way before they become durable VRS truth, or +- **INTENT.REQ-R03 Assumptions validated:** Load-bearing assumptions must be + validated in the best feasible way before they become durable Intent truth, or tracked as blocked open questions with a resolution signal. -- **VRS.REQ-R04 Tradeoffs explicit:** Accepted compromises must be listed with +- **INTENT.REQ-R04 Tradeoffs explicit:** Accepted compromises must be listed with IDs that are unique in their declared scope unless they warrant a decision record. -- **VRS.REQ-R05 Constraints explicit:** Non-negotiable environmental, +- **INTENT.REQ-R05 Constraints explicit:** Non-negotiable environmental, operational, platform, regulatory, resource, or integration limits must be listed as constraints rather than mixed into desired behavior. -- **VRS.REQ-R06 Referenced constraints:** Constraints derived from external +- **INTENT.REQ-R06 Referenced constraints:** Constraints derived from external systems, standards, APIs, vendors, or platform behavior must cite `.reference/` material. ### Must Stay Navigable -- **VRS.REQ-R07 Size bound:** A requirements file should stay below 30 - requirements and must stay below 40; larger scopes require child VRS nodes. -- **VRS.REQ-R08 Scoped IDs:** Requirements, assumptions, constraints, and +- **INTENT.REQ-R07 Size bound:** A requirements file should stay below 30 + requirements and must stay below 40; larger scopes require child Intent nodes. +- **INTENT.REQ-R08 Scoped IDs:** Requirements, assumptions, constraints, and tradeoffs must use IDs whose scope is clear from the artifact or namespace. -- **VRS.REQ-R09 Atomic consistency:** When IDs are renamed, renumbered, moved, or +- **INTENT.REQ-R09 Atomic consistency:** When IDs are renamed, renumbered, moved, or re-scoped, all cross-references must be updated in the same commit. diff --git a/intent/02-requirements/spec.md b/intent/02-requirements/spec.md index e3937e8..46b8aab 100644 --- a/intent/02-requirements/spec.md +++ b/intent/02-requirements/spec.md @@ -1,4 +1,4 @@ -# VRS Requirements — Spec +# Intent Requirements — Spec This document specifies `requirements.md` files. It builds on [requirements.md](./requirements.md). @@ -34,13 +34,13 @@ Draft. - **-R01 Short name:** ... ``` -Use a semantic namespace (`VRS`, `VRS.REQ`, `CVG.ACT`) when references cross +Use a semantic namespace (`Intent`, `INTENT.REQ`, `CVG.ACT`) when references cross artifact, child-node, or project boundaries. Local IDs such as `R01` are acceptable inside one declared requirements scope when every reference is unambiguous from context. Numeric directory prefixes do not appear in IDs. IDs are not permanent public API. They may be renamed, renumbered, or re-scoped -when the VRS shape improves, but the repository commit must remain atomically +when the Intent shape improves, but the repository commit must remain atomically consistent: every reference in that commit resolves to the intended current artifact and clause. diff --git a/intent/03-spec/requirements.md b/intent/03-spec/requirements.md index a1a6de8..55f24aa 100644 --- a/intent/03-spec/requirements.md +++ b/intent/03-spec/requirements.md @@ -1,26 +1,26 @@ -# VRS Spec — Requirements +# Intent Spec — Requirements ## Context -- This child node defines the contract for `spec.md` files in VRS nodes. -- It refines [VRS-R01](../requirements.md), [VRS-R02](../requirements.md), and - [VRS-R12](../requirements.md). +- This child node defines the contract for `spec.md` files in Intent nodes. +- It refines [INTENT-R01](../requirements.md), [INTENT-R02](../requirements.md), and + [INTENT-R12](../requirements.md). ## Requirements ### Must Be Implementable -- **VRS.SPEC-R01 Blueprint:** A spec must be detailed enough to implement +- **INTENT.SPEC-R01 Blueprint:** A spec must be detailed enough to implement without guessing the intended behavior. -- **VRS.SPEC-R02 Requirement traceability:** Spec sections must reference the +- **INTENT.SPEC-R02 Requirement traceability:** Spec sections must reference the requirements they satisfy using IDs that resolve unambiguously within the current commit. -- **VRS.SPEC-R03 Concrete shapes:** Data formats, APIs, state machines, flows, +- **INTENT.SPEC-R03 Concrete shapes:** Data formats, APIs, state machines, flows, and config surfaces must be represented concretely. ### Must Stay Current -- **VRS.SPEC-R04 Living document:** When implementation diverges, either the +- **INTENT.SPEC-R04 Living document:** When implementation diverges, either the implementation or the spec must change. -- **VRS.SPEC-R05 Design questions:** Unresolved design questions must be marked +- **INTENT.SPEC-R05 Design questions:** Unresolved design questions must be marked explicitly and linked to `open-questions.md` when they need tracking. diff --git a/intent/03-spec/spec.md b/intent/03-spec/spec.md index 2e2d745..d065e2d 100644 --- a/intent/03-spec/spec.md +++ b/intent/03-spec/spec.md @@ -1,4 +1,4 @@ -# VRS Spec — Spec +# Intent Spec — Spec This document specifies `spec.md` files. It builds on [requirements.md](./requirements.md). diff --git a/intent/04-ontology/.experiments/ontology-sota-survey.md b/intent/04-ontology/.experiments/ontology-sota-survey.md index 45d661c..633fb38 100644 --- a/intent/04-ontology/.experiments/ontology-sota-survey.md +++ b/intent/04-ontology/.experiments/ontology-sota-survey.md @@ -40,12 +40,12 @@ the last: | Level | Adds | Our equivalent | | --- | --- | --- | -| **Controlled vocabulary** | one authorized term per concept | `## Language` list + `VRS.ONT-R01` canonical term | +| **Controlled vocabulary** | one authorized term per concept | `## Language` list + `INTENT.ONT-R01` canonical term | | **Taxonomy** | hierarchy (broader/narrower) | `## Structure` with hierarchy | | **Thesaurus** | associative (`related`) + synonyms (`altLabel`) | `related` edges + `_Avoid_` / alt labels | | **Ontology** | typed, specialized relations + formal semantics | #1180 typed edges (`isa`/`partOf`/`dependsOn`/…) | -This ladder is exactly our "lazy structure" rule (`VRS.ONT-R06`): a flat glossary +This ladder is exactly our "lazy structure" rule (`INTENT.ONT-R06`): a flat glossary is a controlled vocabulary; you climb only when a relationship carries weight. **Adopt this as the one-line backbone** for the artifact's levels — it gives "minimal ontology = flat term list" a recognized name (controlled vocabulary) and @@ -65,7 +65,7 @@ them): `narrowMatch`, `relatedMatch`, `closeMatch`, `exactMatch`. Key mappings and one deliberate divergence: -- `prefLabel` == our canonical term (`VRS.ONT-R01`). +- `prefLabel` == our canonical term (`INTENT.ONT-R01`). - `altLabel` == our true synonyms; `avoid` ≈ `hiddenLabel` **(loose** — hiddenLabel means "match on it but don't show it"; ours means "don't use it"). - `related` == our "orthogonal / see-also" associative link. @@ -121,7 +121,7 @@ introduce upper-ontology vocabulary. (Sources: BFO/Wikipedia, Barry Smith.) ### DDD ubiquitous language / bounded contexts — the *why* of a per-subsystem ontology Evans: one shared, consistent vocabulary **within an explicitly bounded context**; outside it, the same word may mean something else. This is precisely -our per-subsystem `ontology.md` + the VRS `## Flagged ambiguities` mechanism for +our per-subsystem `ontology.md` + the Intent `## Flagged ambiguities` mechanism for a child that narrows a parent term. It's the strongest existing-practice justification for *scoping* ontologies to subsystems rather than one global glossary. Maps to SKOS **concept scheme** boundaries (below). (Sources: Evans; @@ -152,7 +152,7 @@ hygiene; these guidelines add nothing Claude doesn't know — **cite-don't-teach ("what identifier shape does this imply?"). #1180's edges are *checkable SoT relations*. They are **not competitors** — the naming-relevant edges are a **subset** of the full typed-edge set. So we want ONE set of edge *names* shared -across skill + VRS + #1180, with a marked subset that shapes names. This closes a +across skill + Intent + #1180, with a marked subset that shapes names. This closes a **bidirectional gap**: the skill's `orthogonal` has no #1180 edge, and #1180's `dependsOn`/`related` have no lens in the skill's five. @@ -161,7 +161,7 @@ Two tiers, mirroring SKOS (labels vs semantic relations): ### Tier A — lexical labels (point at strings) | Our term | SKOS | #1180 | Notes | | --- | --- | --- | --- | -| canonical term | `prefLabel` | `label` / `prefLabel` | one per concept (`VRS.ONT-R01`) | +| canonical term | `prefLabel` | `label` / `prefLabel` | one per concept (`INTENT.ONT-R01`) | | synonym / alt | `altLabel` | `altLabel` | true interchangeable names | | `_Avoid_` | `hiddenLabel` *(loose)* | `avoid` | ours = "don't use"; hiddenLabel = "match, don't show" | @@ -178,7 +178,7 @@ Two tiers, mirroring SKOS (labels vs semantic relations): | *(no lens)* — associative "see also" | `related` | object property | `related` | No | | *(no lens)* — spec specialization | `narrower` (weak) | `subPropertyOf` | `refines` | Maybe — a narrowing, ≈ `isa` flavor | -### Recommended ONE edge vocabulary (standardize across skill + VRS + #1180) +### Recommended ONE edge vocabulary (standardize across skill + Intent + #1180) Adopt #1180's typed-edge nouns as the canonical set; they already mirror SKOS/OWL and are the machine-checkable SoT everything else projects from: @@ -214,9 +214,9 @@ layers}. Those are what `/sk-ontology` reasons about to shape identifiers; - Cross-scheme identity: prefer in-scheme `altLabel` over `exactMatch`/`sameAs` merges (`owl:sameAs` hazard). -**VRS inheritance backing:** #1180's cross-file import ("inherited from +**Intent inheritance backing:** #1180's cross-file import ("inherited from `../glossary.md`") == SKOS **`inScheme` + concept-scheme boundaries**. That's the -SOTA backing for the VRS spec's "inheritance flows downward; a child defines only +SOTA backing for the Intent spec's "inheritance flows downward; a child defines only new terms/structure/ambiguity." Worth one line in the contract. --- @@ -229,8 +229,8 @@ report may explain SKOS fully; skill additions must be house-specific and cheap. ### The one fork that matters — how to unify the edge vocabulary | Option | What | Trade-off | Token bar | | --- | --- | --- | --- | -| **3A — rename the five to edge-names now** | `/sk-ontology` + VRS `04-ontology` adopt `isa/partOf/refines/dependsOn/related` (+ `altLabel`/`avoid`), mark naming-relevant subset, drop `set`, rename `orthogonal`→facet | No drift; but churns two skills + VRS contract and formalizes an edge set *ahead of* the tooling that enforces it (#1180) | **Passes** — the shared vocabulary is house-specific and prevents drift; keep the SKOS/OWL rationale as a one-line pointer, don't teach it | -| **3B — keep the five as lenses now; align names only when #1180 lands** | Fix only the clear bugs now (`set` split, leitwort attribution, "facet"); defer full edge-name unification to when the typed SoT exists | No premature churn; but skill/VRS/#1180 drift in the meantime (the exact risk the task flags) | Passes; minimal edits | +| **3A — rename the five to edge-names now** | `/sk-ontology` + Intent `04-ontology` adopt `isa/partOf/refines/dependsOn/related` (+ `altLabel`/`avoid`), mark naming-relevant subset, drop `set`, rename `orthogonal`→facet | No drift; but churns two skills + Intent contract and formalizes an edge set *ahead of* the tooling that enforces it (#1180) | **Passes** — the shared vocabulary is house-specific and prevents drift; keep the SKOS/OWL rationale as a one-line pointer, don't teach it | +| **3B — keep the five as lenses now; align names only when #1180 lands** | Fix only the clear bugs now (`set` split, leitwort attribution, "facet"); defer full edge-name unification to when the typed SoT exists | No premature churn; but skill/Intent/#1180 drift in the meantime (the exact risk the task flags) | Passes; minimal edits | | **3C — minimal: add mapping table as reference, change nothing structural** | Paste the Tier-A/Tier-B mapping into the skill as a "lineage" aside | Cheapest; but a table the skill doesn't act on is frozen state → violates write-skill "no frozen state" | **Fails** the token bar — don't do 3C | **Recommendation: 3A for the edge *names* + 3B's bug-fixes**, i.e. unify the @@ -262,8 +262,8 @@ Cite-don't-teach: SKOS/OWL/DDD get pointer mentions only. coupling between independent dimensions"). Everything else here **fails** the bar (Claude knows naming conventions). -### VRS `04-ontology` contract — specific edits -- Rename the relationship enumeration in `VRS.ONT-R06` to the unified vocabulary +### Intent `04-ontology` contract — specific edits +- Rename the relationship enumeration in `INTENT.ONT-R06` to the unified vocabulary (keep it a *may*, keep lazy-structure). - Add one line: downward inheritance == SKOS `inScheme` / concept-scheme boundaries (SOTA backing for the existing rule). @@ -275,7 +275,7 @@ freshness — these are the epic's job, not the prose contract. ## 4. Where our current skills are wrong / redundant / misaligned -1. **`set` conflates subset and membership** (`/sk-ontology`, VRS `VRS.ONT-R06`). +1. **`set` conflates subset and membership** (`/sk-ontology`, Intent `INTENT.ONT-R06`). Subset ⊆ is subsumption (redundant with `hierarchy`/`isa`); membership ∈ is a distinct collection relation. SKOS/OWL keep these separate. **Fix:** drop "set"; fold subset into `isa`, name membership explicitly. @@ -285,7 +285,7 @@ freshness — these are the epic's job, not the prose contract. 3. **"orthogonal" under-names a known concept.** It's **faceting** (Ranganathan; schema.org multi-domain). Borrow "facet" — the skill's own doctrine is "borrow the established word over inventing one," which it violates here. -4. **Vocabulary drift risk is real and current:** skill+VRS say +4. **Vocabulary drift risk is real and current:** skill+Intent say {hierarchy/composition/orthogonal/set/layers}; #1180 says {isa/partOf/dependsOn/refines/altLabel/avoid}(+related). Two vocabularies for overlapping concepts, already diverging. This survey's core deliverable is to @@ -303,9 +303,9 @@ freshness — these are the epic's job, not the prose contract. Unify the edge names and fix the ambiguous naming lenses now, while deferring typed storage, resolution, and freshness machinery to `#1180`. -## VRS Impact +## Intent Impact -The result is reflected in `VRS.ONT-R06`: the ontology contract uses the shared +The result is reflected in `INTENT.ONT-R06`: the ontology contract uses the shared edge vocabulary, preserves the is-a/part-of distinction, and keeps structure lazy. The survey remains evidence rather than a second normative contract. diff --git a/intent/04-ontology/requirements.md b/intent/04-ontology/requirements.md index a777e7c..feb12be 100644 --- a/intent/04-ontology/requirements.md +++ b/intent/04-ontology/requirements.md @@ -1,9 +1,9 @@ -# VRS Ontology — Requirements +# Intent Ontology — Requirements ## Context -- This child node defines the contract for `ontology.md` files in VRS nodes. -- It refines [VRS-R01](../requirements.md) and [VRS-R02](../requirements.md). +- This child node defines the contract for `ontology.md` files in Intent nodes. +- It refines [INTENT-R01](../requirements.md) and [INTENT-R02](../requirements.md). - The ontology artifact is the language layer (canonical terms) plus an optional structure layer (how the terms relate). A flat term list is the minimal ontology; the language layer alone is that minimal form. The reusable @@ -14,30 +14,30 @@ ### Must Stabilize Language -- **VRS.ONT-R01 Canonical terms:** An ontology must choose one canonical term +- **INTENT.ONT-R01 Canonical terms:** An ontology must choose one canonical term when multiple names compete. -- **VRS.ONT-R02 Tight definitions:** Definitions must describe what a thing is, +- **INTENT.ONT-R02 Tight definitions:** Definitions must describe what a thing is, not how it is implemented. -- **VRS.ONT-R03 Avoid aliases:** Discouraged aliases must be listed when they +- **INTENT.ONT-R03 Avoid aliases:** Discouraged aliases must be listed when they are likely to appear in code, docs, or discussion. ### May Capture Structure -- **VRS.ONT-R06 Lazy structure:** An ontology may record how terms relate — +- **INTENT.ONT-R06 Lazy structure:** An ontology may record how terms relate — the typed edges `isa`, `partOf`, `refines`, `dependsOn`, `related`, plus facets (independent axes) and grouping/layers — and the leitwort convention that carries a family. Structure is added only where a relationship carries weight; the minimal ontology is a flat term list. -- **VRS.ONT-R07 Legible membership:** When a term is a follower of an anchor, +- **INTENT.ONT-R07 Legible membership:** When a term is a follower of an anchor, its name should carry the anchor's leitwort so membership is legible without a lookup. -- **VRS.ONT-R08 Declared inheritance:** A child ontology must name the parent +- **INTENT.ONT-R08 Declared inheritance:** A child ontology must name the parent ontology it inherits and the scope of what it adds. When a node has children that share terms, those shared terms belong in a root ontology at that node. ### Must Avoid Spec Drift -- **VRS.ONT-R04 No decisions:** An ontology must not carry rationale or decision +- **INTENT.ONT-R04 No decisions:** An ontology must not carry rationale or decision history. -- **VRS.ONT-R05 No implementation detail:** An ontology must not become an API, +- **INTENT.ONT-R05 No implementation detail:** An ontology must not become an API, schema, or behavior spec. diff --git a/intent/04-ontology/spec.md b/intent/04-ontology/spec.md index 6075be6..9c18bdd 100644 --- a/intent/04-ontology/spec.md +++ b/intent/04-ontology/spec.md @@ -1,4 +1,4 @@ -# VRS Ontology — Spec +# Intent Ontology — Spec This document specifies `ontology.md` files. It builds on [requirements.md](./requirements.md). @@ -36,5 +36,5 @@ within this file, as a child narrowing a parent term, or as a cross-node homograph (the same word owned by another ontology). Inheritance flows downward, along concept-scheme boundaries: a child ontology -names the parent it inherits (VRS.ONT-R08) and defines only new terms, new +names the parent it inherits (INTENT.ONT-R08) and defines only new terms, new structure, or local ambiguity; it does not restate the parent. diff --git a/intent/05-intuition/requirements.md b/intent/05-intuition/requirements.md index 93fca2b..236fc7f 100644 --- a/intent/05-intuition/requirements.md +++ b/intent/05-intuition/requirements.md @@ -1,24 +1,24 @@ -# VRS Intuition — Requirements +# Intent Intuition — Requirements ## Context -- This child node defines the contract for `intuition.md` files in VRS nodes. -- It refines [VRS-R01](../requirements.md) and [VRS-R05](../requirements.md). +- This child node defines the contract for `intuition.md` files in Intent nodes. +- It refines [INTENT-R01](../requirements.md) and [INTENT-R05](../requirements.md). ## Requirements ### Must Build the Mental Model -- **VRS.INT-R01 Narrative entry point:** `intuition.md` is the VRS node's - narrative entry point and replaces VRS use of `README.md`. -- **VRS.INT-R02 Narrative model:** Intuition must explain the model a reader +- **INTENT.INT-R01 Narrative entry point:** `intuition.md` is the Intent node's + narrative entry point and replaces Intent use of `README.md`. +- **INTENT.INT-R02 Narrative model:** Intuition must explain the model a reader needs before reading formal docs. -- **VRS.INT-R03 System map:** Intuition may include the node's map and reading +- **INTENT.INT-R03 System map:** Intuition may include the node's map and reading order when that helps orientation. ### Must Stay Non-Normative -- **VRS.INT-R04 No hidden constraints:** Normative constraints must live in +- **INTENT.INT-R04 No hidden constraints:** Normative constraints must live in `requirements.md` or `spec.md`, not only in intuition. -- **VRS.INT-R05 No navigation filler:** Intuition must explain the system, not +- **INTENT.INT-R05 No navigation filler:** Intuition must explain the system, not merely list files. diff --git a/intent/05-intuition/spec.md b/intent/05-intuition/spec.md index 5653ed0..ee5ea1f 100644 --- a/intent/05-intuition/spec.md +++ b/intent/05-intuition/spec.md @@ -1,4 +1,4 @@ -# VRS Intuition — Spec +# Intent Intuition — Spec This document specifies `intuition.md` files. It builds on [requirements.md](./requirements.md). diff --git a/intent/06-decisions/requirements.md b/intent/06-decisions/requirements.md index e18be7e..56e5128 100644 --- a/intent/06-decisions/requirements.md +++ b/intent/06-decisions/requirements.md @@ -1,41 +1,41 @@ -# VRS Decisions — Requirements +# Intent Decisions — Requirements ## Context -- This child node defines the contract for VRS decision records. -- It refines [VRS-R07](../requirements.md) and [VRS-R08](../requirements.md). +- This child node defines the contract for Intent decision records. +- It refines [INTENT-R07](../requirements.md) and [INTENT-R08](../requirements.md). ## Requirements ### Must Record Consequential Choices -- **VRS.DEC-R01 Broad scope:** Decision records may cover architecture, +- **INTENT.DEC-R01 Broad scope:** Decision records may cover architecture, product, operational, data, interface, validation, or design choices. -- **VRS.DEC-R02 Admission rule:** A durable decision record must be costly or +- **INTENT.DEC-R02 Admission rule:** A durable decision record must be costly or confusing to reverse, surprising without context, and the result of a real tradeoff. -- **VRS.DEC-R03 No changelog:** Routine implementation changes must not become +- **INTENT.DEC-R03 No changelog:** Routine implementation changes must not become decision records. -- **VRS.DEC-R04 Evidence-backed:** A durable decision must include the best +- **INTENT.DEC-R04 Evidence-backed:** A durable decision must include the best available evidence, proof, argument, research, experiment, implementation fact, or user input backing the chosen approach. -- **VRS.DEC-R05 Principled options:** A durable decision must list the best +- **INTENT.DEC-R05 Principled options:** A durable decision must list the best principled options considered and their tradeoffs. -- **VRS.DEC-R06 Choice rationale:** A durable decision must explain why the - chosen option is best under the VRS context and constraints. -- **VRS.DEC-R07 Multiple evidence forms:** A durable decision must include at +- **INTENT.DEC-R06 Choice rationale:** A durable decision must explain why the + chosen option is best under the Intent context and constraints. +- **INTENT.DEC-R07 Multiple evidence forms:** A durable decision must include at least one applicable evidence form and should include multiple independent evidence forms when the decision is important, risky, or expensive to reverse. -- **VRS.DEC-R08 Compact rationale:** A decision record must summarize the +- **INTENT.DEC-R08 Compact rationale:** A decision record must summarize the decisive evidence and rationale rather than embedding bulky experiment logs, benchmark tables, transcripts, or implementation backlogs. ### Must Preserve Main-Branch Cleanliness -- **VRS.DEC-R09 Durable main:** Main branch may contain accepted, deprecated, +- **INTENT.DEC-R09 Durable main:** Main branch may contain accepted, deprecated, and superseded decision records. -- **VRS.DEC-R10 PR-local proposals:** Proposed records may live under +- **INTENT.DEC-R10 PR-local proposals:** Proposed records may live under `.decisions/.proposed/` during a PR only. -- **VRS.DEC-R11 Proposal exit:** Every proposed record must be accepted, +- **INTENT.DEC-R11 Proposal exit:** Every proposed record must be accepted, folded into another artifact, moved to `open-questions.md`, or deleted before merge. diff --git a/intent/06-decisions/spec.md b/intent/06-decisions/spec.md index e4d0bfe..5d20a51 100644 --- a/intent/06-decisions/spec.md +++ b/intent/06-decisions/spec.md @@ -1,6 +1,6 @@ -# VRS Decisions — Spec +# Intent Decisions — Spec -This document specifies VRS decision records. It builds on +This document specifies Intent decision records. It builds on [requirements.md](./requirements.md). ## Status @@ -43,7 +43,7 @@ independent forms when the decision is important or risky. ## Decision -Chosen option and why it is best under the current VRS context and constraints. +Chosen option and why it is best under the current Intent context and constraints. ``` Statuses are `accepted`, `deprecated`, or `superseded by `. Add diff --git a/intent/07-experiments/requirements.md b/intent/07-experiments/requirements.md index e5f5813..7c33edb 100644 --- a/intent/07-experiments/requirements.md +++ b/intent/07-experiments/requirements.md @@ -1,33 +1,33 @@ -# VRS Experiments — Requirements +# Intent Experiments — Requirements ## Context - This child node defines the contract for `.experiments/` companion directories. The directory name is historical shorthand; records may capture any concrete validation evidence, not only lab-style experiments. -- It refines [VRS-R09](../requirements.md) and [VRS-R10](../requirements.md). +- It refines [INTENT-R09](../requirements.md) and [INTENT-R10](../requirements.md). ## Requirements ### Must Capture Evidence -- **VRS.EXP-R01 Evidence trail:** Experiment records must record validation +- **INTENT.EXP-R01 Evidence trail:** Experiment records must record validation evidence, not plans or unresolved tasks. -- **VRS.EXP-R02 Reproducible method:** An experiment record must state enough method +- **INTENT.EXP-R02 Reproducible method:** An experiment record must state enough method for a reader to understand how the conclusion was reached. -- **VRS.EXP-R03 Clear conclusion:** An experiment record must state what VRS +- **INTENT.EXP-R03 Clear conclusion:** An experiment record must state what Intent artifact should change, if any. -- **VRS.EXP-R04 Assumption validation:** Experiments, benchmarks, prototypes, +- **INTENT.EXP-R04 Assumption validation:** Experiments, benchmarks, prototypes, proofs, research, user confirmations, independent critique, or e2e checks should be used when they are the best feasible way to validate a load-bearing assumption. -- **VRS.EXP-R05 Focused records:** Experiment records should be split by major +- **INTENT.EXP-R05 Focused records:** Experiment records should be split by major question, hypothesis, or validation method when aggregation makes the evidence hard to scan or promote. ### Must Stay Companion-Only -- **VRS.EXP-R06 Lazy directory:** `.experiments/` exists only when it contains +- **INTENT.EXP-R06 Lazy directory:** `.experiments/` exists only when it contains real experiment records. -- **VRS.EXP-R07 Not normative:** Accepted findings must be promoted into +- **INTENT.EXP-R07 Not normative:** Accepted findings must be promoted into requirements, spec, ontology, or decisions. diff --git a/intent/07-experiments/spec.md b/intent/07-experiments/spec.md index dab607f..b8d12f9 100644 --- a/intent/07-experiments/spec.md +++ b/intent/07-experiments/spec.md @@ -1,4 +1,4 @@ -# VRS Experiments — Spec +# Intent Experiments — Spec This document specifies `.experiments/` directories. It builds on [requirements.md](./requirements.md). @@ -27,21 +27,21 @@ Record format: ## Conclusion -## VRS Impact +## Intent Impact ``` Use `.experiments/` for validation evidence records: prototypes, benchmarks, e2e validation, research reports, proofs, user confirmations, independent critique, and failed approaches whose evidence should remain available after -the normative VRS artifacts are updated. +the normative Intent artifacts are updated. Keep records focused on one major question, hypothesis, or validation method. Split a large evidence file when it becomes hard to answer "what was tested, -what happened, and what VRS artifact changed?" without reading unrelated +what happened, and what Intent artifact changed?" without reading unrelated sections. Aggregate only when the evidence is inseparable or the comparison itself is the experiment. -When an experiment validates an assumption, link the assumption ID in `VRS -Impact`. When an assumption cannot yet be validated, leave the gap in +When an experiment validates an assumption, link the assumption ID in +`Intent Impact`. When an assumption cannot yet be validated, leave the gap in `open-questions.md` with the blocker rather than recording a speculative experiment. diff --git a/intent/08-reference/requirements.md b/intent/08-reference/requirements.md index 7e6faac..210a606 100644 --- a/intent/08-reference/requirements.md +++ b/intent/08-reference/requirements.md @@ -1,26 +1,26 @@ -# VRS Reference — Requirements +# Intent Reference — Requirements ## Context - This child node defines the contract for `.reference/` companion directories. -- It refines [VRS-R09](../requirements.md) and [VRS-R10](../requirements.md). +- It refines [INTENT-R09](../requirements.md) and [INTENT-R10](../requirements.md). ## Requirements ### Must Preserve External Context -- **VRS.REF-R01 External source material:** References must capture external +- **INTENT.REF-R01 External source material:** References must capture external APIs, standards, behavior notes, source snapshots, or integration assumptions. -- **VRS.REF-R02 Source identity:** References must identify where the material +- **INTENT.REF-R02 Source identity:** References must identify where the material came from and when it was captured when freshness matters. -- **VRS.REF-R03 Relevance:** References must state which VRS assumption, +- **INTENT.REF-R03 Relevance:** References must state which Intent assumption, requirement, spec clause, or decision they support. -- **VRS.REF-R04 Constraint source:** External constraints in `requirements.md` +- **INTENT.REF-R04 Constraint source:** External constraints in `requirements.md` must cite the reference material that establishes or explains the constraint. ### Must Avoid Becoming Normative -- **VRS.REF-R05 Lazy directory:** `.reference/` exists only when it contains +- **INTENT.REF-R05 Lazy directory:** `.reference/` exists only when it contains real source material. -- **VRS.REF-R06 Promotion required:** VRS truth derived from a reference must be +- **INTENT.REF-R06 Promotion required:** Intent truth derived from a reference must be promoted into a normative artifact. diff --git a/intent/08-reference/spec.md b/intent/08-reference/spec.md index 07516cc..3a97bb2 100644 --- a/intent/08-reference/spec.md +++ b/intent/08-reference/spec.md @@ -1,4 +1,4 @@ -# VRS Reference — Spec +# Intent Reference — Spec This document specifies `.reference/` directories. It builds on [requirements.md](./requirements.md). @@ -24,12 +24,12 @@ Captured: ## Relevant Facts -## VRS Impact +## Intent Impact ``` Use references for third-party API details, standards, external feature specs, or source snapshots. Avoid copying large external documents; capture the facts -the VRS depends on and link to the source. +the Intent depends on and link to the source. When a `requirements.md` constraint depends on external behavior, cite the reference from the constraint: diff --git a/intent/09-delta/DELTA-001-proposal-exit-is-unenforced-and-already-violated.md b/intent/09-delta/DELTA-001-proposal-exit-is-unenforced-and-already-violated.md index 71c0aa6..5e89787 100644 --- a/intent/09-delta/DELTA-001-proposal-exit-is-unenforced-and-already-violated.md +++ b/intent/09-delta/DELTA-001-proposal-exit-is-unenforced-and-already-violated.md @@ -4,8 +4,8 @@ Status: open ## Divergence -`VRS.DEC-R10` confines proposed decision records to `.decisions/.proposed/` -"during a PR only". `VRS.DEC-R11` requires every proposed record to be accepted, +`INTENT.DEC-R10` confines proposed decision records to `.decisions/.proposed/` +"during a PR only". `INTENT.DEC-R11` requires every proposed record to be accepted, folded into another artifact, moved to `open-questions.md`, or deleted **before merge**. [0034](../.decisions/0034-proposal-exit-is-enforced-at-merge-not-relaxed.md) decides those requirements stand and are **enforced at merge**. @@ -27,11 +27,11 @@ The six are not a backlog awaiting ratification; under R11 each is a record that should already have exited. 0034 treats them as evidence of what an unenforced proposed state becomes, and they are the immediate work to clear. -## VRS +## Intent - [0034](../.decisions/0034-proposal-exit-is-enforced-at-merge-not-relaxed.md) — the decision, the rejected durable-state option, and the accepted `rm`-to-green risk. -- `VRS.DEC-R10`, `VRS.DEC-R11` in [06-decisions/requirements.md](../06-decisions/requirements.md). +- `INTENT.DEC-R10`, `INTENT.DEC-R11` in [06-decisions/requirements.md](../06-decisions/requirements.md). - [16-enforcement](../16-enforcement/) — where a check belongs. ## Implementation diff --git a/intent/09-delta/requirements.md b/intent/09-delta/requirements.md index bb9ccf0..bbba87f 100644 --- a/intent/09-delta/requirements.md +++ b/intent/09-delta/requirements.md @@ -1,34 +1,34 @@ -# VRS Delta — Requirements +# Intent Delta — Requirements ## Context - This child node defines the contract for `.delta/` companion directories. -- It refines [VRS-R11](../requirements.md) and [VRS-R13](../requirements.md). +- It refines [INTENT-R11](../requirements.md) and [INTENT-R13](../requirements.md). ## Requirements ### Must Track Drift Explicitly -- **VRS.DELTA-R01 Confirmed divergence:** A delta must describe a confirmed, - currently open divergence between normative VRS and implementation, observed +- **INTENT.DELTA-R01 Confirmed divergence:** A delta must describe a confirmed, + currently open divergence between normative Intent and implementation, observed behavior, or verification evidence. -- **VRS.DELTA-R02 Direction clear:** Each delta must say whether the spec or +- **INTENT.DELTA-R02 Direction clear:** Each delta must say whether the spec or implementation is expected to change. -- **VRS.DELTA-R03 Stable IDs:** Deltas must have stable identifiers so agents +- **INTENT.DELTA-R03 Stable IDs:** Deltas must have stable identifiers so agents can update or close them precisely. ### Must Stay Fresh -- **VRS.DELTA-R04 Drift only:** Delta records are for confirmed contract/reality +- **INTENT.DELTA-R04 Drift only:** Delta records are for confirmed contract/reality divergence, not general tasks or future work. -- **VRS.DELTA-R05 Closure required:** A delta closes by updating the - implementation, updating VRS, or recording an accepted decision that changes +- **INTENT.DELTA-R05 Closure required:** A delta closes by updating the + implementation, updating Intent, or recording an accepted decision that changes the contract. -- **VRS.DELTA-R06 Prune resolved records:** Completed, stale, duplicate, or +- **INTENT.DELTA-R06 Prune resolved records:** Completed, stale, duplicate, or no-longer-true deltas must be removed instead of retained as history. -- **VRS.DELTA-R07 Review on related edits:** Any change to a referenced VRS +- **INTENT.DELTA-R07 Review on related edits:** Any change to a referenced Intent artifact or implementation surface must update or close affected deltas in the same change. -- **VRS.DELTA-R08 Main may contain open deltas:** Open delta files may exist on +- **INTENT.DELTA-R08 Main may contain open deltas:** Open delta files may exist on main when they represent confirmed current drift; closed, stale, speculative, or completed delta files must not. diff --git a/intent/09-delta/spec.md b/intent/09-delta/spec.md index 9d3973e..fd9619d 100644 --- a/intent/09-delta/spec.md +++ b/intent/09-delta/spec.md @@ -1,4 +1,4 @@ -# VRS Delta — Spec +# Intent Delta — Spec This document specifies `.delta/` directories. It builds on [requirements.md](./requirements.md). @@ -20,7 +20,7 @@ delta files in the same PR. Closed deltas are deleted, so IDs can become non-contiguous; do not renumber remaining deltas just to close gaps. Do not create `implementation-delta.md` files. A single visible delta ledger -invites stale completed work and mixed task lists; `.delta/` is the only VRS +invites stale completed work and mixed task lists; `.delta/` is the only Intent delta shape. ## Record Shape @@ -32,32 +32,32 @@ Status: open ## Divergence -## VRS +## Intent ## Implementation ## Direction -update implementation | update VRS | decide +update implementation | update Intent | decide ## Resolution Signal ``` -`Divergence` states the mismatch in one or two sentences. `VRS` links to the +`Divergence` states the mismatch in one or two sentences. `Intent` links to the requirement, spec clause, ontology term, or decision record. `Implementation` links to code, config, observed behavior, or verification output. If no implementation exists yet, this section links to the evidence that proves the -normative VRS is incomplete, contradictory, or false. +normative Intent is incomplete, contradictory, or false. ## Lifecycle -Agents must check affected deltas whenever they edit referenced VRS artifacts or +Agents must check affected deltas whenever they edit referenced Intent artifacts or implementation surfaces. Open deltas may exist on main. They are current-state truth about known drift, not a merge failure by themselves. Close a delta by deleting the file in the same change that resolves the -divergence. If the divergence was intentional, first update the relevant VRS +divergence. If the divergence was intentional, first update the relevant Intent artifact or add a decision record; then delete the delta. Do not keep closed deltas as historical records because Git already preserves history. diff --git a/intent/10-open-questions/requirements.md b/intent/10-open-questions/requirements.md index 9f792bf..d06f1d3 100644 --- a/intent/10-open-questions/requirements.md +++ b/intent/10-open-questions/requirements.md @@ -1,35 +1,35 @@ -# VRS Open Questions — Requirements +# Intent Open Questions — Requirements ## Context - This child node defines the contract for `open-questions.md` files. -- It refines [VRS-R14](../requirements.md). +- It refines [INTENT-R14](../requirements.md). ## Requirements ### Must Track Unresolved Uncertainty -- **VRS.OQ-R01 Genuine uncertainty:** An open question must describe unresolved +- **INTENT.OQ-R01 Genuine uncertainty:** An open question must describe unresolved design uncertainty, not a task, future idea, or confirmed implementation mismatch. -- **VRS.OQ-R02 Resolution path:** Each question must state what kind of evidence +- **INTENT.OQ-R02 Resolution path:** Each question must state what kind of evidence or decision would resolve it. -- **VRS.OQ-R03 Spec link:** When a question blocks a spec detail, the spec must +- **INTENT.OQ-R03 Spec link:** When a question blocks a spec detail, the spec must reference it with a `DQ` identifier. ### Must Stay Fresh -- **VRS.OQ-R04 Prune resolved questions:** Resolved questions must be removed +- **INTENT.OQ-R04 Prune resolved questions:** Resolved questions must be removed from `open-questions.md` in the same change that records the resolution. -- **VRS.OQ-R05 Move to owner:** A resolved answer must move to the owning VRS +- **INTENT.OQ-R05 Move to owner:** A resolved answer must move to the owning Intent artifact when it affects durable system truth. -- **VRS.OQ-R06 Not a roadmap:** Far-future direction belongs in `roadmap.md` +- **INTENT.OQ-R06 Not a roadmap:** Far-future direction belongs in `roadmap.md` unless there is a concrete current design uncertainty to resolve. -- **VRS.OQ-R07 Drafting coverage:** During initial VRS drafting, +- **INTENT.OQ-R07 Drafting coverage:** During initial Intent drafting, `open-questions.md` may hold temporary coverage questions for areas not yet explored. -- **VRS.OQ-R08 Resolution pressure:** Agents must try to resolve every open - question before finalizing VRS work unless the question has a clear blocker. -- **VRS.OQ-R09 Blocker explicit:** A blocked open question must name what +- **INTENT.OQ-R08 Resolution pressure:** Agents must try to resolve every open + question before finalizing Intent work unless the question has a clear blocker. +- **INTENT.OQ-R09 Blocker explicit:** A blocked open question must name what external input, experiment, research, implementation fact, or decision would unblock it. diff --git a/intent/10-open-questions/spec.md b/intent/10-open-questions/spec.md index 786ad07..e0ea644 100644 --- a/intent/10-open-questions/spec.md +++ b/intent/10-open-questions/spec.md @@ -1,4 +1,4 @@ -# VRS Open Questions — Spec +# Intent Open Questions — Spec This document specifies `open-questions.md` files. It builds on [requirements.md](./requirements.md). @@ -13,7 +13,7 @@ Draft. # — Open Questions Only genuinely unresolved design questions. Resolved questions move to their -owning VRS artifact or are deleted. +owning Intent artifact or are deleted. ## DQ1: @@ -31,7 +31,7 @@ Do not keep a resolved-question archive. Git history preserves prior questions. ## Drafting Coverage -During initial VRS drafting, use `open-questions.md` to avoid losing coverage +During initial Intent drafting, use `open-questions.md` to avoid losing coverage areas while the conversation or investigation dives deep into one branch. Coverage questions should be specific enough to act on: @@ -43,7 +43,7 @@ Coverage questions should be specific enough to act on: operational constraint ``` -Before finalizing VRS work, walk every open question. Resolve it into the owning +Before finalizing Intent work, walk every open question. Resolve it into the owning artifact when possible. Leave it open only if it has a clear blocker, and record that blocker in the question. diff --git a/intent/11-roadmap/requirements.md b/intent/11-roadmap/requirements.md index e16d5a8..dfe314a 100644 --- a/intent/11-roadmap/requirements.md +++ b/intent/11-roadmap/requirements.md @@ -1,26 +1,26 @@ -# VRS Roadmap — Requirements +# Intent Roadmap — Requirements ## Context - This child node defines the contract for optional `roadmap.md` files. -- It refines [VRS-R15](../requirements.md). +- It refines [INTENT-R15](../requirements.md). ## Requirements ### Must Preserve Future Direction Without Creating Contract -- **VRS.ROAD-R01 Non-normative:** Roadmap entries must not constrain current +- **INTENT.ROAD-R01 Non-normative:** Roadmap entries must not constrain current implementation. -- **VRS.ROAD-R02 Future direction:** A roadmap entry must describe a plausible +- **INTENT.ROAD-R02 Future direction:** A roadmap entry must describe a plausible later capability, phase, integration, or system direction. -- **VRS.ROAD-R03 Promotion required:** A roadmap entry becomes normative only +- **INTENT.ROAD-R03 Promotion required:** A roadmap entry becomes normative only when promoted into requirements, spec, or a decision record. ### Must Not Hide Current Work -- **VRS.ROAD-R04 Not drift:** Known current contract/reality divergence belongs +- **INTENT.ROAD-R04 Not drift:** Known current contract/reality divergence belongs in `.delta/`. -- **VRS.ROAD-R05 Not uncertainty:** Unresolved design questions belong in +- **INTENT.ROAD-R05 Not uncertainty:** Unresolved design questions belong in `open-questions.md`. -- **VRS.ROAD-R06 Not backlog:** Active implementation tasks belong in the - project planning system, not VRS roadmap. +- **INTENT.ROAD-R06 Not backlog:** Active implementation tasks belong in the + project planning system, not Intent roadmap. diff --git a/intent/11-roadmap/spec.md b/intent/11-roadmap/spec.md index 56c2e3a..812a617 100644 --- a/intent/11-roadmap/spec.md +++ b/intent/11-roadmap/spec.md @@ -1,4 +1,4 @@ -# VRS Roadmap — Spec +# Intent Roadmap — Spec This document specifies optional `roadmap.md` files. It builds on [requirements.md](./requirements.md). @@ -19,9 +19,9 @@ promoted into requirements, spec, or a decision record. - **:** - Trigger: - - Promotion target: requirements | spec | decision | child VRS + - Promotion target: requirements | spec | decision | child Intent ``` Use roadmap for ideas that are concrete enough to preserve but too far out to -belong in the current contract. Review roadmap entries before major VRS updates +belong in the current contract. Review roadmap entries before major Intent updates and delete entries that are no longer relevant. diff --git a/intent/12-common-subsystems/requirements.md b/intent/12-common-subsystems/requirements.md index 31e489d..e81d8c7 100644 --- a/intent/12-common-subsystems/requirements.md +++ b/intent/12-common-subsystems/requirements.md @@ -1,32 +1,32 @@ -# VRS Common Subsystems — Requirements +# Intent Common Subsystems — Requirements ## Context -- This child node defines common VRS subsystem candidates. -- It refines [VRS-R04](../requirements.md) and [VRS-R17](../requirements.md). +- This child node defines common Intent subsystem candidates. +- It refines [INTENT-R04](../requirements.md) and [INTENT-R17](../requirements.md). ## Requirements ### Must Be Subsystems, Not Companion Files -- **VRS.SUB-R01 Child node shape:** A common subsystem must be modeled as a - child VRS node with its own `requirements.md` and `spec.md`. -- **VRS.SUB-R02 No generic data-model file:** Data models must not use a generic - top-level `datamodel.md`; substantial data models become child VRS nodes. -- **VRS.SUB-R03 Lazy creation:** Common subsystem nodes are created only when +- **INTENT.SUB-R01 Child node shape:** A common subsystem must be modeled as a + child Intent node with its own `requirements.md` and `spec.md`. +- **INTENT.SUB-R02 No generic data-model file:** Data models must not use a generic + top-level `datamodel.md`; substantial data models become child Intent nodes. +- **INTENT.SUB-R03 Lazy creation:** Common subsystem nodes are created only when the topic has enough scope to justify independent requirements and spec. ### Must Cover Recurring Design Surfaces -- **VRS.SUB-R04 Interface surfaces:** CLI commands, config files, APIs, UI +- **INTENT.SUB-R04 Interface surfaces:** CLI commands, config files, APIs, UI routes, and other user/system surfaces should get a subsystem when their contract is non-trivial. -- **VRS.SUB-R05 Verification loops:** Test architecture, validation loops, +- **INTENT.SUB-R05 Verification loops:** Test architecture, validation loops, conformance, benchmarks, and e2e checks should get a subsystem when they shape the system. -- **VRS.SUB-R06 Integrations:** External systems should get a subsystem when +- **INTENT.SUB-R06 Integrations:** External systems should get a subsystem when they impose meaningful assumptions, constraints, references, auth, or compatibility boundaries. -- **VRS.SUB-R07 Operations and bounds:** Runtime operation, observability, +- **INTENT.SUB-R07 Operations and bounds:** Runtime operation, observability, rollout, recovery, capacity, disk, memory, CPU, or latency bounds should get a subsystem when they need explicit design. diff --git a/intent/12-common-subsystems/spec.md b/intent/12-common-subsystems/spec.md index 9912b6c..d8ac439 100644 --- a/intent/12-common-subsystems/spec.md +++ b/intent/12-common-subsystems/spec.md @@ -1,6 +1,6 @@ -# VRS Common Subsystems — Spec +# Intent Common Subsystems — Spec -This document specifies common subsystem candidates in VRS trees. It builds on +This document specifies common subsystem candidates in Intent trees. It builds on [requirements.md](./requirements.md). ## Status @@ -12,7 +12,7 @@ Draft. Common subsystem nodes use normal numeric child-node naming: ```text -/ +/ 01-data-model/ requirements.md spec.md diff --git a/intent/13-review-smells/requirements.md b/intent/13-review-smells/requirements.md index f701228..16fdbf8 100644 --- a/intent/13-review-smells/requirements.md +++ b/intent/13-review-smells/requirements.md @@ -1,26 +1,26 @@ -# VRS Review Smells — Requirements +# Intent Review Smells — Requirements ## Context - This child node defines bad patterns agents must check when creating or - editing VRS. -- It refines [VRS-R18](../requirements.md). + editing Intent. +- It refines [INTENT-R18](../requirements.md). ## Requirements ### Must Guide Review -- **VRS.SMELL-R01 Normative checks:** Review smells must be treated as VRS +- **INTENT.SMELL-R01 Normative checks:** Review smells must be treated as Intent review rules, not optional style preferences. -- **VRS.SMELL-R02 Fix ownership:** When a smell appears, the fix must move the - content to the correct VRS owner or delete it. -- **VRS.SMELL-R03 No smell artifact:** Individual VRS topics must not create a - recurring `smells.md` artifact; smell checks live in the meta-VRS contract. +- **INTENT.SMELL-R02 Fix ownership:** When a smell appears, the fix must move the + content to the correct Intent owner or delete it. +- **INTENT.SMELL-R03 No smell artifact:** Individual Intent topics must not create a + recurring `smells.md` artifact; smell checks live in the root Intent contract. ### Must Catch Common Drift -- **VRS.SMELL-R04 Lifecycle freshness:** Stale open questions, roadmap items, +- **INTENT.SMELL-R04 Lifecycle freshness:** Stale open questions, roadmap items, deltas, proposed decisions, experiments, and references must be updated, promoted, pruned, or deleted. -- **VRS.SMELL-R05 Artifact boundary:** Content in the wrong VRS artifact must be +- **INTENT.SMELL-R05 Artifact boundary:** Content in the wrong Intent artifact must be moved rather than duplicated. diff --git a/intent/13-review-smells/spec.md b/intent/13-review-smells/spec.md index 0b30a1f..688d64a 100644 --- a/intent/13-review-smells/spec.md +++ b/intent/13-review-smells/spec.md @@ -1,6 +1,6 @@ -# VRS Review Smells — Spec +# Intent Review Smells — Spec -This document specifies VRS review smells. It builds on +This document specifies Intent review smells. It builds on [requirements.md](./requirements.md). ## Status @@ -21,13 +21,13 @@ Draft. | `roadmap.md` reads like current contract. | Promote it to requirements/spec/decision or weaken it to non-normative future direction. | | `.delta/` contains stale, vague, speculative, duplicate, or completed entries. | Update or delete the delta. | | `.decisions/.proposed/` would merge to main. | Accept, fold, defer to open questions, or delete proposed records before merge. | -| A decision embeds raw experiment logs, benchmark tables, transcripts, or follow-up backlog. | Summarize the decisive evidence and link to `.experiments/`, `.reference/`, code, planning, or the owning VRS artifact. | +| A decision embeds raw experiment logs, benchmark tables, transcripts, or follow-up backlog. | Summarize the decisive evidence and link to `.experiments/`, `.reference/`, code, planning, or the owning Intent artifact. | | `.experiments/` contains plans instead of evidence. | Move plans to the planning system; keep only evidence records. | | `.experiments/` aggregates unrelated questions until the conclusion is hard to promote. | Split by major question, hypothesis, or validation method. | -| `.reference/` contains copied external docs without VRS impact. | Summarize relevant facts and link to the source. | +| `.reference/` contains copied external docs without Intent impact. | Summarize relevant facts and link to the source. | | Empty companion directories exist to satisfy a template. | Delete them until real content exists. | -| A generic `README.md` is used as VRS entry point. | Use `intuition.md`; keep README for repository onboarding only. | -| Requirements exceed 30 items or approach 40. | Split into child VRS nodes. | +| A generic `README.md` is used as Intent entry point. | Use `intuition.md`; keep README for repository onboarding only. | +| Requirements exceed 30 items or approach 40. | Split into child Intent nodes. | -Agents should run this catalog before finalizing VRS edits and fix any smell in +Agents should run this catalog before finalizing Intent edits and fix any smell in the same change when the correct owner is clear. diff --git a/intent/14-grill-intent/requirements.md b/intent/14-grill-intent/requirements.md new file mode 100644 index 0000000..d9a1635 --- /dev/null +++ b/intent/14-grill-intent/requirements.md @@ -0,0 +1,37 @@ +# Intent Grill Intent — Requirements + +## Context + +- This child node defines how the Intent contract composes with the `grill-intent` + interview skill. +- It refines [INTENT-R12](../requirements.md) and [INTENT-R23](../requirements.md). + +## Requirements + +### Must Apply Intent, Not Redefine It + +- **INTENT.GRILL-R01 Intent contract source:** `intent/` is the source of truth + for artifact structure, lifecycle, and review rules. +- **INTENT.GRILL-R02 Procedural skill:** `grill-intent` owns the interview procedure: + questioning, pressure-testing, validation, and inline Intent updates. +- **INTENT.GRILL-R03 Thin skill:** The operational skill must avoid duplicating + detailed artifact rules that already live in the root Intent contract. + +### Must Preserve Interview Discipline + +- **INTENT.GRILL-R04 One question:** The procedure asks one question at a time and + waits for feedback. +- **INTENT.GRILL-R05 Recommended answer:** Each question includes the agent's + recommended answer and tradeoff framing. +- **INTENT.GRILL-R06 Explore before asking:** If code, Intent, references, or tooling + can answer a question, the agent investigates before asking the user. +- **INTENT.GRILL-R07 Update as understanding crystallizes:** Resolved terms, + requirements, constraints, decisions, experiments, references, deltas, and + open questions are captured in the correct Intent artifact as they become clear. +- **INTENT.GRILL-R08 Ontology handling:** The procedure resolves fuzzy, + conflicting, or overloaded terms and updates `ontology.md` using the + root Intent ontology contract. + +### Must Use the Preferred Name + +- **INTENT.GRILL-R09 Skill name:** The skill name is `grill-intent`. diff --git a/intent/14-grill-vrs/spec.md b/intent/14-grill-intent/spec.md similarity index 61% rename from intent/14-grill-vrs/spec.md rename to intent/14-grill-intent/spec.md index 8eb9f0e..af0d27d 100644 --- a/intent/14-grill-vrs/spec.md +++ b/intent/14-grill-intent/spec.md @@ -1,6 +1,6 @@ -# VRS Grill VRS — Spec +# Intent Grill Intent — Spec -This document specifies the `grill-vrs` procedure. It builds on +This document specifies the `grill-intent` procedure. It builds on [requirements.md](./requirements.md). ## Status @@ -10,23 +10,23 @@ Draft. ## Relationship ```text -context/vrs/ normative intent-layer contract -grill-vrs procedure that interrogates and updates the contract +intent/ normative intent-layer contract +grill-intent procedure that interrogates and updates the contract ``` -VRS defines which artifact owns each fact. `grill-vrs` defines how an agent +Intent defines which artifact owns each fact. `grill-intent` defines how an agent arrives at those facts with a human or through code/research investigation. ## Procedure -1. Read the relevant VRS node and the meta-VRS contract. +1. Read the relevant Intent node and the root Intent contract. 2. Investigate code, references, experiments, and existing decisions before asking questions that local context can answer. 3. Ask one question at a time. 4. Include the recommended answer, options, tradeoffs, and evidence gaps. 5. Validate load-bearing assumptions with the best feasible evidence. 6. Resolve fuzzy, conflicting, or overloaded terms into `ontology.md`. -7. Update the owning VRS artifact as soon as understanding crystallizes. +7. Update the owning Intent artifact as soon as understanding crystallizes. 8. Walk remaining open questions before finalizing; leave only blocked questions with explicit blockers. 9. Run the review-smell catalog before closing the session. @@ -34,6 +34,6 @@ arrives at those facts with a human or through code/research investigation. ## Skill Reduction When the operational skill is updated, it should keep procedural rules and link -to `context/vrs/` for artifact details. The skill should not carry independent +to `intent/` for artifact details. The skill should not carry independent templates for decisions, ontology, requirements, experiments, deltas, or roadmap -when the meta-VRS already defines them. +when the root Intent contract already defines them. diff --git a/intent/14-grill-vrs/requirements.md b/intent/14-grill-vrs/requirements.md deleted file mode 100644 index c701b0d..0000000 --- a/intent/14-grill-vrs/requirements.md +++ /dev/null @@ -1,37 +0,0 @@ -# VRS Grill VRS — Requirements - -## Context - -- This child node defines how the VRS contract composes with the `grill-vrs` - interview skill. -- It refines [VRS-R12](../requirements.md) and [VRS-R23](../requirements.md). - -## Requirements - -### Must Apply VRS, Not Redefine It - -- **VRS.GRILL-R01 VRS contract source:** `context/vrs/` is the source of truth - for artifact structure, lifecycle, and review rules. -- **VRS.GRILL-R02 Procedural skill:** `grill-vrs` owns the interview procedure: - questioning, pressure-testing, validation, and inline VRS updates. -- **VRS.GRILL-R03 Thin skill:** The operational skill must avoid duplicating - detailed artifact rules that already live in the meta-VRS. - -### Must Preserve Interview Discipline - -- **VRS.GRILL-R04 One question:** The procedure asks one question at a time and - waits for feedback. -- **VRS.GRILL-R05 Recommended answer:** Each question includes the agent's - recommended answer and tradeoff framing. -- **VRS.GRILL-R06 Explore before asking:** If code, VRS, references, or tooling - can answer a question, the agent investigates before asking the user. -- **VRS.GRILL-R07 Update as understanding crystallizes:** Resolved terms, - requirements, constraints, decisions, experiments, references, deltas, and - open questions are captured in the correct VRS artifact as they become clear. -- **VRS.GRILL-R08 Ontology handling:** The procedure resolves fuzzy, - conflicting, or overloaded terms and updates `ontology.md` using the - meta-VRS ontology contract. - -### Must Use the Preferred Name - -- **VRS.GRILL-R09 Skill name:** The skill name is `grill-vrs`. diff --git a/intent/15-evaluation/requirements.md b/intent/15-evaluation/requirements.md index 91cb738..36ae583 100644 --- a/intent/15-evaluation/requirements.md +++ b/intent/15-evaluation/requirements.md @@ -1,38 +1,38 @@ -# VRS Evaluation — Requirements +# Intent Evaluation — Requirements ## Context -- This child node defines how to evaluate the VRS system and VRS skills. -- It refines [VRS-R25](../requirements.md). +- This child node defines how to evaluate the Intent system and Intent skills. +- It refines [INTENT-R25](../requirements.md). ## Requirements ### Must Evaluate End To End -- **VRS.EVAL-R01 Isolated scenario:** An eval must run in an isolated temporary +- **INTENT.EVAL-R01 Isolated scenario:** An eval must run in an isolated temporary project or scenario outside tracked project files. -- **VRS.EVAL-R02 Realistic surface area:** The scenario must exercise multiple - VRS artifact kinds, including requirements, spec, ontology, decisions, and at +- **INTENT.EVAL-R02 Realistic surface area:** The scenario must exercise multiple + Intent artifact kinds, including requirements, spec, ontology, decisions, and at least one companion artifact. -- **VRS.EVAL-R03 Skill application:** The eval must apply the relevant skill - procedure, especially `grill-vrs` for unclear or consequential design. +- **INTENT.EVAL-R03 Skill application:** The eval must apply the relevant skill + procedure, especially `grill-intent` for unclear or consequential design. ### Must Produce Evidence -- **VRS.EVAL-R04 Artifact evidence:** The eval must preserve or report the temp +- **INTENT.EVAL-R04 Artifact evidence:** The eval must preserve or report the temp artifact paths so findings can be inspected. -- **VRS.EVAL-R05 Gap classification:** Findings must classify gaps by owning - VRS artifact: requirement, spec, ontology, decision, open question, delta, +- **INTENT.EVAL-R05 Gap classification:** Findings must classify gaps by owning + Intent artifact: requirement, spec, ontology, decision, open question, delta, experiment, reference, roadmap, review smell, enforcement, or skill update. -- **VRS.EVAL-R06 No tracked edits by eval worker:** The eval worker must not +- **INTENT.EVAL-R06 No tracked edits by eval worker:** The eval worker must not modify tracked repo files; durable findings are applied by the owner agent after review. ### Must Support Iteration -- **VRS.EVAL-R07 Recommendation shape:** Each recommendation must include the - evidence, options or alternatives when relevant, tradeoffs, and suggested VRS +- **INTENT.EVAL-R07 Recommendation shape:** Each recommendation must include the + evidence, options or alternatives when relevant, tradeoffs, and suggested Intent destination. -- **VRS.EVAL-R08 Milestone evidence:** Significant VRS skill or contract changes +- **INTENT.EVAL-R08 Milestone evidence:** Significant Intent skill or contract changes should be followed by at least one isolated scenario eval before being treated as stable. diff --git a/intent/15-evaluation/semantic-review/fixture-format.md b/intent/15-evaluation/semantic-review/fixture-format.md index 80274dd..7c03a88 100644 --- a/intent/15-evaluation/semantic-review/fixture-format.md +++ b/intent/15-evaluation/semantic-review/fixture-format.md @@ -1,6 +1,6 @@ # Semantic Review Fixture Format -Semantic-review fixtures tune `axe vrs review` and the baked prompt/schema +Semantic-review fixtures tune `intent review` and the baked prompt/schema owned by [16-enforcement](../../16-enforcement/spec.md). ## Fixture Directory @@ -8,7 +8,7 @@ owned by [16-enforcement](../../16-enforcement/spec.md). Each fixture should live in a stable, descriptive directory: ```text -context/vrs/15-evaluation/semantic-review// +intent/15-evaluation/semantic-review// fixture.json input/ context// @@ -16,7 +16,7 @@ context/vrs/15-evaluation/semantic-review// spec.md ... diagnostics/ # optional - axe-vrs-check.json + intent-check.json expected-review.json assertions.json # optional notes.md @@ -26,10 +26,10 @@ context/vrs/15-evaluation/semantic-review// ```json { - "schema_version": "vrs.semantic-review.fixture.v1", + "schema_version": "intent.semantic-review.fixture.v1", "id": "requirements-mechanism", "purpose": "Detect implementation mechanism in requirements.", - "covers": ["VRS.REVIEW.requirements.mechanism"], + "covers": ["INTENT.REVIEW.requirements.mechanism"], "prompt_ref": "../../../16-enforcement/review-prompt.md", "schema_ref": "../../../16-enforcement/review-result.schema.json", "assertion_mode": "full | minimum", @@ -37,24 +37,24 @@ context/vrs/15-evaluation/semantic-review// } ``` -`input/` contains the tracked VRS artifacts copied into a temporary eval +`input/` contains the tracked Intent artifacts copied into a temporary eval workspace. Expected finding artifact paths should be fixture-relative, not absolute paths and not paths from a specific temporary run. -`diagnostics/axe-vrs-check.json` is optional until the deterministic checker +`diagnostics/intent-check.json` is optional until the deterministic checker output is relevant to the fixture; when present it must use a generated artifact marker such as `schema_version` or `producer`. -`expected-review.json` contains a complete schema-valid `axe.vrs.review.v1` +`expected-review.json` contains a complete schema-valid `axe.intent.review.v1` result. Real-provider semantic evals should usually use `assertion_mode: "minimum"` and assert only stable finding identity in `assertions.json`: ```json { - "schema_version": "vrs.semantic-review.assertions.v1", + "schema_version": "intent.semantic-review.assertions.v1", "minimum_findings": [ { - "rule": "VRS.REVIEW.requirements.mechanism", + "rule": "INTENT.REVIEW.requirements.mechanism", "severity": "warning", "artifact": "input/context/requirements-mechanism/requirements.md", "owner": "requirements.md" @@ -80,7 +80,7 @@ protects. - Copy fixtures to an isolated temporary workspace before running the eval. - Do not let fixture cases define new review rules; rule semantics belong in the review-smell catalog, file-kind contracts, and enforcement prompt/schema. -- If a fixture proves a VRS contract gap, update the owning VRS artifact and +- If a fixture proves an Intent contract gap, update the owning Intent artifact and preserve the fixture only when it continues to protect behavior. -- Use Axe VRS `.experiments/` for command plumbing evidence; use these fixtures +- Use Intent CLI `.experiments/` for command plumbing evidence; use these fixtures for review quality. diff --git a/intent/15-evaluation/semantic-review/requirements-mechanism/assertions.json b/intent/15-evaluation/semantic-review/requirements-mechanism/assertions.json index 38d2729..8edb461 100644 --- a/intent/15-evaluation/semantic-review/requirements-mechanism/assertions.json +++ b/intent/15-evaluation/semantic-review/requirements-mechanism/assertions.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.assertions.v1", + "schema_version": "intent.semantic-review.assertions.v1", "minimum_findings": [ { - "rule": "VRS.REVIEW.requirements.mechanism", + "rule": "INTENT.REVIEW.requirements.mechanism", "severity": "warning", "artifact": "input/context/requirements-mechanism/requirements.md", "owner": "requirements.md" diff --git a/intent/15-evaluation/semantic-review/requirements-mechanism/expected-review.json b/intent/15-evaluation/semantic-review/requirements-mechanism/expected-review.json index e59f43b..a93de6e 100644 --- a/intent/15-evaluation/semantic-review/requirements-mechanism/expected-review.json +++ b/intent/15-evaluation/semantic-review/requirements-mechanism/expected-review.json @@ -1,14 +1,14 @@ { - "schema_version": "axe.vrs.review.v1", + "schema_version": "axe.intent.review.v1", "summary": "1 semantic concern found.", "findings": [ { - "rule": "VRS.REVIEW.requirements.mechanism", + "rule": "INTENT.REVIEW.requirements.mechanism", "severity": "warning", "gate": "review", "artifact": "input/context/requirements-mechanism/requirements.md", "owner": "requirements.md", - "evidence": "REQ-R01 requires SQLite tables named `vrs_nodes` and `vrs_edges`.", + "evidence": "REQ-R01 requires SQLite tables named `intent_nodes` and `intent_edges`.", "suggested_fix": "Move storage design to spec or a decision record; keep the requirement focused on observable caching behavior." } ] diff --git a/intent/15-evaluation/semantic-review/requirements-mechanism/fixture.json b/intent/15-evaluation/semantic-review/requirements-mechanism/fixture.json index 434990a..0f2755d 100644 --- a/intent/15-evaluation/semantic-review/requirements-mechanism/fixture.json +++ b/intent/15-evaluation/semantic-review/requirements-mechanism/fixture.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.fixture.v1", + "schema_version": "intent.semantic-review.fixture.v1", "id": "requirements-mechanism", "purpose": "Detect implementation mechanism in requirements.", - "covers": ["VRS.REVIEW.requirements.mechanism"], + "covers": ["INTENT.REVIEW.requirements.mechanism"], "prompt_ref": "../../../16-enforcement/review-prompt.md", "schema_ref": "../../../16-enforcement/review-result.schema.json", "assertion_mode": "minimum", diff --git a/intent/15-evaluation/semantic-review/requirements-mechanism/input/context/requirements-mechanism/requirements.md b/intent/15-evaluation/semantic-review/requirements-mechanism/input/context/requirements-mechanism/requirements.md index 83e2464..985eff5 100644 --- a/intent/15-evaluation/semantic-review/requirements-mechanism/input/context/requirements-mechanism/requirements.md +++ b/intent/15-evaluation/semantic-review/requirements-mechanism/input/context/requirements-mechanism/requirements.md @@ -7,4 +7,4 @@ The project records user-visible intent for an agent-operated tool. ## Requirements - **REQ-R01 Cache implementation:** The system must use SQLite tables named - `vrs_nodes` and `vrs_edges` to cache every parsed Markdown artifact. + `intent_nodes` and `intent_edges` to cache every parsed Markdown artifact. diff --git a/intent/15-evaluation/semantic-review/spec-rationale/assertions.json b/intent/15-evaluation/semantic-review/spec-rationale/assertions.json index aeb2dea..35106f4 100644 --- a/intent/15-evaluation/semantic-review/spec-rationale/assertions.json +++ b/intent/15-evaluation/semantic-review/spec-rationale/assertions.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.assertions.v1", + "schema_version": "intent.semantic-review.assertions.v1", "minimum_findings": [ { - "rule": "VRS.REVIEW.spec.rationale", + "rule": "INTENT.REVIEW.spec.rationale", "severity": "warning", "artifact": "input/context/spec-rationale/spec.md", "owner": "spec.md" diff --git a/intent/15-evaluation/semantic-review/spec-rationale/expected-review.json b/intent/15-evaluation/semantic-review/spec-rationale/expected-review.json index a39b3dc..e6d5cc9 100644 --- a/intent/15-evaluation/semantic-review/spec-rationale/expected-review.json +++ b/intent/15-evaluation/semantic-review/spec-rationale/expected-review.json @@ -1,9 +1,9 @@ { - "schema_version": "axe.vrs.review.v1", + "schema_version": "axe.intent.review.v1", "summary": "1 semantic concern found.", "findings": [ { - "rule": "VRS.REVIEW.spec.rationale", + "rule": "INTENT.REVIEW.spec.rationale", "severity": "warning", "gate": "review", "artifact": "input/context/spec-rationale/spec.md", diff --git a/intent/15-evaluation/semantic-review/spec-rationale/fixture.json b/intent/15-evaluation/semantic-review/spec-rationale/fixture.json index 62ecdf3..d5b119c 100644 --- a/intent/15-evaluation/semantic-review/spec-rationale/fixture.json +++ b/intent/15-evaluation/semantic-review/spec-rationale/fixture.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.fixture.v1", + "schema_version": "intent.semantic-review.fixture.v1", "id": "spec-rationale", "purpose": "Detect decision rationale embedded in spec.", - "covers": ["VRS.REVIEW.spec.rationale"], + "covers": ["INTENT.REVIEW.spec.rationale"], "prompt_ref": "../../../16-enforcement/review-prompt.md", "schema_ref": "../../../16-enforcement/review-result.schema.json", "assertion_mode": "minimum", diff --git a/intent/15-evaluation/semantic-review/stale-delta/assertions.json b/intent/15-evaluation/semantic-review/stale-delta/assertions.json index eba05cc..442574c 100644 --- a/intent/15-evaluation/semantic-review/stale-delta/assertions.json +++ b/intent/15-evaluation/semantic-review/stale-delta/assertions.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.assertions.v1", + "schema_version": "intent.semantic-review.assertions.v1", "minimum_findings": [ { - "rule": "VRS.REVIEW.delta.stale", + "rule": "INTENT.REVIEW.delta.stale", "severity": "warning", "artifact": "input/context/stale-delta/.delta/DELTA-001-review-command-missing.md", "owner": ".delta/" diff --git a/intent/15-evaluation/semantic-review/stale-delta/expected-review.json b/intent/15-evaluation/semantic-review/stale-delta/expected-review.json index d56b5a5..ab9c3e3 100644 --- a/intent/15-evaluation/semantic-review/stale-delta/expected-review.json +++ b/intent/15-evaluation/semantic-review/stale-delta/expected-review.json @@ -1,9 +1,9 @@ { - "schema_version": "axe.vrs.review.v1", + "schema_version": "axe.intent.review.v1", "summary": "1 semantic concern found.", "findings": [ { - "rule": "VRS.REVIEW.delta.stale", + "rule": "INTENT.REVIEW.delta.stale", "severity": "warning", "gate": "review", "artifact": "input/context/stale-delta/.delta/DELTA-001-review-command-missing.md", diff --git a/intent/15-evaluation/semantic-review/stale-delta/fixture.json b/intent/15-evaluation/semantic-review/stale-delta/fixture.json index b2ca7b2..7f27177 100644 --- a/intent/15-evaluation/semantic-review/stale-delta/fixture.json +++ b/intent/15-evaluation/semantic-review/stale-delta/fixture.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.fixture.v1", + "schema_version": "intent.semantic-review.fixture.v1", "id": "stale-delta", "purpose": "Detect completed work left in delta.", - "covers": ["VRS.REVIEW.delta.stale"], + "covers": ["INTENT.REVIEW.delta.stale"], "prompt_ref": "../../../16-enforcement/review-prompt.md", "schema_ref": "../../../16-enforcement/review-result.schema.json", "assertion_mode": "minimum", diff --git a/intent/15-evaluation/semantic-review/stale-delta/input/context/stale-delta/.delta/DELTA-001-review-command-missing.md b/intent/15-evaluation/semantic-review/stale-delta/input/context/stale-delta/.delta/DELTA-001-review-command-missing.md index af096d0..1f6eeb1 100644 --- a/intent/15-evaluation/semantic-review/stale-delta/input/context/stale-delta/.delta/DELTA-001-review-command-missing.md +++ b/intent/15-evaluation/semantic-review/stale-delta/input/context/stale-delta/.delta/DELTA-001-review-command-missing.md @@ -4,13 +4,13 @@ Status: open ## Divergence -The VRS says `axe vrs review` should exist, but the implementation does not +The Intent says `intent review` should exist, but the implementation does not provide it yet. ## Current Evidence -Completed in commit `abc1234`: `axe vrs review` now runs through the Coding -Agent Invocation Contract and emits `axe.vrs.review.v1`. +Completed in commit `abc1234`: `intent review` now runs through the Coding +Agent Invocation Contract and emits `axe.intent.review.v1`. ## Required Update diff --git a/intent/15-evaluation/semantic-review/stale-delta/notes.md b/intent/15-evaluation/semantic-review/stale-delta/notes.md index 6dbc10e..5469667 100644 --- a/intent/15-evaluation/semantic-review/stale-delta/notes.md +++ b/intent/15-evaluation/semantic-review/stale-delta/notes.md @@ -1,5 +1,5 @@ # Stale Delta Fixture This fixture protects the rule that `.delta/` contains only current, actionable -divergence between VRS intent and implementation or observed behavior. Completed +divergence between Intent and implementation or observed behavior. Completed work should be pruned rather than retained as a reminder. diff --git a/intent/15-evaluation/semantic-review/stale-open-question/assertions.json b/intent/15-evaluation/semantic-review/stale-open-question/assertions.json index 5187ebb..2332fec 100644 --- a/intent/15-evaluation/semantic-review/stale-open-question/assertions.json +++ b/intent/15-evaluation/semantic-review/stale-open-question/assertions.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.assertions.v1", + "schema_version": "intent.semantic-review.assertions.v1", "minimum_findings": [ { - "rule": "VRS.REVIEW.open-questions.stale", + "rule": "INTENT.REVIEW.open-questions.stale", "severity": "warning", "artifact": "input/context/stale-open-question/open-questions.md", "owner": "open-questions.md" diff --git a/intent/15-evaluation/semantic-review/stale-open-question/expected-review.json b/intent/15-evaluation/semantic-review/stale-open-question/expected-review.json index 3a356c8..e57a01d 100644 --- a/intent/15-evaluation/semantic-review/stale-open-question/expected-review.json +++ b/intent/15-evaluation/semantic-review/stale-open-question/expected-review.json @@ -1,9 +1,9 @@ { - "schema_version": "axe.vrs.review.v1", + "schema_version": "axe.intent.review.v1", "summary": "1 semantic concern found.", "findings": [ { - "rule": "VRS.REVIEW.open-questions.stale", + "rule": "INTENT.REVIEW.open-questions.stale", "severity": "warning", "gate": "review", "artifact": "input/context/stale-open-question/open-questions.md", diff --git a/intent/15-evaluation/semantic-review/stale-open-question/fixture.json b/intent/15-evaluation/semantic-review/stale-open-question/fixture.json index c33e2cf..d948fe0 100644 --- a/intent/15-evaluation/semantic-review/stale-open-question/fixture.json +++ b/intent/15-evaluation/semantic-review/stale-open-question/fixture.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.fixture.v1", + "schema_version": "intent.semantic-review.fixture.v1", "id": "stale-open-question", "purpose": "Detect resolved content left in open questions.", - "covers": ["VRS.REVIEW.open-questions.stale"], + "covers": ["INTENT.REVIEW.open-questions.stale"], "prompt_ref": "../../../16-enforcement/review-prompt.md", "schema_ref": "../../../16-enforcement/review-result.schema.json", "assertion_mode": "minimum", diff --git a/intent/15-evaluation/semantic-review/vision-mechanism/assertions.json b/intent/15-evaluation/semantic-review/vision-mechanism/assertions.json index dd739df..c7f8dbe 100644 --- a/intent/15-evaluation/semantic-review/vision-mechanism/assertions.json +++ b/intent/15-evaluation/semantic-review/vision-mechanism/assertions.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.assertions.v1", + "schema_version": "intent.semantic-review.assertions.v1", "minimum_findings": [ { - "rule": "VRS.REVIEW.vision.mechanism", + "rule": "INTENT.REVIEW.vision.mechanism", "severity": "warning", "artifact": "input/context/vision-mechanism/vision.md", "owner": "vision.md" diff --git a/intent/15-evaluation/semantic-review/vision-mechanism/expected-review.json b/intent/15-evaluation/semantic-review/vision-mechanism/expected-review.json index ec92ba2..7b509e2 100644 --- a/intent/15-evaluation/semantic-review/vision-mechanism/expected-review.json +++ b/intent/15-evaluation/semantic-review/vision-mechanism/expected-review.json @@ -1,9 +1,9 @@ { - "schema_version": "axe.vrs.review.v1", + "schema_version": "axe.intent.review.v1", "summary": "1 semantic concern found.", "findings": [ { - "rule": "VRS.REVIEW.vision.mechanism", + "rule": "INTENT.REVIEW.vision.mechanism", "severity": "warning", "gate": "review", "artifact": "input/context/vision-mechanism/vision.md", diff --git a/intent/15-evaluation/semantic-review/vision-mechanism/fixture.json b/intent/15-evaluation/semantic-review/vision-mechanism/fixture.json index d64790f..42ad0c9 100644 --- a/intent/15-evaluation/semantic-review/vision-mechanism/fixture.json +++ b/intent/15-evaluation/semantic-review/vision-mechanism/fixture.json @@ -1,8 +1,8 @@ { - "schema_version": "vrs.semantic-review.fixture.v1", + "schema_version": "intent.semantic-review.fixture.v1", "id": "vision-mechanism", "purpose": "Detect implementation mechanism in vision.", - "covers": ["VRS.REVIEW.vision.mechanism"], + "covers": ["INTENT.REVIEW.vision.mechanism"], "prompt_ref": "../../../16-enforcement/review-prompt.md", "schema_ref": "../../../16-enforcement/review-result.schema.json", "assertion_mode": "minimum", diff --git a/intent/15-evaluation/spec.md b/intent/15-evaluation/spec.md index 791da3e..bc97a0e 100644 --- a/intent/15-evaluation/spec.md +++ b/intent/15-evaluation/spec.md @@ -1,6 +1,6 @@ -# VRS Evaluation — Spec +# Intent Evaluation — Spec -This document specifies isolated evaluation runs for VRS and VRS skills. It +This document specifies isolated evaluation runs for Intent and Intent skills. It builds on [requirements.md](./requirements.md). ## Status @@ -13,7 +13,7 @@ An eval scenario should be small enough to run quickly but rich enough to force artifact routing decisions: ```text -/tmp/vrs-eval-/ +/tmp/intent-eval-/ context// vision.md requirements.md @@ -39,10 +39,10 @@ The scenario should include at least: ## Eval Procedure -1. Read `context/vrs/` and `nixpkgs/ai/skills/grill-vrs.md`. +1. Read `intent/` and `nixpkgs/ai/skills/grill-intent.md`. 2. Create the scenario in a temporary directory outside tracked repo files. -3. Apply the `grill-vrs` procedure as if shaping the scenario with a user. -4. Produce the miniature VRS tree. +3. Apply the `grill-intent` procedure as if shaping the scenario with a user. +4. Produce the miniature Intent tree. 5. Review the tree with the review-smell catalog. 6. Report evidence-backed findings and classify each gap by owning artifact. @@ -55,20 +55,20 @@ baked review prompt and result schema owned by Tracked fixtures are canonical inputs and expected outcomes, not eval run output. A semantic-review eval copies or materializes a fixture into an -isolated temporary scenario before invoking `axe vrs review` through the Coding +isolated temporary scenario before invoking `intent review` through the Coding Agent Invocation Contract. This preserves the isolated-eval requirement while -keeping prompt-quality examples reviewable in the VRS tree. +keeping prompt-quality examples reviewable in the Intent tree. Use semantic-review fixtures for: -- known-good VRS examples that should produce no findings; +- known-good Intent examples that should produce no findings; - known-bad examples for review-smell coverage; - edge cases where deterministic diagnostics should not be repeated as semantic findings; - cases that protect against prompt drift, schema drift, or overconfident findings when supplied context is insufficient. -Use `context/coding-agents/14-axe/12-vrs/.experiments/` for command-integration +Use `context/coding-agents/14-axe/12-intent/.experiments/` for command-integration prototypes that validate Axe or CAIC wiring rather than semantic-review quality. Fixture shape is validated before real semantic review runs. The first validator @@ -95,7 +95,7 @@ when they detect known automated environments. ## Report Shape ```markdown -# VRS Eval Report +# Intent Eval Report Scenario: Artifacts: @@ -107,12 +107,12 @@ Artifacts: | Finding | Evidence | Owner | Recommendation | | --- | --- | --- | --- | -## Suggested VRS Updates +## Suggested Intent Updates ``` -Temporary eval artifacts are evidence, not normative VRS. Durable changes are -applied to the real VRS tree only after review. +Temporary eval artifacts are evidence, not normative Intent. Durable changes are +applied to the real Intent tree only after review. -When an eval creates a valid example and exposes a meta-VRS gap, preserve both: +When an eval creates a valid example and exposes a root Intent contract gap, preserve both: the example demonstrates what worked, while the report classifies the gap by -owning artifact and proposes the minimal durable VRS update. +owning artifact and proposes the minimal durable Intent update. diff --git a/intent/16-enforcement/.experiments/2026-06-19-real-provider-review-eval.md b/intent/16-enforcement/.experiments/2026-06-19-real-provider-review-eval.md index 02ef1b4..a2e085f 100644 --- a/intent/16-enforcement/.experiments/2026-06-19-real-provider-review-eval.md +++ b/intent/16-enforcement/.experiments/2026-06-19-real-provider-review-eval.md @@ -1,14 +1,18 @@ -# Real provider VRS review eval +# Real provider Intent review eval + +The terminology and protocol identifiers in this summary use the current Intent +contract. The original raw provider report used superseded identifiers and was +retired rather than rewritten as captured output. ## Question After CAIC provider hardening and stock backend-id cleanup, bounded manual -`axe vrs review` runs against a small existing VRS subsystem should complete and -write `axe.vrs.review.v1` reports for the supported stock backends. +`intent review` runs against a small existing Intent subsystem should complete and +write `axe.intent.review.v1` reports for the supported stock backends. ## Method -Target: `context/vrs/16-enforcement` +Target: `intent/16-enforcement` Commands used built `axe` and `coding-agent` binaries from the branch, with `--timeout-seconds 180` and `--report` paths under this experiment directory. @@ -20,9 +24,9 @@ The run was manual and not part of CI or a Nix check. | --- | --- | | `codex` before schema hardening | Failed before semantic output. Improved CAIC diagnostics showed Codex rejected the review schema because `schema_version` used `const` without a `type`. | | `codex` after adding string types | Failed before semantic output. Codex then rejected the schema because `gate` was a property but not listed in `required`. | -| `codex` after requiring `gate` | Succeeded and wrote [real-provider-reports/2026-06-19-codex-review.json](./real-provider-reports/2026-06-19-codex-review.json). The report contains one `VRS.REVIEW.semantic-ownership` warning. | +| `codex` after requiring `gate` | Succeeded and produced one semantic-ownership warning. The raw report used superseded identifiers and was retired during the Intent-wide contract migration rather than rewritten as if it were newly captured evidence. | | `claude` after schema hardening | Failed with CAIC `timeout` after the bounded 180-second run. No report file was written. | -| `claude` wrapper probe after timeout investigation | A tiny direct `--bare` probe spent zero tokens and failed immediately with `Not logged in · Please run /login`, confirming that this worktree has no API-key auth for isolated Claude runs. A CAIC probe then failed before model execution because the wrapper passed retired/unsupported `MultiEdit` in `--disallowedTools`; the installed Claude CLI rejects unknown deny rules. A full `axe vrs review` probe still timed out because CAIC placed variadic `--add-dir ` immediately before the positional prompt, so Claude consumed the prompt as part of `--add-dir` instead of receiving review input. | +| `claude` wrapper probe after timeout investigation | A tiny direct `--bare` probe spent zero tokens and failed immediately with `Not logged in · Please run /login`, confirming that this worktree has no API-key auth for isolated Claude runs. A CAIC probe then failed before model execution because the wrapper passed retired/unsupported `MultiEdit` in `--disallowedTools`; the installed Claude CLI rejects unknown deny rules. A full `intent review` probe still timed out because CAIC placed variadic `--add-dir ` immediately before the positional prompt, so Claude consumed the prompt as part of `--add-dir` instead of receiving review input. | | Fake Claude regression after wrapper fix | Added token-free fake-provider coverage that rejects `MultiEdit`, requires CAIC to pass an explicit `--model sonnet`, and rejects `--add-dir` after `--json-schema` so the prompt cannot be swallowed by Claude's variadic directory option. | The Codex failures were actionable only after CAIC started returning redacted @@ -35,10 +39,10 @@ The successful Codex report found: ```json { - "rule": "VRS.REVIEW.semantic-ownership", + "rule": "INTENT.REVIEW.semantic-ownership", "severity": "warning", - "artifact": "context/vrs/16-enforcement/spec.md", - "owner": "Axe VRS command spec" + "artifact": "intent/16-enforcement/spec.md", + "owner": "Intent CLI command spec" } ``` @@ -46,7 +50,7 @@ The successful Codex report found: The deterministic and fake-provider paths are working. Production readiness is tracked per backend. The stock `codex` real-provider path is now proven for this -small VRS subsystem after schema hardening. The `claude` timeout investigation +small Intent subsystem after schema hardening. The `claude` timeout investigation found two wrapper-level command compatibility issues. First, the adapter passed `MultiEdit` in `--disallowedTools`, but the installed Claude CLI rejects that tool name before @@ -60,9 +64,9 @@ still requires API-key auth because `--bare` does not use local OAuth/keychain login. That is now a Claude-backend readiness delta, not a blocker for the already proven Codex backend. -## VRS Impact +## Intent Impact -The experiment supports the per-backend readiness rule in the Axe VRS spec and +The experiment supports the per-backend readiness rule in the Intent CLI spec and the remaining Claude-specific delta. It also validates keeping the baked review -schema in `context/vrs/16-enforcement` and keeping real-provider evals +schema in `intent/16-enforcement` and keeping real-provider evals manual-only. diff --git a/intent/16-enforcement/.experiments/real-provider-reports/2026-06-19-codex-review.json b/intent/16-enforcement/.experiments/real-provider-reports/2026-06-19-codex-review.json deleted file mode 100644 index 8b3a71a..0000000 --- a/intent/16-enforcement/.experiments/real-provider-reports/2026-06-19-codex-review.json +++ /dev/null @@ -1,127 +0,0 @@ -{ - "adapter": { - "name": "coding-agent-adapter", - "version": "0.1.0" - }, - "backend": { - "id": "codex", - "model": "gpt-5-codex", - "provider": "codex", - "provider_command": { - "argv_redacted": [ - "codex", - "exec", - "--cd", - "/tmp/dotfiles-vrs-fixture-check", - "--sandbox", - "read-only", - "-c", - "", - "--ignore-user-config", - "--ignore-rules", - "--ephemeral", - "-c", - "", - "--output-schema", - "", - "--json", - "--output-last-message", - "", - "" - ], - "binary": "codex", - "env_redacted": [ - "CODEX_HOME=" - ], - "omitted": [ - "prompt", - "secrets", - "large-context" - ], - "strategy": "native-schema" - }, - "requested": "codex" - }, - "result": { - "findings": [ - { - "artifact": "context/vrs/16-enforcement/spec.md", - "evidence": "The spec says real-provider execution policy is owned by the Axe VRS command spec, but then defines concrete policy: manual-only real-token runs, automated-context refusal, no extra token-confirmation flag, backend capability proof, stdout/report behavior.", - "gate": "review", - "owner": "Axe VRS command spec", - "rule": "VRS.REVIEW.semantic-ownership", - "severity": "warning", - "suggested_fix": "Move the concrete real-provider execution policy to the Axe VRS command spec, and leave this enforcement spec with only the semantic-review interface expectations it owns." - } - ], - "schema_version": "axe.vrs.review.v1", - "summary": "Semantic review found one ownership drift risk in the supplied enforcement spec. Deterministic diagnostics were empty." - }, - "run": { - "approval": { - "effective": "never", - "enforcement_source": "sandbox-and-noninteractive-exec", - "requested": "never" - }, - "config": { - "effective_policy": "isolated", - "loaded_behavioral_config": false, - "loaded_classes": [ - "auth", - "runtime" - ], - "requested_policy": "isolated" - }, - "context_files": [ - { - "origin": "generated-artifact", - "path": "/tmp/.tmpgyE5fp/axe-vrs-check.json", - "resolved_path": "/tmp/.tmpgyE5fp/axe-vrs-check.json", - "role": "generated-diagnostics" - }, - { - "origin": "workspace", - "path": "/tmp/dotfiles-vrs-fixture-check/context/vrs/16-enforcement/.experiments/2026-06-19-real-provider-review-eval.md", - "resolved_path": "/tmp/dotfiles-vrs-fixture-check/context/vrs/16-enforcement/.experiments/2026-06-19-real-provider-review-eval.md", - "role": "normative" - }, - { - "origin": "workspace", - "path": "/tmp/dotfiles-vrs-fixture-check/context/vrs/16-enforcement/requirements.md", - "resolved_path": "/tmp/dotfiles-vrs-fixture-check/context/vrs/16-enforcement/requirements.md", - "role": "normative" - }, - { - "origin": "workspace", - "path": "/tmp/dotfiles-vrs-fixture-check/context/vrs/16-enforcement/review-prompt.md", - "resolved_path": "/tmp/dotfiles-vrs-fixture-check/context/vrs/16-enforcement/review-prompt.md", - "role": "normative" - }, - { - "origin": "workspace", - "path": "/tmp/dotfiles-vrs-fixture-check/context/vrs/16-enforcement/spec.md", - "resolved_path": "/tmp/dotfiles-vrs-fixture-check/context/vrs/16-enforcement/spec.md", - "role": "normative" - } - ], - "cwd": "/tmp/dotfiles-vrs-fixture-check", - "id": "run_610725_1781863383354_0", - "mode": "review", - "network": { - "effective_policy": "disabled", - "provider_model_transport": "required", - "requested_policy": "disabled" - }, - "permission": { - "effective": "read-only", - "enforcement_source": "provider-native", - "requested": "read-only" - }, - "retry": { - "attempts": 1, - "reasons": [] - } - }, - "schema_version": "coding_agent.result.v1", - "status": "completed" -} \ No newline at end of file diff --git a/intent/16-enforcement/requirements.md b/intent/16-enforcement/requirements.md index 6f6efbb..73d7981 100644 --- a/intent/16-enforcement/requirements.md +++ b/intent/16-enforcement/requirements.md @@ -1,56 +1,56 @@ -# VRS Enforcement — Requirements +# Intent Enforcement — Requirements ## Context -- This child node defines how VRS hygiene is checked in real repository VRS +- This child node defines how Intent hygiene is checked in real repository Intent trees. -- It refines [VRS-R18](../requirements.md), [VRS-R25](../requirements.md), and - [VRS-R27](../requirements.md). +- It refines [INTENT-R18](../requirements.md), [INTENT-R25](../requirements.md), and + [INTENT-R27](../requirements.md). ## Requirements ### Must Preserve Semantic Ownership -- **VRS.ENF-R01 Enforcement does not own semantics:** Enforcement must validate - VRS artifacts against the contracts owned by the file-kind and concept nodes; +- **INTENT.ENF-R01 Enforcement does not own semantics:** Enforcement must validate + Intent artifacts against the contracts owned by the file-kind and concept nodes; it must not become the place where those contracts are defined. -- **VRS.ENF-R02 Narrow scope:** Enforcement covers repo hygiene, diagnostics, +- **INTENT.ENF-R02 Narrow scope:** Enforcement covers repo hygiene, diagnostics, and review gates. It does not own artifact authoring procedure, isolated - scenario evaluation, or implementation of every future VRS-related tool. + scenario evaluation, or implementation of every future Intent-related tool. ### Must Separate Mechanical and Semantic Checks -- **VRS.ENF-R03 Deterministic checks:** Mechanical invariants should be checked +- **INTENT.ENF-R03 Deterministic checks:** Mechanical invariants should be checked by token-free deterministic tooling when feasible. -- **VRS.ENF-R04 Semantic review:** Intent-quality checks that require judgment +- **INTENT.ENF-R04 Semantic review:** Intent-quality checks that require judgment must be reported separately from deterministic lint findings. -- **VRS.ENF-R05 Blocking clarity:** Each enforcement mode must say whether it is +- **INTENT.ENF-R05 Blocking clarity:** Each enforcement mode must say whether it is merge-blocking, advisory, or review-only. ### Must Produce Actionable Diagnostics -- **VRS.ENF-R06 Artifact owner:** Every finding must name the VRS artifact or +- **INTENT.ENF-R06 Artifact owner:** Every finding must name the Intent artifact or child node that owns the fix. -- **VRS.ENF-R07 Evidence:** Every finding must include enough evidence for a +- **INTENT.ENF-R07 Evidence:** Every finding must include enough evidence for a reader or agent to reproduce or inspect it. -- **VRS.ENF-R08 Machine-readable output:** Tooling-oriented enforcement should +- **INTENT.ENF-R08 Machine-readable output:** Tooling-oriented enforcement should support structured output so agents and CI can route findings precisely. ### Must Fit Existing Workflows -- **VRS.ENF-R09 Local-first:** Deterministic enforcement must be runnable locally +- **INTENT.ENF-R09 Local-first:** Deterministic enforcement must be runnable locally before CI. -- **VRS.ENF-R10 Eval feedback:** False positives, missing checks, or ambiguous +- **INTENT.ENF-R10 Eval feedback:** False positives, missing checks, or ambiguous diagnostics should feed back into [15-evaluation](../15-evaluation/spec.md) - scenarios or the owning VRS contract. + scenarios or the owning Intent contract. ### Must Enforce Cross-References Incrementally -- **VRS.ENF-R11 Xref subset:** Cross-reference enforcement must start with a +- **INTENT.ENF-R11 Xref subset:** Cross-reference enforcement must start with a deterministic subset that can be checked from repository contents alone. -- **VRS.ENF-R12 Commit consistency:** Xref enforcement must validate references +- **INTENT.ENF-R12 Commit consistency:** Xref enforcement must validate references against the current commit, not require identifiers to remain stable across future commits. -- **VRS.ENF-R13 Wiki-link migration:** Wiki-style links in normative artifacts +- **INTENT.ENF-R13 Wiki-link migration:** Wiki-style links in normative artifacts should be warned on first and promoted to errors only after the intended migration path is clear. diff --git a/intent/16-enforcement/review-prompt.md b/intent/16-enforcement/review-prompt.md index f68288f..bdd9603 100644 --- a/intent/16-enforcement/review-prompt.md +++ b/intent/16-enforcement/review-prompt.md @@ -1,15 +1,15 @@ -# VRS Semantic Review Prompt +# Intent Semantic Review Prompt -You are running `axe vrs review`. +You are running `intent review`. -Review only the supplied VRS artifacts, deterministic diagnostics, and -normative VRS contracts. Return JSON that matches `axe.vrs.review.v1`. Do not +Review only the supplied Intent artifacts, deterministic diagnostics, and +normative Intent contracts. Return JSON that matches `axe.intent.review.v1`. Do not edit files, do not propose patches, and do not rely on repository files that were not supplied as context. ## Review Scope -Classify semantic VRS issues that deterministic lint cannot prove safely: +Classify semantic Intent issues that deterministic lint cannot prove safely: - `vision.md` contains implementation, architecture, tools, migration plans, or other mechanisms instead of durable intent. @@ -24,16 +24,16 @@ Classify semantic VRS issues that deterministic lint cannot prove safely: being accepted, folded, deferred, or deleted. - `.experiments/` contains plans instead of evidence, or aggregates unrelated questions into one unclear conclusion. -- `.reference/` contains copied source material without explaining VRS impact. +- `.reference/` contains copied source material without explaining Intent impact. - `.delta/` contains stale, completed, speculative, duplicate, or vague entries. - `open-questions.md` contains resolved questions or questions without a real blocker. - `roadmap.md` contains current contract rather than non-normative future direction. -- Empty companion directories or README-style VRS entry points appear where the - meta-VRS contract does not allow them. +- Empty companion directories or README-style Intent entry points appear where the + root Intent contract does not allow them. -Use the review-smell catalog in `context/vrs/13-review-smells/spec.md` as the +Use the review-smell catalog in `intent/13-review-smells/spec.md` as the primary rubric when it is supplied. ## Finding Rules @@ -42,10 +42,10 @@ Only report findings that are actionable and grounded in supplied evidence. Each finding must: -- name the owner artifact or VRS child node that should receive the fix; +- name the owner artifact or Intent child node that should receive the fix; - cite the concrete evidence that led to the finding; - describe the smallest principled fix; -- use severity `error` only when the issue blocks a correct VRS update or would +- use severity `error` only when the issue blocks a correct Intent update or would make automated enforcement unsafe; - use severity `warning` for likely semantic drift that needs review; - use severity `info` for non-blocking observations that help route future diff --git a/intent/16-enforcement/review-result.schema.json b/intent/16-enforcement/review-result.schema.json index 24c1023..3dec78a 100644 --- a/intent/16-enforcement/review-result.schema.json +++ b/intent/16-enforcement/review-result.schema.json @@ -1,13 +1,13 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schickling.dev/schemas/axe.vrs.review.v1.json", - "title": "Axe VRS Semantic Review Result", + "$id": "https://schickling.dev/schemas/axe.intent.review.v1.json", + "title": "Intent CLI Semantic Review Result", "type": "object", "required": ["schema_version", "summary", "findings"], "properties": { "schema_version": { "type": "string", - "const": "axe.vrs.review.v1" + "const": "axe.intent.review.v1" }, "summary": { "type": "string", @@ -29,7 +29,7 @@ "properties": { "rule": { "type": "string", - "pattern": "^VRS\\.REVIEW\\.[a-z0-9.-]+$" + "pattern": "^INTENT\\.REVIEW\\.[a-z0-9.-]+$" }, "severity": { "type": "string", diff --git a/intent/16-enforcement/spec.md b/intent/16-enforcement/spec.md index 4e71004..3f3526a 100644 --- a/intent/16-enforcement/spec.md +++ b/intent/16-enforcement/spec.md @@ -1,6 +1,6 @@ -# VRS Enforcement — Spec +# Intent Enforcement — Spec -This document specifies VRS enforcement for real repository VRS trees. It builds +This document specifies Intent enforcement for real repository Intent trees. It builds on [requirements.md](./requirements.md). ## Status @@ -9,7 +9,7 @@ Draft. ## Scope -Enforcement checks whether VRS artifacts obey the meta-VRS contract. It does not +Enforcement checks whether Intent artifacts obey the root Intent contract. It does not define artifact semantics; it consumes the contracts owned by sibling nodes such as [02-requirements](../02-requirements/spec.md), [03-spec](../03-spec/spec.md), [06-decisions](../06-decisions/spec.md), @@ -20,24 +20,24 @@ Enforcement is distinct from [15-evaluation](../15-evaluation/spec.md): | Concept | Target | Output | | --- | --- | --- | -| Evaluation | Temporary scenario outside tracked files | Evidence about whether VRS/skills work end to end | -| Enforcement | Real repository VRS artifacts | Findings about hygiene, validity, and review risk | +| Evaluation | Temporary scenario outside tracked files | Evidence about whether Intent/skills work end to end | +| Enforcement | Real repository Intent artifacts | Findings about hygiene, validity, and review risk | ## Enforcement Layers | Layer | Checks | Default Gate | | --- | --- | --- | | Deterministic lint | File names, required sections, IDs, links, companion shapes, empty directories, proposed records, obvious stale delta markers | Merge-blocking once implemented and calibrated | -| Semantic review | Vision purity, requirement testability, spec completeness, decision substance, open-question freshness, review-smell judgment | Advisory until a VRS or project policy makes it blocking | -| Eval feedback | Reproduces false positives, missing checks, and ambiguous diagnostics in isolated scenarios | Evidence for VRS updates | +| Semantic review | Vision purity, requirement testability, spec completeness, decision substance, open-question freshness, review-smell judgment | Advisory until an Intent or project policy makes it blocking | +| Eval feedback | Reproduces false positives, missing checks, and ambiguous diagnostics in isolated scenarios | Evidence for Intent updates | ## Deterministic Check Candidates The first deterministic enforcement surface should prioritize checks that are cheap, local, and low-ambiguity: -- VRS node detection and allowed lazy companion directories. -- Numeric child directory names (`NN-slug`) where child VRS nodes are used. +- Intent node detection and allowed lazy companion directories. +- Numeric child directory names (`NN-slug`) where child Intent nodes are used. - Required sections for each artifact kind. - `spec.md` status and link to its `requirements.md`, with explicit exceptions for root nodes if needed. @@ -63,7 +63,7 @@ Xref enforcement applies the commit-scoped identifier contract from | Cross-node references are namespaced or include a Markdown link to the owning artifact. | Warning first; blocking after migration | | Wiki-style links in normative artifacts point to docs, decisions, requirements, or specs. | Warning first; error after migration | -This is not a full typed VRS graph. The first checker should avoid semantic +This is not a full typed Intent graph. The first checker should avoid semantic judgment and should report ambiguous references instead of guessing. If a rule cannot resolve scope from the current artifact and links, it emits a diagnostic that names the missing scope declaration or owning artifact. @@ -98,12 +98,12 @@ Initial migration ordering: The first blocking rule should be local Markdown link existence because it is cheap, local, low-ambiguity, and directly improves navigation. Decision-record shape is the second blocking candidate only after experiments are promising. The -initial decision-shape experiment found the meta-VRS decisions compatible with +initial decision-shape experiment found the root Intent contract decisions compatible with the proposed strict shape, but the wider `context/**/.decisions` corpus is not ready for repo-wide blocking without migration or scoped enforcement. Initial strict decision-shape enforcement applies only to -`context/vrs/.decisions/`. Other `context/**/.decisions/` records may be scanned +`intent/.decisions/`. Other `context/**/.decisions/` records may be scanned for migration diagnostics later, but they are not part of the first strict decision-shape scope. @@ -127,18 +127,18 @@ judgment is deterministic: The baked semantic-review prompt and output schema live in this enforcement node: -- [review-prompt.md](./review-prompt.md) defines the default `axe vrs review` - prompt and routes semantic judgment to the owning VRS contracts. +- [review-prompt.md](./review-prompt.md) defines the default `intent review` + prompt and routes semantic judgment to the owning Intent contracts. - [review-result.schema.json](./review-result.schema.json) defines the - `axe.vrs.review.v1` result shape. + `axe.intent.review.v1` result shape. -`axe vrs review` consumes these assets through the Coding Agent Invocation +`intent review` consumes these assets through the Coding Agent Invocation Contract. Callers do not provide arbitrary prompts for the standard review -mode; prompt and schema changes are VRS changes and should be evaluated through +mode; prompt and schema changes are Intent changes and should be evaluated through fixtures before becoming the baked version. Real-provider execution policy is owned by the -[VRS command spec](../../context/cli/spec.md). Enforcement +[Intent command spec](../../context/cli/spec.md). Enforcement owns the baked prompt, result schema, semantic finding shape, and fixture-backed quality evidence. The command spec owns when providers may run, which CAIC contract pieces are required, and how stdout/report routing behaves. @@ -152,10 +152,10 @@ Structured enforcement output should preserve enough routing context for agents: "kind": "deterministic | semantic", "severity": "error | warning | info", "gate": "blocking | advisory | review", - "artifact": "context/vrs/requirements.md", + "artifact": "intent/requirements.md", "owner": "02-requirements", - "rule": "VRS.ENF.", - "evidence": "Requirement IDs skip VRS-R12.", + "rule": "INTENT.ENF.", + "evidence": "Requirement IDs skip INTENT-R12.", "suggested_fix": "Renumber the requirement or update references." } ``` @@ -166,7 +166,7 @@ Deterministic enforcement should be implemented behind a checker interface that can be consumed by multiple operator surfaces without duplicating rule logic. The checker owns mechanical parsing, rule evaluation, derived graph extraction, and diagnostic emission. It does not own the semantics of the artifacts it -checks; those stay in the relevant meta-VRS nodes. +checks; those stay in the relevant root Intent contract nodes. Enforcement owns the reusable checking contract, not command-surface behavior. Consumers may call this interface from CLIs, Nix checks, review workflows, or @@ -187,10 +187,10 @@ The enforcement interface should expose: Deterministic enforcement should integrate with the repo's local check workflow before becoming a CI expectation. Semantic review should be available as an explicit agent or LLM-backed review mode that reports findings by owner artifact -and does not silently rewrite VRS. +and does not silently rewrite Intent. -`grill-vrs` may call enforcement during a VRS session, but it remains the -interview/update procedure. Enforcement supplies findings; the owning VRS +`grill-intent` may call enforcement during an Intent session, but it remains the +interview/update procedure. Enforcement supplies findings; the owning Intent artifact still receives the durable fix. ## Gate Policy @@ -201,7 +201,7 @@ still needs cleanup, fixture coverage, or false-positive calibration; after that migration completes, the rule is either promoted to blocking or deleted. Semantic review is advisory by default. It may become blocking only for a -specific VRS or project policy after evidence shows that the review mode is +specific Intent or project policy after evidence shows that the review mode is reliable enough for that scope and has a clear appeal or override path. Until then, semantic findings route to review comments, deltas, decisions, or open -questions owned by the affected VRS artifact. +questions owned by the affected Intent artifact. diff --git a/intent/intuition.md b/intent/intuition.md index 1775ae6..29e8f12 100644 --- a/intent/intuition.md +++ b/intent/intuition.md @@ -1,11 +1,11 @@ -# VRS — Intuition +# Intent — Intuition *For: agents and maintainers shaping durable system docs · Assumes: Markdown -docs live beside code or under `context/` · Covers: the mental model for VRS as +docs live beside code or under `context/` · Covers: the mental model for Intent as a self-describing documentation system* -VRS is a compact contract for keeping design knowledge current without turning -docs into plans, changelogs, or essays. A VRS tree separates durable intent from +Intent is a compact contract for keeping design knowledge current without turning +docs into plans, changelogs, or essays. An Intent tree separates durable intent from implementation detail: ```text @@ -22,24 +22,24 @@ open-questions.md unresolved design uncertainty roadmap.md non-committed future direction ``` -Not every VRS node has every file. Files and companion directories are lazy: +Not every Intent node has every file. Files and companion directories are lazy: create them when there is real content, not to satisfy a template. -The narrative entry point for a VRS node is `intuition.md`, not `README.md`. +The narrative entry point for an Intent node is `intuition.md`, not `README.md`. It builds the reader's mental model and may include the system map; it is part -of the VRS language rather than a generic repository convention. In directory +of the Intent language rather than a generic repository convention. In directory shape, it follows the formal `vision.md`/`requirements.md`/`spec.md` chain and `ontology.md`. -VRS is hierarchical. A root VRS defines the system-level contract; child VRS +Intent is hierarchical. A root Intent defines the system-level contract; child Intent nodes refine one file kind, subsystem, mechanism, or concept when the parent -would otherwise become too large or ambiguous. The meta-VRS uses this recursively: +would otherwise become too large or ambiguous. The root Intent contract uses this recursively: Vision, Requirements, Spec, Ontology, Decision Records, Experiments, Reference, -Delta, Open Questions, and Roadmap each deserve their own child VRS when their +Delta, Open Questions, and Roadmap each deserve their own child Intent when their contract needs more detail than the root can carry cleanly. Decision records are durable. Proposed decisions are allowed during a PR so an agent can continue working without blocking on every unresolved design choice, but proposed records are PR-local scaffolding. Before merge, each proposed -decision is accepted into `.decisions/`, folded into the relevant VRS document, +decision is accepted into `.decisions/`, folded into the relevant Intent document, or deleted. diff --git a/intent/ontology.md b/intent/ontology.md index d2cdaa6..369a001 100644 --- a/intent/ontology.md +++ b/intent/ontology.md @@ -1,39 +1,41 @@ -# VRS — Ontology +# Intent — Ontology -Canonical language for the VRS documentation system. These terms apply to VRS +Canonical language for the Intent documentation system. These terms apply to Intent trees in `context/` and package-local docs. This node has no structure layer — the terms are largely independent, so the minimal (language-only) ontology is enough. ## Language -**VRS**: -The documentation system composed from Vision, Requirements, and Spec documents -plus lazy companion artifacts. +**Intent**: +The project's intent layer and the documentation system that records it, +composed from Vision, Requirements, and Spec documents plus lazy companion +artifacts. _Avoid_: docs template, planning docs **Intent Layer**: -The role VRS plays in a project: durable, structured intent that constrains -code, plans, skills, and agent behavior without replacing implementation truth. -_Avoid_: source of implementation truth, project plan +A descriptive role for Intent, not a second system name: durable, structured +intent that constrains code, plans, skills, and agent behavior without replacing +implementation truth. +_Avoid_: separate layer name, source of implementation truth, project plan -**VRS Node**: -A directory that owns a coherent VRS scope, such as a system, subsystem, +**Intent Node**: +A directory that owns a coherent Intent scope, such as a system, subsystem, mechanism, file-kind contract, or concept. _Avoid_: folder, module -**Child VRS Node**: -A VRS Node that refines part of a parent node's contract without restating the +**Child Intent Node**: +An Intent Node that refines part of a parent node's contract without restating the parent's intent. _Avoid_: section, nested README **Common Subsystem**: -A recurring VRS child-node shape that is often useful across topics, such as +A recurring Intent child-node shape that is often useful across topics, such as data model, interface, verification, integrations, or operations. _Avoid_: companion file **Intuition**: -The narrative entry point for a VRS Node; it gives the mental model and system +The narrative entry point for an Intent Node; it gives the mental model and system map that the formal documents assume. _Avoid_: README @@ -44,7 +46,7 @@ _Avoid_: ADR, changelog entry **Proposed Decision**: A PR-local working decision record that lets an agent proceed autonomously until -the decision is accepted, folded into another VRS artifact, deferred, or deleted. +the decision is accepted, folded into another Intent artifact, deferred, or deleted. _Avoid_: accepted decision, main-branch proposal **Experiment**: @@ -53,7 +55,7 @@ performance claim, or integration behavior. _Avoid_: plan, todo **Reference**: -External source material a VRS Node depends on, such as API behavior, standards, +External source material an Intent Node depends on, such as API behavior, standards, third-party documentation, or source snapshots. _Avoid_: experiment @@ -64,10 +66,10 @@ _Avoid_: roadmap item, delta, task **Roadmap**: Non-normative future direction that is concrete enough to preserve but not yet -part of the current VRS contract. +part of the current Intent contract. _Avoid_: spec, backlog, open question **Delta**: -A confirmed, currently open divergence between the VRS contract and the current +A confirmed, currently open divergence between the Intent contract and the current implementation, tracked under `.delta/`. _Avoid_: backlog, roadmap diff --git a/intent/requirements.md b/intent/requirements.md index 0e36ec7..d019347 100644 --- a/intent/requirements.md +++ b/intent/requirements.md @@ -1,126 +1,128 @@ -# VRS — Requirements +# Intent — Requirements ## Context -- This topic defines VRS by using VRS. The root VRS constrains the operational - skill and the child VRS nodes. -- Coding agents are expected to create and update VRS artifacts while working, +- This topic defines Intent by using Intent. The root Intent constrains the operational + skill and the child Intent nodes. +- Coding agents are expected to create and update Intent artifacts while working, so the contract must support autonomous progress without allowing temporary scaffolding to merge as durable truth. ## Assumptions -- **VRS-A01 Markdown as durable medium:** VRS artifacts are Markdown files +- **INTENT-A01 Markdown as durable medium:** Intent artifacts are Markdown files tracked in Git. -- **VRS-A02 Lazy artifacts:** Not every VRS node needs every companion file or +- **INTENT-A02 Lazy artifacts:** Not every Intent node needs every companion file or directory. Empty template structure is noise. ## Constraints -- **VRS-C01 Git-backed lifecycle:** VRS merge hygiene relies on Git review and +- **INTENT-C01 Git-backed lifecycle:** Intent merge hygiene relies on Git review and history; closed decision proposals and deltas are pruned rather than archived in separate closed-state files. ## Acceptable Tradeoffs -- **VRS-T01 Broad decision records:** VRS uses "Decision Record" rather than +- **INTENT-T01 Broad decision records:** Intent uses "Decision Record" rather than ADR, trading some external acronym recognition for a term that covers non-architecture decisions. -- **VRS-T02 PR-local proposals:** Proposed decision records may exist during a +- **INTENT-T02 PR-local proposals:** Proposed decision records may exist during a PR, trading short-lived branch noise for agent autonomy and explicit merge hygiene. -- **VRS-T03 Child-node detail:** The root VRS delegates detailed file-kind rules - to child VRS nodes, trading one-stop compactness for composability. +- **INTENT-T03 Child-node detail:** The root Intent delegates detailed file-kind rules + to child Intent nodes, trading one-stop compactness for composability. ## Requirements ### Must Separate Artifact Responsibilities -- **VRS-R01 Clear ownership:** Every durable VRS fact must have a primary owning +- **INTENT-R01 Clear ownership:** Every durable Intent fact must have a primary owning artifact kind: vision, requirements, spec, ontology, intuition, decision record, experiment, reference, open question, roadmap, or delta. -- **VRS-R02 No upstream restatement:** A child artifact must reference upstream +- **INTENT-R02 No upstream restatement:** A child artifact must reference upstream constraints instead of restating them. -- **VRS-R03 Protected intent:** `vision.md` and `requirements.md` changes +- **INTENT-R03 Protected intent:** `vision.md` and `requirements.md` changes require deliberate confirmation because they change goals or constraints. ### Must Support Hierarchy -- **VRS-R04 Child VRS nodes:** The system must support child VRS nodes for +- **INTENT-R04 Child Intent nodes:** The system must support child Intent nodes for subsystems, mechanisms, file-kind contracts, and cross-cutting concepts. -- **VRS-R05 Formal-first order:** The meta-VRS child-node order must begin with - the formal VRS chain (`vision`, `requirements`, `spec`), followed by +- **INTENT-R05 Formal-first order:** The root Intent contract's child-node order must begin with + the formal Intent chain (`vision`, `requirements`, `spec`), followed by `ontology`, `intuition`, and companion concepts. -- **VRS-R06 Commit-scoped identifiers:** Identifiers must be internally +- **INTENT-R06 Commit-scoped identifiers:** Identifiers must be internally consistent within each repository commit and must not depend on numeric directory prefixes. ### Must Keep Main Clean -- **VRS-R07 Durable decisions only on main:** Main branch must contain only +- **INTENT-R07 Durable decisions only on main:** Main branch must contain only durable accepted, deprecated, or superseded decision records. -- **VRS-R08 Proposed decisions are PR-local:** `.decisions/.proposed/` may +- **INTENT-R08 Proposed decisions are PR-local:** `.decisions/.proposed/` may exist in a PR but must be empty or absent before merge. -- **VRS-R09 Lazy companion directories:** `.experiments/` and `.reference/` are +- **INTENT-R09 Lazy companion directories:** `.experiments/` and `.reference/` are first-class companion directories but must be created only when they contain real evidence or source material. ### Must Support Verification -- **VRS-R10 Evidence promotion:** Findings from experiments or references must - be promoted into normative VRS artifacts when they affect system truth. -- **VRS-R11 Delta tracking:** Known divergence between VRS and implementation +- **INTENT-R10 Evidence promotion:** Findings from experiments or references must + be promoted into normative Intent artifacts when they affect system truth. +- **INTENT-R11 Delta tracking:** Known divergence between Intent and implementation must be tracked explicitly in `.delta/` rather than hidden in prose. -- **VRS-R12 Skill projection:** Operational agent skills must be reducible to - procedures that apply the normative VRS contract instead of duplicating the +- **INTENT-R12 Skill projection:** Operational agent skills must be reducible to + procedures that apply the normative Intent contract instead of duplicating the contract. -- **VRS-R13 Delta freshness:** Delta records must be kept current and pruned - when resolved, folded into VRS, or superseded by an accepted decision. -- **VRS-R14 Open-question freshness:** Resolved, stale, or no-longer-relevant +- **INTENT-R13 Delta freshness:** Delta records must be kept current and pruned + when resolved, folded into Intent, or superseded by an accepted decision. +- **INTENT-R14 Open-question freshness:** Resolved, stale, or no-longer-relevant questions must be removed from `open-questions.md` and moved to their owning - artifact when the answer affects VRS. -- **VRS-R15 Roadmap separation:** Future direction that is not yet normative + artifact when the answer affects Intent. +- **INTENT-R15 Roadmap separation:** Future direction that is not yet normative must live in `roadmap.md`, not in `spec.md`, `open-questions.md`, or `.delta/`. -- **VRS-R16 Referenced constraints:** Constraints caused by external systems, +- **INTENT-R16 Referenced constraints:** Constraints caused by external systems, standards, APIs, platforms, or resource envelopes must be captured in `requirements.md` and backed by `.reference/` when the source is not obvious from repository code. -- **VRS-R17 Common subsystem candidates:** Data models, interfaces, +- **INTENT-R17 Common subsystem candidates:** Data models, interfaces, verification loops, integrations, and operations/resource bounds must be - considered as child VRS nodes when they are substantial enough to need their + considered as child Intent nodes when they are substantial enough to need their own requirements and spec. -- **VRS-R18 Review smells:** VRS authors and agents must check for documented - VRS smells when creating or editing VRS artifacts and fix the artifact owner +- **INTENT-R18 Review smells:** Intent authors and agents must check for documented + Intent smells when creating or editing Intent artifacts and fix the artifact owner rather than preserving the smell. -- **VRS-R19 Drafting open questions:** During initial VRS drafting, +- **INTENT-R19 Drafting open questions:** During initial Intent drafting, `open-questions.md` may hold temporary coverage questions, but agents must try to resolve all open questions before finalizing unless each remaining question names a clear blocker. -- **VRS-R20 Assumption validation:** Load-bearing assumptions must be validated - in the best feasible way before becoming durable VRS truth. Valid forms +- **INTENT-R20 Assumption validation:** Load-bearing assumptions must be validated + in the best feasible way before becoming durable Intent truth. Valid forms include user confirmation, research, benchmarks, e2e experiments, prototypes, proofs, implementation evidence, or independent agent critique. -- **VRS-R21 Evidence-backed decisions:** Durable decision records must include +- **INTENT-R21 Evidence-backed decisions:** Durable decision records must include evidence or argument, principled options with tradeoffs, and a clear reason - the chosen option is best under the current VRS context. -- **VRS-R22 Intent layer:** VRS must be described as the project's intent layer - while keeping "VRS" as the concrete artifact/system name. -- **VRS-R23 Grill VRS procedure:** The Socratic interview/update skill should be - named `grill-vrs` and treated as the procedure for applying the VRS contract, + the chosen option is best under the current Intent context. +- **INTENT-R22 One canonical name:** Intent is the only name for the project's + intent layer, artifact system, corpus, nodes, tooling contracts, and + operational procedures. Paths and command names use `intent`; structured IDs + and diagnostic namespaces use `INTENT`. +- **INTENT-R23 Grill Intent procedure:** The Socratic interview/update skill should be + named `grill-intent` and treated as the procedure for applying the Intent contract, not as a duplicate source of artifact rules. -- **VRS-R24 Ontology through Grill VRS:** `grill-vrs` must handle fuzzy, - conflicting, or overloaded language by applying the meta-VRS ontology contract. +- **INTENT-R24 Ontology through Grill Intent:** `grill-intent` must handle fuzzy, + conflicting, or overloaded language by applying the root Intent ontology contract. The reusable term-design discipline lives in the `ontology`/`naming` skills; - `grill-vrs` owns applying it to the ontology artifact during interviews rather + `grill-intent` owns applying it to the ontology artifact during interviews rather than duplicating the procedure. -- **VRS-R25 Isolated evaluation:** VRS and VRS skills must be evaluable through +- **INTENT-R25 Isolated evaluation:** Intent and Intent skills must be evaluable through isolated scenario runs that produce evidence without modifying tracked project files. -- **VRS-R26 Existing VRS references:** VRS authors should inspect existing VRS +- **INTENT-R26 Existing Intent references:** Intent authors should inspect existing Intent systems as reference examples when helpful, while preserving the target system's own structure and constraints. -- **VRS-R27 Enforcement:** VRS must support repo hygiene enforcement through a +- **INTENT-R27 Enforcement:** Intent must support repo hygiene enforcement through a narrow enforcement contract that distinguishes deterministic lint from semantic review without turning enforcement into the owner of artifact semantics. diff --git a/intent/roadmap.md b/intent/roadmap.md index 49b95a6..7e6af94 100644 --- a/intent/roadmap.md +++ b/intent/roadmap.md @@ -1,37 +1,37 @@ -# VRS — Roadmap +# Intent — Roadmap Non-normative future direction. Entries do not constrain implementation until promoted into requirements, spec, or a decision record. ## Planning Integration -- **Planning-tool integration:** VRS should eventually integrate with whichever - tool owns durable plan intent, so long-running agent work can reference VRS - artifacts, propose VRS changes, attach VRS evidence, and route durable +- **Planning-tool integration:** Intent should eventually integrate with whichever + tool owns durable plan intent, so long-running agent work can reference Intent + artifacts, propose Intent changes, attach Intent evidence, and route durable learning back into the intent layer. Plan authority is external to this repository, so the integration is a consumer contract rather than a shared data model. - Trigger: an external planning authority is the normal durable work surface for agents, and exposes a stable reference for a plan and a step. - - Promotion target: requirements, spec, or a dedicated integration child VRS. + - Promotion target: requirements, spec, or a dedicated integration child Intent. ## Structured Intent Layer -- **Structured VRS representation:** VRS should eventually move beyond a brittle +- **Structured Intent representation:** Intent should eventually move beyond a brittle collection of Markdown conventions toward a more structured intent layer with symbolic references, typed records, checked schemas, and tooling support for restructuring, renumbering, and cross-reference maintenance. - Current policy: roadmap only. Markdown artifacts remain normative until enforcement evidence shows that additional machine-readable structure is worth the authoring and migration cost. - - Trigger: evidence shows a structured representation improves VRS + - Trigger: evidence shows a structured representation improves Intent correctness and maintainability without making authoring too heavy. - Promotion target: requirements, spec, enforcement, or a dedicated structured - VRS child node. -- **Typed graph v0:** Before a full typed-source model, VRS should define a + Intent child node. +- **Typed graph v0:** Before a full typed-source model, Intent should define a small Markdown-authored graph contract for nodes, IDs, references, refinement edges, statuses, and evidence edges. Markdown remains authoritative; generated graph JSON is derived. - Trigger: deterministic lint needs structure that cannot be inferred reliably from prose alone. - - Promotion target: enforcement spec or a dedicated structured VRS child node. + - Promotion target: enforcement spec or a dedicated structured Intent child node. diff --git a/intent/spec.md b/intent/spec.md index 42372b8..7bcddb9 100644 --- a/intent/spec.md +++ b/intent/spec.md @@ -1,7 +1,7 @@ -# VRS — Spec +# Intent — Spec -This document specifies the VRS documentation system itself. It is the root -contract for the operational VRS skill and for VRS trees in `context/` or +This document specifies the Intent documentation system itself. It is the root +contract for the operational Intent skill and for Intent trees in `context/` or package-local docs. ## Status @@ -10,24 +10,24 @@ Draft. ## Scope -This root spec defines the shape of VRS nodes, companion artifacts, hierarchy, -and lifecycle rules that apply across VRS documents. +This root spec defines the shape of Intent nodes, companion artifacts, hierarchy, +and lifecycle rules that apply across Intent documents. It does not define the full section-level contract for every file kind. Those -contracts live in child VRS nodes so the root remains small and composable. +contracts live in child Intent nodes so the root remains small and composable. -VRS is the project's **intent layer**. It records durable, structured intent -that constrains code, plans, skills, and agent behavior without replacing -implementation truth. "Intent layer" names the role; VRS remains the concrete -artifact system. +Intent is the project's **intent layer** and the concrete artifact system that +records it. It records durable, structured intent that constrains code, plans, +skills, and agent behavior without replacing implementation truth. The same +name applies to the layer, corpus, artifacts, nodes, and tooling contracts. ## Root Node Shape -A VRS node is a directory whose files collectively describe one durable system, +An Intent node is a directory whose files collectively describe one durable system, subsystem, concept, or documentation contract. ```text -/ +/ vision.md # protected: why and success criteria requirements.md # protected: testable constraints spec.md # living blueprint @@ -47,23 +47,23 @@ subsystem, concept, or documentation contract. .md # external source snapshot or integration note ``` -All files and companion directories are lazy. A VRS node creates only the +All files and companion directories are lazy. An Intent node creates only the artifacts that carry real content. ## Entry Point -`intuition.md` is the narrative entry point. It replaces the VRS use of -`README.md`, but it follows the formal VRS chain and ontology in the directory +`intuition.md` is the narrative entry point. It replaces the Intent use of +`README.md`, but it follows the formal Intent chain and ontology in the directory shape. It gives the reader the system map, concepts, and operating model that the formal documents assume. Repository `README.md` files may still exist for package-level onboarding, but -they are not VRS artifacts. +they are not Intent artifacts. -## Child VRS Nodes +## Child Intent Nodes -The meta-VRS is self-recursive: each major VRS file kind or concept can have a -child VRS node that defines its own contract. +The root Intent contract is self-recursive: each major Intent file kind or +concept can have a child Intent node that defines its own contract. Initial child nodes: @@ -77,17 +77,17 @@ Initial child nodes: | `06-decisions/` | Durable decisions and PR-local proposed decisions | | `07-experiments/` | Validation evidence, prototypes, benchmarks, research | | `08-reference/` | External system assumptions and source snapshots | -| `09-delta/` | Gap tracking between VRS and implementation | +| `09-delta/` | Gap tracking between Intent and implementation | | `10-open-questions/` | Unresolved design uncertainty | | `11-roadmap/` | Future direction that is not yet contract | | `12-common-subsystems/` | Common subsystem patterns worth considering | -| `13-review-smells/` | VRS smells and bad patterns agents must check | -| `14-grill-vrs/` | Interview procedure for interrogating and updating VRS | -| `15-evaluation/` | Evaluation approach for VRS and VRS skills | +| `13-review-smells/` | Intent smells and bad patterns agents must check | +| `14-grill-intent/` | Interview procedure for interrogating and updating Intent | +| `15-evaluation/` | Evaluation approach for Intent and Intent skills | | `16-enforcement/` | Repo hygiene checks, diagnostics, and review gates | Child nodes use numeric prefixes for reading order only. The order starts with -the formal VRS chain (`vision` -> `requirements` -> `spec`), then language +the formal Intent chain (`vision` -> `requirements` -> `spec`), then language (`ontology`), then narrative entry (`intuition`), then companion concepts. Stable identifiers use semantic namespaces, not directory numbers. @@ -105,7 +105,7 @@ Use a decision record when all are true: Accepted decision records include at least one applicable evidence or argument type, principled options with tradeoffs, and a clear explanation for why the -chosen option is best under the current VRS context and constraints. Important +chosen option is best under the current Intent context and constraints. Important or risky decisions should use multiple independent evidence forms when feasible, such as research plus benchmark, prototype plus user confirmation, or proof plus implementation evidence. If the options or evidence are not clear yet, keep the @@ -122,14 +122,14 @@ Proposed decision records are branch-local scaffolding only: ## Experiments and Reference `.experiments/` and `.reference/` are first-class companion directories, but -they are lazy. Most VRS nodes do not need both. +they are lazy. Most Intent nodes do not need both. Use `.experiments/` for validation evidence produced by this project: prototypes, benchmarks, e2e validation, proofs, user confirmations, independent -critique, failed approaches, and research reports whose result informs the VRS +critique, failed approaches, and research reports whose result informs the Intent contract. -Use `.reference/` for external source material the VRS depends on: API +Use `.reference/` for external source material the Intent depends on: API snapshots, third-party behavior notes, standards excerpts, or integration assumptions. @@ -140,7 +140,7 @@ The companion directories preserve the evidence trail, not the source of truth. ## Delta `.delta/` is a first-class companion directory for confirmed divergence between -the VRS contract and current implementation, observed behavior, or verification +the Intent contract and current implementation, observed behavior, or verification evidence. It is lazy and visible in normal review because it answers which parts of the contract are not true yet. @@ -156,8 +156,8 @@ A delta is not a task, backlog item, or historical record. It must stay current: - create a delta only after confirming a real contract/reality divergence; - allow open deltas on main when they represent current known drift; - allow non-contiguous `DELTA-*` IDs after closed deltas are deleted; -- update it whenever the relevant VRS or implementation changes; -- close it by deleting the file once implementation and VRS agree again; +- update it whenever the relevant Intent or implementation changes; +- close it by deleting the file once implementation and Intent agree again; - if the divergence was intentional, replace the delta with the relevant requirement, spec change, or decision record; - stale, vague, or completed deltas must be pruned before merge. @@ -172,7 +172,7 @@ Resolved questions must leave `open-questions.md`. Resolution moves the content to the artifact that now owns it: spec, requirements, ontology, decision record, experiment, reference, roadmap, or deletion if it no longer matters. -During initial VRS drafting, `open-questions.md` may also hold temporary +During initial Intent drafting, `open-questions.md` may also hold temporary coverage questions so important areas are not forgotten. Before finalizing the draft, agents must try to resolve every open question; any remaining question must name the blocker that prevents resolution. @@ -191,7 +191,7 @@ implementation tasks. ## Common Subsystems -Some recurring design areas are often large enough to deserve child VRS nodes, +Some recurring design areas are often large enough to deserve child Intent nodes, but they are not generic companion files. Create them when the topic has real surface area, constraints, or independent verification needs. @@ -205,22 +205,22 @@ Common candidates: | `NN-integrations/` | External systems impose assumptions, constraints, references, auth, or compatibility boundaries. | | `NN-operations/` | Runtime operation, observability, rollout, recovery, capacity, or resource bounds need an explicit contract. | -These are subsystem VRS nodes with their own `requirements.md` and `spec.md`, +These are subsystem Intent nodes with their own `requirements.md` and `spec.md`, not top-level files such as `datamodel.md`. -## Existing VRS References +## Existing Intent References -When creating or reshaping a VRS tree, inspect existing VRS systems as reference +When creating or reshaping an Intent tree, inspect existing Intent systems as reference examples when helpful. Match the example to the problem shape: flat topic, hierarchical subsystem tree, composable contract/realization tree, or package-local docs, or intuition-heavy narrative tree. Discover current -examples by searching VRS roots rather than relying on a stale inventory. Use +examples by searching Intent roots rather than relying on a stale inventory. Use examples for precedent and calibration, not as templates to copy blindly. ## Review Smells -VRS smell checks are part of the meta-VRS contract. They are not a per-topic -artifact file; they are review rules agents apply when creating or editing VRS. +Intent smell checks are part of the root Intent contract. They are not a per-topic +artifact file; they are review rules agents apply when creating or editing Intent. Common smells: @@ -232,49 +232,49 @@ Common smells: | Open questions contain resolved answers | Move the answer to its owner and remove the question. | | Roadmap constrains current implementation | Promote it to requirements/spec or mark it non-normative. | | Delta is stale, vague, or completed | Update or delete the delta. | -| Generic `README.md` is used as VRS entry point | Use `intuition.md`. | +| Generic `README.md` is used as Intent entry point | Use `intuition.md`. | | Companion directories exist empty | Delete them until they contain real content. | -| One requirements file exceeds the size bound | Split into child VRS nodes. | +| One requirements file exceeds the size bound | Split into child Intent nodes. | -## Grill VRS +## Grill Intent -`grill-vrs` is the Socratic interview/update procedure that applies the VRS +`grill-intent` is the Socratic interview/update procedure that applies the Intent contract. -VRS owns the artifacts, lifecycle, and correctness contract. `grill-vrs` owns +Intent owns the artifacts, lifecycle, and correctness contract. `grill-intent` owns the conversation procedure: ask one question at a time, challenge fuzzy terms, validate assumptions, compare against code and references, and update the -correct VRS artifact as understanding crystallizes. +correct Intent artifact as understanding crystallizes. The procedure must not duplicate detailed artifact rules that live in -`context/vrs/`; it should point to the meta-VRS contract and stay focused on how +`intent/`; it should point to the root Intent contract and stay focused on how to conduct the interview. -Ontology handling is part of `grill-vrs`, not a separate skill by default. -When fuzzy, conflicting, or overloaded domain language appears, `grill-vrs` +Ontology handling is part of `grill-intent`, not a separate skill by default. +When fuzzy, conflicting, or overloaded domain language appears, `grill-intent` resolves the term with the user or available evidence and updates `ontology.md` -using the meta-VRS ontology contract. +using the root Intent ontology contract. ## Evaluation -VRS and VRS skills are evaluated through isolated scenario runs. An eval creates -a small but non-trivial temporary VRS tree outside tracked project files, applies -the meta-VRS contract and `grill-vrs` procedure, then reports: +Intent and Intent skills are evaluated through isolated scenario runs. An eval creates +a small but non-trivial temporary Intent tree outside tracked project files, applies +the root Intent contract and `grill-intent` procedure, then reports: - whether artifact routing was clear; - whether assumptions, constraints, decisions, ontology terms, open questions, references, experiments, roadmap, and deltas were distinguishable; - whether decision evidence/options/tradeoffs were practical; -- whether the skill duplicated, contradicted, or failed to apply the meta-VRS; +- whether the skill duplicated, contradicted, or failed to apply the root Intent contract; - what contract gaps should become open questions, deltas, decisions, or spec changes. -Eval artifacts are evidence. Persist durable findings into the owning VRS +Eval artifacts are evidence. Persist durable findings into the owning Intent artifact; do not treat the temporary scenario tree itself as normative. ## Enforcement -VRS enforcement checks real repository VRS artifacts for hygiene and contract +Intent enforcement checks real repository Intent artifacts for hygiene and contract violations. It is intentionally narrower than "tooling": enforcement owns check layers, diagnostics, and gate semantics, while artifact semantics stay with the file-kind and concept nodes that define them. diff --git a/intent/vision.md b/intent/vision.md index 638caf0..82a76c6 100644 --- a/intent/vision.md +++ b/intent/vision.md @@ -1,8 +1,8 @@ -# VRS — Vision +# Intent — Vision ## The Need -VRS exists because durable system knowledge needs a home that is more precise +Intent exists because durable system knowledge needs a home that is more precise than prose notes and less procedural than an agent skill. The documentation system must help humans and agents preserve intent, constraints, tradeoffs, and implementation shape without confusing those artifacts with plans or temporary @@ -10,33 +10,33 @@ working state. ## The Vision -- VRS is a self-describing documentation contract: the VRS system is itself - specified with VRS. -- VRS is the project's intent layer: durable, structured intent that constrains +- Intent is a self-describing documentation contract: the Intent system is itself + specified with Intent. +- Intent is the project's intent layer: durable, structured intent that constrains code, plans, skills, and agent behavior without replacing implementation truth. -- VRS documents are small, composable, and hierarchical enough that each file +- Intent documents are small, composable, and hierarchical enough that each file has one job. -- VRS separates normative system truth from supporting evidence, references, +- Intent separates normative system truth from supporting evidence, references, open questions, and PR-local scaffolding. -- VRS gives coding agents a precise contract for where to record discoveries +- Intent gives coding agents a precise contract for where to record discoveries while keeping main-branch documentation clean and durable. ## What This Is Not -- VRS is not a project plan, milestone tracker, or backlog. -- VRS is not a replacement for implementation-owned source code. -- VRS is not a generic README convention. -- VRS is not limited to architecture; it also covers product, operational, +- Intent is not a project plan, milestone tracker, or backlog. +- Intent is not a replacement for implementation-owned source code. +- Intent is not a generic README convention. +- Intent is not limited to architecture; it also covers product, operational, data, interface, and validation decisions when they shape a system. ## Success Criteria -1. A reader can determine which VRS artifact owns a fact without relying on +1. A reader can determine which Intent artifact owns a fact without relying on agent-specific skill text. -2. A VRS tree can scale from one small topic to a hierarchy of child nodes +2. An Intent tree can scale from one small topic to a hierarchy of child nodes without duplicating upstream intent. 3. Proposed decisions, experiments, references, and deltas have clear lifecycles and do not pollute the durable contract. -4. Operational skills such as `vrs.md` and `grill-vrs` can become thin - procedures over the normative `context/vrs/` contract. +4. Operational skills such as `intent.md` and `grill-intent` can become thin + procedures over the normative `intent/` contract. diff --git a/skills/intent.md b/skills/intent.md index c206779..749f193 100644 --- a/skills/intent.md +++ b/skills/intent.md @@ -49,15 +49,16 @@ claim is wrong far more often than it is checked. The checker is deterministic and consumer-agnostic: `intent/16-enforcement/` specifies the rules so that any tool can implement them, and the shipped binary is one such tool rather than the definition. Diagnostics carry a stable -`VRS.ENF.` code, so a finding maps back to the rule that produced it — +`INTENT.ENF.` code, so a finding maps back to the rule that produced it — match on the code, never on the message text. -**Expect `axe`- and `vrs`-flavoured identifiers out of an `intent` binary.** -Rule IDs (`AXE.VRS-R*`) and JSON `schema_version` values (`axe.vrs.check.v1`) -carry earlier names. That is deliberate, not a packaging bug: identifiers are -what external references and differential comparisons are keyed on, so they are -held stable and renamed in one coordinated pass rather than drifting per -release. Key your tooling on them as they are. +**Treat identifier namespaces as public contracts.** CLI requirement IDs use +`AXE.INTENT-R*`, checker rules use `INTENT.ENF.*`, and JSON +schema versions use values such as `axe.intent.check.v1`. The `axe` component +is a stable protocol/document namespace; `intent` names the layer, artifact +system, and executable command. +These identifiers changed together during the Intent-wide rename and have no +compatibility aliases, so downstream tooling must match the current values. Run `--help` for the authoritative surface; the commands and what each answers: