From 2ab32fc9dda3b272378bef2056c988ec937cdc18 Mon Sep 17 00:00:00 2001 From: gus Date: Mon, 11 May 2026 10:33:28 -0300 Subject: [PATCH] docs: align AI-facing discovery surfaces after architecture vNext The 2026-05-11 architecture retest confirmed Architecture vNext is functionally closed on main (PRs #209-#215) but found three P2 documentation drifts that this follow-up resolves. Finding 1: AI-facing surfaces pointed at a non-existent reference/telemetry.md path. llms.txt and bin/about.sh now reference TELEMETRY.md, the canonical file the READMEs already linked to. Finding 2: AGENTS.md claimed to list every shipped skill but the table only had eight entries; the README sells 13. Grouped the table into three sections (default sprint / orchestration and safety / onboarding and entry points) and added compound, feature, nano-run, nano-help, and nano-doctor. Finding 3: README.md mentioned auto-saved artifacts and the resolver but did not reflect the Architecture vNext guarantees the retest just proved. Tightened three existing sections: - Artifacts now mentions the SHA-256 integrity field, --require-integrity for strict consumers, and the schema_legacy marker on --from-session legacy artifacts. - Resolver now mentions upstream_status (the four trust values) and the phase_context block that lets custom skills declare trust: strict, max_age_days, required vs optional upstreams, and tagged solution / diarization lookup. routing in the JSON output exposes what the resolver applied. - Write/Edit guard section now mentions the credential JSON basenames it blocks (credentials.json, secrets.json, service-account*.json, firebase-adminsdk*.json, google-credentials*.json, aws-credentials*.json) plus the safe-template exception (.env.example, credentials.example.json, service-account.template.json) and the case-insensitive match. Lint adds architecture-vnext-doc-locks with three steps: - Telemetry path is TELEMETRY.md, not reference/telemetry.md, and llms.txt + bin/about.sh both mention TELEMETRY.md. - AGENTS.md mentions compound, feature, nano-run, nano-help, and a doctor variant (nano-doctor, /doctor, or doctor/SKILL). - README.md mentions --require-integrity, phase_context, upstream_status, at least one credential JSON name, and at least one safe-template shape. Each lock was sabotage-tested (reintroduce the dead path / delete a required token / strip --require-integrity); all three caught the drift cleanly. No runtime behavior changes; all existing E2E suites remain green. Closes the three P2 doc findings from the 2026-05-11 Architecture vNext fresh retest spec. --- .github/workflows/lint.yml | 83 ++++++++++++++++++++++++++++++++++++++ AGENTS.md | 19 ++++++++- README.md | 8 +++- bin/about.sh | 2 +- llms.txt | 2 +- 5 files changed, 109 insertions(+), 5 deletions(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 12b7023..e75a085 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 75193da..35485ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/.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/.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 `/skills//`. 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. diff --git a/README.md b/README.md index 209c292..f4cf188 100644 --- a/README.md +++ b/README.md @@ -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? ``` diff --git a/bin/about.sh b/bin/about.sh index ddc03a2..388d038 100755 --- a/bin/about.sh +++ b/bin/about.sh @@ -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 diff --git a/llms.txt b/llms.txt index 6fe9688..59951c0 100644 --- a/llms.txt +++ b/llms.txt @@ -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