garagon · garagon · May 11, 2026 · May 11, 2026
@@ -3437,6 +3437,89 @@ jobs:
           fi
           echo "OK: guard concurrency tier uses the phase registry."
 
+  architecture-vnext-doc-locks:
+    name: Architecture vNext doc locks (telemetry path, AGENTS inventory, README accuracy)
+    runs-on: ubuntu-latest
+    # Three contracts the 2026-05-11 architecture retest asked for as
+    # a follow-up after Architecture vNext closed:
+    #   1. AI-facing surfaces must point at TELEMETRY.md, not the
+    #      non-existent reference/telemetry.md path.
+    #   2. AGENTS.md must list every built-in skill the README sells
+    #      so adapters using AGENTS.md as the inventory do not
+    #      under-discover the product (Option A: complete inventory).
+    #   3. README.md must mention the Architecture vNext guarantees
+    #      that were just proven: --require-integrity, phase_context
+    #      + upstream_status, credential JSON write parity, and the
+    #      safe-template exception.
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - name: Telemetry doc path is TELEMETRY.md, not reference/telemetry.md
+        run: |
+          set -e
+          if grep -nF 'reference/telemetry.md' \
+              llms.txt bin/about.sh AGENTS.md README.md README.es.md 2>/dev/null; then
+            echo "FAIL: an AI-facing surface still points at the non-existent reference/telemetry.md."
+            echo "      The canonical path is TELEMETRY.md."
+            exit 1
+          fi
+          for f in llms.txt bin/about.sh; do
+            if ! grep -qF 'TELEMETRY.md' "$f"; then
+              echo "FAIL: $f does not mention TELEMETRY.md after the path correction."
+              exit 1
+            fi
+          done
+          echo "OK: telemetry doc path is correct across AI-facing surfaces."
+      - name: AGENTS.md is a complete built-in skill inventory
+        run: |
+          set -e
+          fail=0
+          # Required tokens for the complete-inventory contract
+          # (Option A from the retest spec). nano-doctor is accepted
+          # in either of the two trigger spellings; the lock checks
+          # whichever shape lands.
+          for token in compound feature nano-run nano-help; do
+            if ! grep -qi -- "$token" AGENTS.md; then
+              echo "FAIL: AGENTS.md does not mention skill '$token'."
+              fail=1
+            fi
+          done
+          if ! grep -qiE 'nano-doctor|/doctor|doctor/SKILL' AGENTS.md; then
+            echo "FAIL: AGENTS.md does not mention the doctor skill."
+            fail=1
+          fi
+          exit $fail
+      - name: README reflects Architecture vNext guarantees
+        run: |
+          set -e
+          fail=0
+          # Strict trust + structured artifact contract
+          if ! grep -qF -- '--require-integrity' README.md; then
+            echo "FAIL: README.md does not mention --require-integrity (strict artifact trust)."
+            fail=1
+          fi
+          # Custom routing contract
+          if ! grep -qF 'phase_context' README.md; then
+            echo "FAIL: README.md does not mention phase_context (custom routing contract)."
+            fail=1
+          fi
+          if ! grep -qF 'upstream_status' README.md; then
+            echo "FAIL: README.md does not mention upstream_status (resolver trust output)."
+            fail=1
+          fi
+          # Secret-write parity: at least one credential JSON name
+          if ! grep -qiE 'credentials\.json|service-account|firebase-adminsdk' README.md; then
+            echo "FAIL: README.md does not mention credential JSON write protection."
+            fail=1
+          fi
+          # Safe-template exception: at least one template shape
+          if ! grep -qiE '\.env\.example|credentials\.example\.json' README.md; then
+            echo "FAIL: README.md does not mention the safe-template exception (.env.example / credentials.example.json)."
+            fail=1
+          fi
+          exit $fail
+
   ai-facing-docs-consistency:
     name: AI-facing docs agree on adapters, sprint, guard, privacy
     runs-on: ubuntu-latest

@@ -1,9 +1,11 @@
 # Nanostack: Agent Discovery
 
