Roo4L · Roo4L · May 11, 2026 · May 10, 2026 · May 10, 2026 · May 10, 2026
diff --git a/.planning/STATE.md b/.planning/STATE.md
diff --git a/...ng/quick/260510-n7e-remove-gsd-artifacts-from-help-and-proje/260510-n7e-PLAN.md b/...ng/quick/260510-n7e-remove-gsd-artifacts-from-help-and-proje/260510-n7e-PLAN.md
diff --git a/...quick/260510-n7e-remove-gsd-artifacts-from-help-and-proje/260510-n7e-SUMMARY.md b/...quick/260510-n7e-remove-gsd-artifacts-from-help-and-proje/260510-n7e-SUMMARY.md
@@ -0,0 +1,152 @@
+---
+status: complete
+quick_id: 260510-n7e
+date: 2026-05-10
+ticket: AL-33
+tags: [docs, claude-md, review-loop, external-audience]
+---
+
+# 260510-n7e: Remove GSD artifacts from help and project documentation
+
+Two-task quick scrub: strip internal-vocabulary leaks from externally-facing
+artifacts (Task 1), then wire the existing `external-audience-auditor` agent
+into the project review-loop dispatch table so future regressions are caught
+automatically (Task 2).
+
+## Commits
+
+| Task | Commit    | Title                                                              |
+| ---- | --------- | ------------------------------------------------------------------ |
+| 1    | `a161cf6` | chore(docs): scrub internal-vocabulary leaks from user-facing surfaces (AL-33) |
+| 2    | `bb8f02f` | chore(claude): wire external-audience-auditor into review-loop dispatch (AL-33) |
+
+## Task 1 — files modified
+
+- `README.md` — drop `AGT-02` token; drop `.planning/REQUIREMENTS.md` link;
+  contextualize bare `ADR-006` reference with the named decision-record link.
+- `CONTRIBUTING.md` — drop `BHV/RT/AGT/CLI/CAT/INST/HRN/TST/DOC-XX` requirement
+  ID list from the PR-guidance step; rephrase "cites the relevant requirement
+  ID" to "names the behavior it pins".
+- `docs/STABILITY-MODEL.md` — replace bare `ADR-011` TL;DR token with a
+  one-breath substance + decision-record link; drop `AGT-02`, `TST-08`,
+  `Phase 6`, `ADR-012` tokens; clean up bare `ADR-NNN` prefixes in the Related
+  list (the link text already carries the substance).
+- `docs/README.md` — drop "GSD workflow state" lede phrasing (internal harness
+  vocabulary); drop "ADR-001..ADR-010 seeded in Phase 1" sentence; rephrase
+  HARNESS.md section descriptors from §-numbers to plain prose.
+- `docs/internals/playwright.md` — contextualize bare `ADR-012` reference with
+  a named decision-record link.
+- `plugin/cli/src/index.ts` — drop `(CLI-06)` from `agentlinux upgrade` and
+  `(CLI-07)` from `agentlinux pin` Commander descriptions (these surface in
+  user-visible `--help` output).
+
+## Task 2 — files modified
+
+- `CLAUDE.md` — added a new dispatch row to "Review Loop" §"Reviewers applied
+  by file type" for externally-facing artifacts (top-level README,
+  CONTRIBUTING, docs/internals/, docs/HARNESS.md, docs/STABILITY-MODEL.md,
+  docs/README.md, public release notes, blog/email drafts, agentlinux.org
+  copy, user-visible packaging strings) → also `external-audience-auditor`,
+  in addition to the per-file-type reviewers above. Skip-list documented
+  inline (`.planning/`, `docs/decisions/`, `docs/audits/`, `docs/research/`,
+  `.claude/`, source under `plugin/`/`packaging/`/`tests/`).
+
+## Leak categories found and substitutions applied
+
+1. **Bare requirement IDs** (`AGT-02`, `TST-08`, `CLI-06`, `CLI-07`, the
+   `BHV/RT/AGT/CLI/CAT/INST/HRN/TST/DOC-XX` enumeration). Substitute: drop the
+   token and restate the behavior in prose ("the self-update-without-sudo
+   invariant"; "the release-gate test"; "Reconcile installed versions against
+   the curated catalog").
+2. **Bare ADR cross-references** (`ADR-006`, `ADR-011`, `ADR-012`).
+   Substitute: cite both the substance and the decision-record file in one
+   breath, or replace with a named link without the numeric prefix.
+3. **GSD harness vocabulary** ("`.planning/` holds GSD workflow state").
+   Substitute: drop the GSD-flavoring; describe the directory's purpose
+   neutrally.
+4. **Phase numbering** (`Phase 1`, `Phase 6`). Substitute: drop the label;
+   keep the substance ("the release-gate test").
+5. **Internal workspace paths** in user-facing prose
+   (`.planning/REQUIREMENTS.md` link from README). Substitute: delete — the
+   internal contract is not a user-facing surface.
+
+## Kept on purpose
+
+- Catalog agent name `gsd` and the npm package `get-shit-done-cc` — these are
+  the public installable identifiers users type at the CLI.
+- "GSD workflow CLI for Claude Code" inside catalog example output and the
+  catalog.json description string — that's the user-visible product
+  description that ships in the catalog.
+- Source-comment references inside `plugin/`, `packaging/`, `tests/` —
+  out of scope per the external-audience-auditor (only user-visible *strings*
+  under packaging/ are audited, not source comments).
+- ADR cross-references inside `docs/decisions/` — internal-only by audit
+  scope (ADR-to-ADR cross-refs are appropriate within the decision tree).
+- `Co-Authored-By: Claude Opus 4.7 ...` in commit messages — project
+  convention, and commit messages are not user-visible per the plan's scope
+  partition (the auditor flags this trailer only in user-visible artifacts
+  like blog posts or website copy).
+
+## Out-of-scope deferrals
+
+- `docs/HARNESS.md` is referenced from README.md and matches the auditor's
+  externally-facing scope, but it is primarily contributor-harness
+  documentation written for people coming into the workspace. Its full
+  internal-vocabulary load (Phase numbering, ADR-NN cross-refs, requirement
+  ID enumeration) is structurally part of what the document explains. A
+  separate quick task is the right vehicle for that scrub; conflating it
+  here would have made this commit too large to review cleanly.
+- Source comments in `plugin/`, `packaging/`, `tests/` carry phase/plan/req
+  vocabulary heavily. These are explicitly out of audit scope per the
+  `external-audience-auditor` Rule 1 ("Audit only externally-facing
+  artifacts").
+
+## Reviewer findings
+
+The Task tool for spawning subagents was not available in this executor
+environment, so the review loop was performed inline against each reviewer's
+lens. All concerns either passed or are documented as out-of-scope above.
+
+- **node-engineer** (plugin/cli/src/index.ts): help-text-only edit; no API,
+  parsing, or behavior change. PASS.
+- **security-engineer** (plugin/cli/src/index.ts): no impact on `preAction`
+  EUID guard or input validation. PASS.
+- **qa-engineer**: verified no bats test asserts the literal `(CLI-06)` or
+  `(CLI-07)` substring against `--help` output (test descriptions name the
+  IDs for traceability, but bodies assert behavior — exit codes, sentinel
+  state, presence of agent name in upgrade table). PASS.
+- **ai-deslop**: substitutions are tighter than originals; word count went
+  down. PASS.
+- **dev-docs-auditor**: index.ts change is help-text only — no behavior
+  change, so docs/internals/registry-cli.md does not need updating. PASS.
+- **technical-writer**: each substitution preserves the original sentence's
+  meaning while removing unresolvable IDs. The CONTRIBUTING.md substitution
+  is *more* actionable for external contributors. PASS.
+- **fact-checker**: substantive claims unchanged. "Release-gate test",
+  "curated-combo", "agent user's NOPASSWD sudo drop-in" all factually
+  accurate. PASS.
+- **external-audience-auditor** (sanity check): re-ran the leak grep on the
+  post-fix tree against the in-scope file set. Zero hard-fail matches. PASS.
+
+## Verification
+
+Final grep against the in-scope externally-facing files for the canonical
+hard-fail leak taxonomy:
+
+```
+grep -E '(AL-[0-9]+|\.planning/|BHV-[0-9]+|RT-[0-9]+|AGT-[0-9]+|CLI-[0-9]+|CAT-[0-9]+|INST-[0-9]+|HRN-[0-9]+|TST-[0-9]+|DOC-[0-9]+|gsd-executor|gsd-planner|gsd-sdk|smart discuss|the orchestrator|the executor|the planner|Plan [0-9]+-[0-9]+|\bPhase [0-9]+\b|ADR-[0-9]+)' \
+  README.md CONTRIBUTING.md docs/internals/*.md docs/STABILITY-MODEL.md docs/README.md
+# → 0 matches
+```
+
+The user-visible Commander help-text scan also confirms `(CLI-06)` and
+`(CLI-07)` no longer appear in `agentlinux upgrade --help` or
+`agentlinux pin --help` output.
+
+## Self-Check: PASSED
+
+- Task 1 commit `a161cf6` exists in `git log`. FOUND.
+- Task 2 commit `bb8f02f` exists in `git log`. FOUND.
+- All 7 modified files in Task 1 are tracked at the new content. FOUND.
+- CLAUDE.md has the new dispatch row at line 60+. FOUND.
+- Verify-block grep returns zero hard-fail matches. CONFIRMED.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -60,6 +60,20 @@ Reviewers applied by file type:
 - Catalog recipes → `catalog-auditor`, `security-engineer`, `ai-deslop`, `dev-docs-auditor`
 - Docs → `technical-writer`, `fact-checker`, `ai-deslop` (skip for ADRs and
   research summaries)
+- Externally-facing artifacts (top-level `README.md`, `CONTRIBUTING.md`,
+  `docs/internals/`, `docs/HARNESS.md`, `docs/STABILITY-MODEL.md`,
+  `docs/README.md`, release notes, blog/email drafts, `agentlinux.org` copy,
+  user-visible packaging strings) → also `external-audience-auditor`, in
+  addition to the per-file-type reviewers above
+
+`external-audience-auditor` flags internal vocabulary that leaks into copy a
+public-repo reader (or a blog/email/website excerpt) cannot resolve: AL Jira
+keys, GSD plan filenames, BHV/RT/AGT/CLI/CAT/INST/HRN/TST/DOC requirement IDs,
+Phase/Plan numbering, bare ADR cross-refs, GSD orchestrator/executor/planner
+vocabulary, Claude Code self-references. Skip for `.planning/`,
+`docs/decisions/`, `docs/audits/`, `docs/research/`, `.claude/`, and source
+comments under `plugin/`/`packaging/`/`tests/` (only user-visible *strings*
+under `packaging/` are in scope).
 
 `dev-docs-auditor` keeps `docs/internals/<component>.md` in sync when changes
 touch `plugin/bin/`, `plugin/lib/`, `plugin/provisioner/`, `plugin/cli/src/`,

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -24,14 +24,13 @@ behavior-test-driven — that shapes how we accept changes.
    that there is no reason to skip it.
 
 5. **Open a PR.** Reference the issue. Describe what behavior changed and
-   which `BHV-XX` / `RT-XX` / `AGT-XX` / `CLI-XX` / `CAT-XX` / `INST-XX` /
-   `HRN-XX` / `TST-XX` / `DOC-XX` requirements are touched.
+   which `tests/bats/*.bats` test files cover it.
 
 ## Behavior-test contract
 
 `tests/bats/*.bats` is the spec. Implementation may change freely as long as
 the suite stays green. PRs that change observable behavior should add or
-update a `@test` that cites the relevant requirement ID in its description.
+update a `@test` that names the behavior it pins.
 
 See [`docs/HARNESS.md`](docs/HARNESS.md) §3 (test harness layout), §4 (review
 loop), and §5 (skill convention).

diff --git a/README.md b/README.md
@@ -86,9 +86,10 @@ curated pin; when you want to run ahead of it, you can — `agentlinux upgrade`
 shows the 3-way divergence between installed, curated, and upstream latest,
 and `agentlinux pin` sets sticky overrides so power users are not re-nagged.
 
-AGT-02 remains a permission invariant: whether you stay on the curated pin or
-run `claude update` past it, AgentLinux's release-gate test verifies the
-self-update path succeeds with zero `EACCES` and zero `sudo` prompts.
+The self-update-without-sudo invariant is permanent: whether you stay on the
+curated pin or run `claude update` past it, AgentLinux's release-gate test
+verifies the self-update path succeeds with zero `EACCES` and zero `sudo`
+prompts.
 
 See [docs/STABILITY-MODEL.md](docs/STABILITY-MODEL.md) for the user-facing
 one-page summary and [docs/decisions/011-stability-first-version-pinning.md](docs/decisions/011-stability-first-version-pinning.md)
@@ -113,8 +114,7 @@ catalog's curated choice. Precedent: Homebrew's `brew pin`.
 - `curl` preinstalled (stock on all three releases)
 
 Not yet supported in v0.3.0: ARM64, Fedora/Alma/Rocky/Arch. Those are on the
-v0.4+ roadmap. See [.planning/REQUIREMENTS.md](.planning/REQUIREMENTS.md) for
-the full behavior contract.
+v0.4+ roadmap.
 
 ## Security
 
@@ -123,7 +123,8 @@ download (connection reset mid-transfer) yields a bash syntax error *before*
 any commands run — partial-download execution is not possible. The release
 tarball is fetched over HTTPS and verified against a sibling `.sha256` asset
 published on the same GitHub Release before extraction. GPG signatures are
-on the v0.4+ roadmap (ADR-006); v0.3.0's trust story is HTTPS + SHA256 +
+on the v0.4+ roadmap — see [`docs/decisions/006-curl-pipe-bash-plus-deb.md`](docs/decisions/006-curl-pipe-bash-plus-deb.md)
+for the distribution decision; v0.3.0's trust story is HTTPS + SHA256 +
 maintainer 2FA + branch protection.
 
 Report vulnerabilities via the repository's Security tab (coordinated

diff --git a/docs/README.md b/docs/README.md
@@ -1,17 +1,16 @@
 # AgentLinux Documentation
 
-This directory holds all reference documentation. `.planning/` holds GSD workflow
-state (plans, STATE.md, config) — not documentation. If the output of a task is
+This directory holds all reference documentation. If the output of a task is
 a document intended to be read later (ADR, research report, design proposal,
 review summary), it goes here.
 
 ## Layout
 
-- `HARNESS.md` — authoritative project harness spec (§1 layout, §2 docs,
-  §3 systems access, §4 review loop, §5 skills, §6 CLAUDE.md, §7 checklist,
-  §8 success criteria).
-- `decisions/` — Architecture Decision Records (ADRs). ADR-001..ADR-010 seeded
-  in Phase 1 per `HARNESS.md` §2.3. New ADRs land as decisions resolve.
+- `HARNESS.md` — authoritative project harness spec (project layout,
+  documentation routing, systems-access inventory, review loop, skills,
+  contributor checklist).
+- `decisions/` — Architecture Decision Records (ADRs). New ADRs land as
+  decisions resolve.
 - `research/v0.3.0/` — v0.3.0 research outputs (STACK, FEATURES, ARCHITECTURE,
   PITFALLS, SUMMARY).
 - `research/v0.2.0/` — archived v0.2.0 research (carry-forward reference).

diff --git a/docs/STABILITY-MODEL.md b/docs/STABILITY-MODEL.md
@@ -1,6 +1,7 @@
 # AgentLinux Stability Model
 
-> The TL;DR of [ADR-011](decisions/011-stability-first-version-pinning.md).
+> The user-facing summary of AgentLinux's curated-combo version pinning —
+> the full decision record is at [`decisions/011-stability-first-version-pinning.md`](decisions/011-stability-first-version-pinning.md).
 
 AgentLinux ships *curated combos*: every catalog agent is pinned to an exact
 version that we test together end-to-end before each release. You install one
@@ -22,11 +23,11 @@ v0.3.0 pins:
 - `gsd` (`get-shit-done-cc`) — **1.37.1** (npm global into the agent's
   per-user prefix)
 - `playwright` — **1.59.1** (npm global + `playwright install --with-deps
-  chromium`; apt-layer runs via ADR-012 NOPASSWD sudo drop-in)
+  chromium`; apt-layer runs via the agent user's NOPASSWD sudo drop-in)
 
-The Phase 6 release-gate (`TST-08`) installs the full pinned combo on a clean
-Ubuntu host and runs the agent bats suite before the tag can publish. A red
-combo cannot ship.
+The release-gate test installs the full pinned combo on a clean Ubuntu host
+and runs the agent bats suite before the tag can publish. A red combo cannot
+ship.
 
 ## The three divergence states
 
@@ -50,8 +51,8 @@ Outcomes:
 ## Worked example: "I ran `claude update`"
 
 The canonical path. Claude Code ships with its own self-updater that writes
-into the agent-owned install tree — that is the whole point of AgentLinux
-(AGT-02). After `claude update`, the curated pin and the installed version
+into the agent-owned install tree — that is the whole point of AgentLinux.
+After `claude update`, the curated pin and the installed version
 disagree; `agentlinux upgrade` surfaces the diff rather than silently
 overwriting your choice:
 
@@ -116,9 +117,9 @@ behind is supported (`pin =<semver>`); reconciling is one command
 
 ## Related
 
-- [ADR-011 — Stability-first version pinning with explicit reconciliation](decisions/011-stability-first-version-pinning.md)
+- [Stability-first version pinning with explicit reconciliation](decisions/011-stability-first-version-pinning.md)
   — the full decision record, including considered alternatives (private
   apt/dpkg repo, Nix-style symlink profiles, thin-wrapper baseline).
-- [ADR-006 — curl-pipe-bash primary + optional .deb distribution](decisions/006-curl-pipe-bash-plus-deb.md)
+- [curl-pipe-bash primary + optional .deb distribution](decisions/006-curl-pipe-bash-plus-deb.md)
   — how the release tarball + catalog snapshot + SHA256 sidecar get to users.
 - [README.md](../README.md) — the top-level install + verify story.
diff --git a/docs/internals/playwright.md b/docs/internals/playwright.md
@@ -53,9 +53,9 @@ skill into `~/.claude/skills/playwright-cli/` — which is what makes the
 agent's `/playwright-cli` slash commands surface inside Claude Code.
 Apt-layer browser deps that the bootstrapper's underlying Playwright
 runtime needs install via the upstream sudo-prepended path; the agent
-user's NOPASSWD sudo drop-in (`/etc/sudoers.d/agentlinux`,
-[ADR-012](../decisions/012-agent-user-full-sudo.md)) is what makes that
-step run cleanly without prompting. After install, a sanity check asserts
+user's NOPASSWD sudo drop-in (`/etc/sudoers.d/agentlinux` — see
+[the agent-user-full-sudo decision record](../decisions/012-agent-user-full-sudo.md))
+is what makes that step run cleanly without prompting. After install, a sanity check asserts
 the skill directory landed where Claude Code looks for it; a missing
 directory fails the install rather than silently writing a sentinel for
 a half-bootstrapped state.

diff --git a/plugin/cli/src/index.ts b/plugin/cli/src/index.ts
@@ -79,7 +79,7 @@ program
 
 program
   .command("upgrade")
-  .description("Reconcile installed versions against the curated catalog (CLI-06)")
+  .description("Reconcile installed versions against the curated catalog")
   .option("--reset-all-curated", "accept curated versions for all agents; clear overrides")
   .option("--respect-overrides", "install curated only for non-overridden agents")
   .option("--all-latest", "install npm latest for all (implies --check-upstream)")
@@ -91,7 +91,7 @@ program
 
 program
   .command("pin <spec>")
-  .description("Set sticky override: <name>=curated|latest|x.y.z (CLI-07)")
+  .description("Set sticky override: <name>=curated|latest|x.y.z")
   .action(async (spec: string, opts) => {
     await pinCmd(spec, opts);
   });