release: v3.4.18 — the architecture knowledge base regenerated off HEAD (/v:onboard --refresh): 191/191 citations resolve, 36 stale entries down to the structural floor

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: copeus

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers-v",
       "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert + Context7 library validator), disjoint partitioning, manifest-driven multi-backend dispatch (Claude + Codex + Antigravity + Cursor), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode, research-grounded brainstorming (gated pre-brainstorm recon + batched elicitation), V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall→action bridge), and batched parallel dispatch (Opus default, narrow Sonnet exception)",
-      "version": "3.4.17",
+      "version": "3.4.18",
       "source": "./",
       "author": {
         "name": "Oleg",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-v",
   "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert advisor + library/doc validator — Context7 MCP when the session has it attached, WebSearch/WebFetch otherwise), disjoint file partitioning, manifest-driven multi-backend dispatch (Claude + headless Codex + Antigravity + Cursor workers), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode for multi-feature builds, V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall→action bridge), and batched parallel dispatch (Opus default, Sonnet for narrow junior-task carve-out), plus /v:onboard — a project-onboarding command that builds a citation-verified knowledge base + AGENTS.md/CLAUDE.md bridge behind a human gate. Auto-intercepts three transitions: brainstorming → writing-plans → execution; a gated pre-brainstorm recon pass and batched elicitation are guidance the brainstorm follows, not enforced mechanisms.",
-  "version": "3.4.17",
+  "version": "3.4.18",
   "author": {
     "name": "Oleg",
     "email": "copeus@gmail.com"

CHANGELOG.md

@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [3.4.18] - 2026-09-04
+
+`/v:onboard --refresh` on the architecture knowledge base, which had not been regenerated since 2026-07-14
+(v2.6) and was flagged stale on every session banner since.
+
+### Changed — docs regenerated off HEAD, citation-verified
+
+- `docs/superpowers/architecture/{architecture,business-logic,tech-context}.md` and `CONVENTIONS.md`
+  rewritten against v3.4.17: Engine C (emit → per-wave pipeline, Implement/Gate/Record, the six
+  subcommands), the lane guard and its fail-open contract, Stage −1 triage on `UserPromptSubmit`, the
+  integration authority, `resume-prepare`, measured usage including the Engine C transcript mode,
+  `global_constraints`/`interfaces`, the backend-maturity ladder; claims about mechanisms removed in
+  3.4.0–3.4.16 (epic watcher, headless shim, Devin, the v2.11 "self-resurrecting" loop) deleted.
+  191/191 `file:line` citations resolve; staleness is down from 36 entries to the one structural
+  `uncited-new-file` floor the checker always reports for a cited directory with uncited siblings.
+- CONVENTIONS.md records only rules the repo actually states or enforces (each cited). Two 3.4-era process
+  rules — no checkout writes while a direct-mode job is registered, and double-quoted YAML job bodies —
+  live only in CHANGELOG prose and are grounded here on `state-machine.md` and the example manifest;
+  the 120-column rule is not recorded because nothing in the repo enforces it.
+
 ## [3.4.17] - 2026-09-04
 
 The Superpowers-integration audit (3.4.16, audit §7) closed. Checked against the installed Superpowers

CONVENTIONS.md

@@ -1,5 +1,5 @@
 <!--
-generated by /v:onboard from cited evidence on 2026-06-30; refresh with /v:onboard --refresh
+generated by /v:onboard from cited evidence on 2026-09-04; refresh with /v:onboard --refresh
 provenance: docs/superpowers/architecture/.onboard-manifest.json
 NOTE: generated. These are the conventions that differ from competent-developer defaults; each is
 cited to the evidence (a config, CI gate, or lint rule) it was derived from — not the model's prior.
@@ -12,41 +12,110 @@ Deltas from default practice that this repo actually enforces.
 ## Python: stdlib only
 
 - Write helper scripts in **pure Python standard library** — no third-party runtime deps. The scope
-  gate is "Python 3.9-safe, stdlib only. Targets stock-macOS python3 3.9.6." (`scripts/compound-v-scope-check.py:98`)
-- Ship a built-in **`--selftest`** that runs offline (builds throwaway git repos in `$TMPDIR`). (`scripts/compound-v-scope-check.py:514-516`, `scripts/compound-v-onboard.py:1185-1186`) CI runs the
-  epic-state / epic-arbiter self-tests under a **Python 3.9 floor**, then every other script's
-  `--selftest` on the same interpreter. (`.github/workflows/validate.yml:269-282`)
+  gate is "Python 3.9-safe, stdlib only. Targets stock-macOS python3 3.9.6." (`scripts/compound-v-scope-check.py:141`);
+  the `/v:onboard` toolkit says the same in its docstring. (`scripts/compound-v-onboard.py:1-2`)
+- Ship a built-in **`--selftest`** that runs offline (builds throwaway git repos in `$TMPDIR`).
+  (`scripts/compound-v-scope-check.py:626-683`, `scripts/compound-v-onboard.py:1184-1186`)
+  CI runs the epic-state / epic-arbiter self-tests first under a clean **Python 3.9** to prove they
+  stay dependency-free (`.github/workflows/validate.yml:285-289`), then sweeps **every** `scripts/*.py`
+  that mentions `--selftest` — discovery is dynamic, so a new script is picked up automatically.
+  (`.github/workflows/validate.yml:298-312`)
 - Reuse canonical shared constants instead of forking a second copy (e.g. secret-pattern families are
   imported from `compound-v-memory.py`, not redefined). (`scripts/compound-v-onboard.py:5-9`)
 
+## Tests live under `tests/`, and the sweep must never match zero
+
+- The selftest sweep globs `scripts/*.py` **only**; everything under `tests/` is executed by a
+  separate job. A test script parked in `scripts/` is therefore a test CI never runs.
+  (`.github/workflows/validate.yml:314-315`)
+- That job **always runs** — no `paths:` filter and no `if:` guard, because GitHub reports a
+  conditionally-skipped required check as `Success` — discovers `.sh` and `.py` recursively, and
+  **fails when it discovers nothing**: a guard that silently matches zero files is a false green.
+  (`.github/workflows/validate.yml:317-374`)
+
 ## Markdown frontmatter
 
-- Every skill (`skills/*/SKILL.md`) and agent (`agents/*.md`) needs `name` and `description`
-  frontmatter; commands are exempt (name = filename). (`scripts/lint-frontmatter.py:110-115`)
+- Frontmatter is a **path-class presence gate**: `agents/*.md`, `commands/*.md` and
+  `skills/*/SKILL.md` must carry a block; every other `.md` is exempt. Required `name` and
+  `description` (commands exempt from `name` — it is the filename). (`scripts/lint-frontmatter.py:8-20`)
 - Keep `description` ≤ 500 chars (soft) and total frontmatter ≤ 1024 chars (hard). (`scripts/lint-frontmatter.py:33-34`)
-- Quote any `paths` value containing glob chars (`{}[]`) — unquoted globs break YAML. (`scripts/lint-frontmatter.py:137-142`)
+- `maxTurns`, when present, must be a **positive integer** — a string, float or negative is ignored by
+  the runtime, so the agent runs uncapped while its file claims a cap. (`scripts/lint-frontmatter.py:161-170`)
+- Quote any `paths` value containing glob chars (`{}[]`) — unquoted globs break YAML.
+  (`scripts/lint-frontmatter.py:172-177`)
 
 ## Model policy — NEVER Haiku
 
-- **Opus by default**, Sonnet only for the narrow junior-task carve-out; **Haiku is forbidden.** The
-  frontmatter linter rejects any `model:` containing `haiku` (`scripts/lint-frontmatter.py:124-126`)
-  and additionally requires `model: opus` on every `agents/*.md`. (`scripts/lint-frontmatter.py:128-134`)
-  CI enforces the no-Haiku rule on agent files too. (`.github/workflows/validate.yml:92-97`)
-- Execution-layer model values (`gpt-5.5`, etc.) are NEVER placed in any frontmatter — they live only
-  in the manifest/job_spec. (`skills/backend-launcher/SKILL.md:37`)
+- **Opus by default.** The frontmatter linter rejects any `model:` containing `haiku`
+  (`scripts/lint-frontmatter.py:133-136`)
+  and requires `model: opus` on every `agents/*.md`. (`scripts/lint-frontmatter.py:151-159`) CI enforces
+  the no-Haiku rule on agent files independently of the linter. (`.github/workflows/validate.yml:83-97`)
+- **The one carve-out is named, not open.** `code-archaeologist` and `doc-validator` may carry
+  `model: sonnet` because their work is scanning — reading a repository, resolving a library — and
+  scanning is execution, not judgment. The allow-list is explicit and short on purpose.
+  (`scripts/lint-frontmatter.py:36-44`)
+- **Fable is never frontmatter.** It belongs to a business-critical *invocation*, set by the caller's
+  `model` override; a static `model: fable` would spend the top model on every routine pre-flight.
+  (`scripts/lint-frontmatter.py:147-150`)
+- Execution-layer model values (`gpt-5.6-sol`, etc.) are NEVER placed in any frontmatter — they live
+  only in the manifest/job_spec. (`skills/backend-launcher/SKILL.md:46`)
 
 ## No fabricated metrics (anti-ruflo)
 
 - Do not print token-cost / savings numbers you cannot measure. CI greps `scripts/` and `docs/` for
-  fabricated-metric phrasing (e.g. "tokens saved", "cost savings: N") and fails the build on a hit. (`.github/workflows/validate.yml:156-179`)
+  fabricated-metric phrasing (e.g. "tokens saved", "cost savings: N") and fails the build on a hit.
+  (`.github/workflows/validate.yml:185-214`)
 - No daemon, no MCP server, no external vector-DB service, no fabricated cost metrics — the anti-ruflo
-  charter. (`skills/compound-v/SKILL.md:44`)
+  charter. (`skills/compound-v/SKILL.md:46`)
+- Measurement that is absent stays absent: a missing or unparseable usage source yields
+  `measured:false` with null counts, never a substituted zero. (`scripts/compound-v-usage-extract.py:17-27`)
+
+## The test contract: a scope may never resolve to nothing
+
+- `test_scope: floor_only` requires a non-empty `floor_command`, and `test_scope: impacted` requires a
+  non-empty `full_command` — so no scope can resolve to running nothing. Overlapping `impacted_map`
+  `when` globs **union**; first-match-wins would silently drop declared coverage.
+  (`skills/compound-v/execution-manifest.md:581-591`)
+- A job's own run-dir bookkeeping is excluded before glob matching, so writing `state.json` can neither
+  match a `when` glob nor promote the job to the full suite as an "unmapped path".
+  (`skills/compound-v/execution-manifest.md:593-599`)
+- **Never write, anywhere, that the floor preserves pre-merge safety.** The floor is early feedback;
+  the merge-blocking CI run is what restores the full-suite guarantee.
+  (`skills/compound-v/execution-manifest.md:601-605`)
+
+## Shell scripts and hooks
+
+- Hooks under `hooks/*.sh` must be executable, and `shellcheck` runs over `hooks/*.sh` **and**
+  `scripts/compound-v-*.sh`. (`.github/workflows/validate.yml:216-230`)
+- Every hook registration carries `"shell": "bash"` — the documented optional field — so these bash
+  scripts are not handed to PowerShell on a Windows box with no Git Bash. (`hooks/hooks.json:2`)
+- A hook that can block the turn carries a `|| true` suffix in its registration, because a syntax
+  error is fatal before any in-script trap can run: the registration itself must neutralize it. (`hooks/hooks.json:3`)
+  The `PreToolUse` lane guard deliberately does **not**, because a non-zero `PreToolUse` exit is not a
+  deny; copying the idiom there would be cargo-culting. (`hooks/hooks.json:4`)
+
+## YAML in manifests
+
+- Write a multi-line job `body` as a **block scalar** (`body: |`) — the shape every job in the shipped
+  example uses, and the only one that keeps a paragraph's line breaks; a quoted flow scalar folds them
+  into one line. (`examples/manifest.example.yaml:64-68`)
+- The `body` (or one of its `description` / `prompt` / `spec` aliases) is **required**: a job with none
+  of them is refused at emit, because a prompt carrying lanes and no instructions asks the worker to
+  invent the task — and an invented task that stays inside its lane passes every gate here.
+  (`skills/compound-v/execution-manifest.md:58`)
 
 ## Doc placement
 
 - Generated/working docs live under `docs/superpowers/**` in a flat, predictable layout
-  (`recon/`, `archaeology/`, `expert/`, `library-audit/`, `execution/<run-id>/`, `memory/`, `specs/`, `plans/`). (`skills/compound-v/SKILL.md:197-225`)
-- Onboarding output goes to `docs/superpowers/architecture/*` + root `CONVENTIONS.md`/`AGENTS.md`/`CLAUDE.md`. (`skills/compound-v/onboarding.md:9-13`)
+  (`recon/`, `archaeology/`, `expert/`, `library-audit/`, `execution/<run-id>/`, `memory/`, `specs/`, `plans/`).
+  (`skills/compound-v/SKILL.md:199-227`)
+- Onboarding output goes to `docs/superpowers/architecture/*` + root `CONVENTIONS.md`/`AGENTS.md`/`CLAUDE.md`.
+  (`skills/compound-v/onboarding.md:9-13`)
+- Every committed run directory must carry a **committed `state.json`**; CI fails on a manifest with
+  no state beside it, and the historical gaps are allowlisted by id rather than back-filled, because a
+  reconstructed audit trail is fabricated evidence, not a repair. (`.github/workflows/validate.yml:136-159`)
+- Every intra-repo markdown link must resolve; the dead-link scan runs **last** in the job so
+  cross-refs to files authored by later batches resolve at integration time. (`.github/workflows/validate.yml:232-274`)
 
 ## cclint scope
 
@@ -56,4 +125,15 @@ Deltas from default practice that this repo actually enforces.
 
 ## Versioning
 
-- `plugin.json` and `marketplace.json` versions must match exactly; CI fails on drift. (`.github/workflows/validate.yml:43-52`)
+- `plugin.json` and `marketplace.json` versions must match exactly; CI fails on drift.
+  (`.github/workflows/validate.yml:43-52`)
+- The top release heading in `CHANGELOG.md` must match `plugin.json`'s version — the guard parses the
+  first `## [x.y.z]` heading outside fenced code blocks. (`.github/workflows/validate.yml:54-81`)
+
+## Writing in the shared checkout during a run (not machine-enforced)
+
+- While a `direct`-mode job is registered in a run's `lane-map.json`, treat the shared checkout as
+  that job's lane: an out-of-lane write there lands in the job's git-derived changed set and BLOCKS
+  it. The `PreToolUse` guard is only a floor — it fails open on anything it cannot resolve, including
+  a write made by an interpreter one-liner, so nothing mechanical catches this one.
+  (`skills/compound-v/state-machine.md:166`, `hooks/lane-guard.sh:17-23`, `hooks/lane-guard.sh:32-58`)