-This file lists the skills shipped by Nanostack for the verified adapters: Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI. Each skill folder contains a `SKILL.md` for adapter discovery and an `agents/openai.yaml` for OpenAI-compatible agents. Adapter capability evidence lives in `adapters/<host>.json`; treat the JSON as the single source of truth for what a given host actually enforces (hook execution, write guard, phase gate).
+This file lists every built-in skill shipped by Nanostack for the verified adapters: Claude Code, Cursor, OpenAI Codex, OpenCode, and Gemini CLI. Each skill folder contains a `SKILL.md` for adapter discovery and an `agents/openai.yaml` for OpenAI-compatible agents. Adapter capability evidence lives in `adapters/<host>.json`; treat the JSON as the single source of truth for what a given host actually enforces (hook execution, write guard, phase gate).
 
 ## Available skills
 
+### Default sprint
+
 | Skill | Directory | Description |
 |-------|-----------|-------------|
 | think | `think/` | Strategic product thinking with calibrated intensity per archetype. Saves a structured artifact (value proposition, scope mode, target user, narrowest wedge, key risk, premise validation). |
@@ -12,9 +14,24 @@ This file lists the skills shipped by Nanostack for the verified adapters: Claud
 | qa     | `qa/` | Browser, API, CLI, or debug testing. WTF heuristic. |
 | security | `security/` | OWASP Top 10 + STRIDE audit. Cross-references /review for conflicts. |
 | ship   | `ship/` | Pre-flight, PR creation, CI monitoring, post-deploy verification. Generates the sprint journal on success. |
+| compound | `compound/` | Knowledge capture after /ship. Promotes proven solutions across sprints (bug, pattern, decision) with confidence and applied_count. |
+
+### Orchestration and safety
+
+| Skill | Directory | Description |
+|-------|-----------|-------------|
 | guard  | `guard/` | Block and warn rules on Bash + Write/Edit. Phase concurrency, sprint phase gate, and budget gate run inside the same pipeline. Rule counts live in `guard/rules.json`. |
 | conductor | `conductor/` | Multi-agent sprint orchestrator. Parallel sessions via claim/complete protocol with atomic file locking. |
 
+### Onboarding and entry points
+
+| Skill | Directory | Description |
+|-------|-----------|-------------|
+| feature   | `feature/` | Fast sprint for an existing project. Skips /think, runs plan through ship. |
+| nano-run  | `start/` | First-run onboarding. Reads adapter capabilities, writes a setup artifact, configures permissions and stack preferences through a conversation. |
+| nano-help | `help/` | Quick reference for all built-in skills and the default sprint flow. |
+| nano-doctor | `doctor/` | Diagnostic. Reports the actual enforcement level for the running adapter and any drift between adapter declarations and the local install. |
+
 ## Custom workflow stacks
 
 Custom stacks declare their own phases in `.nanostack/config.json` (`custom_phases` + `phase_graph`) and live under `<store>/skills/<name>/`. They get the same lifecycle support as the built-in sprint (graph-aware progression, concurrency enforcement, artifact trust, schema validation, routing intent through `phase_context`). The contract is in `reference/custom-stack-contract.md`; `examples/custom-stack-template/compliance-release/` is a worked example.

@@ -459,7 +459,7 @@ Plus a Tier 7 of warn rules for operations that need attention but not blocking.
 
 ### Write and Edit are hooked too
 
-`Write`, `Edit`, and `MultiEdit` go through their own PreToolUse hook (`guard/bin/check-write.sh`) that denies a narrow list of paths: secret files (`.env` and variants, `*.pem`, `*.key`, SSH keys, shell history) and system or user-secret directories (`/etc`, `/var`, `/usr/bin`, `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.gcp`, `~/.kube`). Symlinks are resolved before matching so `mylink/config -> ~/.ssh/config` is treated as the resolved target. See [`SECURITY.md`](SECURITY.md) for the full denylist and the manual wire-up for installs that predate the hook.
+`Write`, `Edit`, and `MultiEdit` go through their own PreToolUse hook (`guard/bin/check-write.sh`) that denies a narrow list of paths: secret files (`.env` and variants, `*.pem`, `*.key`, SSH keys, shell history), credential JSON basenames (`credentials.json`, `secrets.json`, `service-account*.json`, `firebase-adminsdk*.json`, `google-credentials*.json`, `aws-credentials*.json`, plus the same-stem variants with environment or region suffixes), and system or user-secret directories (`/etc`, `/var`, `/usr/bin`, `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.gcp`, `~/.kube`). Safe templates (`.env.example`, `.env.sample`, `.env.template`, `credentials.example.json`, `service-account.template.json`, etc.) pass through so first-run onboarding does not fight the guard. Matching is case-insensitive and mirrors the read-side G-035 rule. Symlinks are resolved before matching so `mylink/config -> ~/.ssh/config` is treated as the resolved target. See [`SECURITY.md`](SECURITY.md) for the full denylist and the manual wire-up for installs that predate the hook.
 
 ### Deny-and-continue
 
@@ -628,12 +628,16 @@ A review artifact captures everything: findings, scope drift, conflicts resolved
 }
 ```
 
-Full schema in [`reference/artifact-schema.md`](reference/artifact-schema.md). To disable, set `auto_save: false` in `.nanostack/config.json`.
+Every artifact `bin/save-artifact.sh` writes carries a SHA-256 `integrity` field over the canonical JSON, so a downstream consumer can detect a tampered file. Strict consumers call `bin/find-artifact.sh --require-integrity` to also reject artifacts whose `.integrity` field is missing. The save path validates the structured shape per phase (see `bin/lib/artifact-schemas.sh`); the legacy `--from-session` form still works for manual recovery but writes `schema_legacy: true` so downstream tools know the artifact was reconstructed instead of produced by the structured flow.
+
+Full schema in [`reference/artifact-schema.md`](reference/artifact-schema.md). To disable auto-save, set `auto_save: false` in `.nanostack/config.json`.
 
 ### Skills read each other
 
 Every skill starts with one call to `bin/resolve.sh`, a centralized context resolver. It loads upstream artifacts, past solutions, conflict precedents, diarizations and project config in one JSON blob. Each phase has its own routing table: `/review` gets the plan artifact and solutions matched by file overlap with the current diff. `/security` gets the plan, review artifact (up to 30 days back) and conflict precedents. `/compound` gets all six phase artifacts.
 
+The resolver also exposes trust state to the caller. `upstream_status` per phase reports `verified`, `integrity_missing`, `integrity_mismatch`, or `missing`, so a release gate can tell a tampered artifact apart from a never-saved one. Custom skills can declare a `phase_context` block in `.nanostack/config.json` to ask the resolver for `trust: strict` (rejects integrity-missing upstreams), a per-phase `max_age_days`, required vs optional upstreams, and tagged solution / diarization lookup. The applied context comes back in `routing` so consumers see what the resolver did, not just what they asked for.
+
 `/review` checks scope drift: did you touch files outside the plan? Did you skip files that were in it?
 
 ```

@@ -81,7 +81,7 @@ All data in \`.nanostack/\`:
 - Briefs: \`.nanostack/know-how/briefs/\`
 - Audit log: \`.nanostack/audit.log\`
 
-There is no Nanostack cloud. Telemetry is opt-in and documented in \`reference/telemetry.md\`.
+There is no Nanostack cloud. Telemetry is opt-in and documented in \`TELEMETRY.md\`.
 
 ## This Project
 

@@ -41,7 +41,7 @@ Every artifact written by `bin/save-artifact.sh` carries a SHA-256 integrity fie
 
 ## Privacy
 
-There is no Nanostack cloud. Artifacts, journals, and analytics stay under `.nanostack/` on disk. Telemetry is opt-in and documented in `reference/telemetry.md`; the on-by-default behavior is no remote calls.
+There is no Nanostack cloud. Artifacts, journals, and analytics stay under `.nanostack/` on disk. Telemetry is opt-in and documented in `TELEMETRY.md`; the on-by-default behavior is no remote calls.
 
 ## Install