#62 Replace the brainstorming override with a vendor link and an AGENTS.md preference

.socraticodecontextartifacts.json

@@ -18,7 +18,7 @@
     {
       "name": "skills-doc",
       "path": "./docs/SKILLS.md",
-      "description": "The vendored agent skills: inventory, the brainstorming override, the daily refresh hook, provisioning a worktree."
+      "description": "The vendored agent skills: inventory, overrides, the daily refresh hook, provisioning a worktree."
     },
     {
       "name": "socraticode-doc",

.socraticodeignore

@@ -3,8 +3,8 @@
 # graph only, never the context artifacts (docs/SOCRATICODE.md).
 
 # Vendored gregoryfoster/skills and obra/superpowers. skills/ and .claude/skills/ are
-# symlinks into skills-vendor/, bar skills/brainstorming, an upstream copy with one
-# path changed (docs/SKILLS.md); .skills/ holds the installed doctor.sh. Unexcluded
+# symlinks into skills-vendor/, bar any upstream override (none since #62;
+# docs/SKILLS.md); .skills/ holds the installed doctor.sh. Unexcluded
 # they outnumber processor's own files, and every sibling's includeLinked search
 # would serve them as processor.
 skills-vendor/

AGENTS.md

@@ -14,6 +14,11 @@ Design of record: [docs/specs/2026-09-29-processor-service-design.md](docs/specs
 
 TDD required. Red → Green → Refactor. No production code without a failing test first. Non-trivial work gets a plan in `docs/plans/YYYY-MM-DD-<issue>-<slug>.md`, reviewed before implementation.
 
+**Brainstorming** (`skills/brainstorming`, superpowers' unmodified): these are the partner's preferences its *Where it goes* defers to.
+- A change to the service's behaviour amends the spec: a dated **Amended** entry in its header, plus the sections it touches. A design doc of its own only for work the spec doesn't cover: `docs/specs/YYYY-MM-DD-<issue>-<topic>-design.md`, never `docs/superpowers/specs/`.
+- `superpowers:<name>` means this repo's `skills/<name>`, whichever vendor it links. `superpowers:writing-plans` is gregoryfoster's `writing-plans`, which writes the plan above to `docs/plans/`; `superpowers:using-git-worktrees` is gregoryfoster's too (§ Conventions).
+- The builder check runs as written. On an amendment, hand it the spec and name the amended sections.
+
 ## Environment & Tooling
 
 Python 3.12, uv, hatchling src layout, pytest, ruff.
@@ -56,7 +61,7 @@ find-links locks by filename, not hash, so either source satisfies the same `uv.
 
 ## Agent Skills
 
-`gregoryfoster/skills` and `obra/superpowers` vendored under `skills-vendor/`, symlinked into `skills/` (agentskills.io) and `.claude/skills/` (Claude Code). Symlinks dangle until the submodules are initialised: `bash .skills/doctor.sh`. A `SessionStart` hook bumps them daily on `main` and pushes. Inventory, override, refresh: [docs/SKILLS.md](docs/SKILLS.md).
+`gregoryfoster/skills` and `obra/superpowers` vendored under `skills-vendor/`, symlinked into `skills/` (agentskills.io) and `.claude/skills/` (Claude Code). Symlinks dangle until the submodules are initialised: `bash .skills/doctor.sh`. A `SessionStart` hook bumps them daily on `main` and pushes. Inventory, refresh, worktrees: [docs/SKILLS.md](docs/SKILLS.md).
 
 ## Environment Files
 
@@ -96,7 +101,7 @@ scripts/deploy.sh [<build>]              # ship: CI green, then build a release
 - [docs/specs/2026-09-29-processor-service-design.md](docs/specs/2026-09-29-processor-service-design.md) — the spec: decisions, grants, runtime, failure table, versioning, cutover, testing, contract quick reference
 - [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) — prerequisites, the broker credential handoff, `/etc/processor/`, releases and `scripts/deploy.sh`, the drift check, liveness, containment, install and rollback, operate, co-core bumps, Tailscale DNS, Node.js
 - [docs/plans/](docs/plans/) — implementation plans
-- [docs/SKILLS.md](docs/SKILLS.md) — vendored agent skills, the brainstorming override, the refresh hook
+- [docs/SKILLS.md](docs/SKILLS.md) — vendored agent skills: inventory, overrides (none), the refresh hook, worktrees
 - [docs/SOCRATICODE.md](docs/SOCRATICODE.md) — semantic search: tools, the shared store, link stubs, the pin, the memory decision
 
 <!-- BEGIN socraticode-policy -->

docs/SKILLS.md

@@ -36,21 +36,19 @@ The first session in a fresh clone or worktree fails the hook with exit 127 (hoo
 
 **gregoryfoster-skills (13):** `auditing-ci-cost` (CI since #12), `coordinating-epics` (#24 since #52), `curating-context`, `enforcing-architecture` (`reviewing-architecture` delegates to it), `init-socraticode`, `managing-skills`, `orchestrating-issue-backlog`, `reviewing-architecture`, `reviewing-code-python-fastapi`, `shipping-work-python-fastapi`, `using-git-worktrees`, `using-mayfly-chat`, `writing-plans`.
 
-**obra-superpowers (11 + override):** `dispatching-parallel-agents`, `executing-plans`, `finishing-a-development-branch`, `receiving-code-review`, `requesting-code-review`, `subagent-driven-development`, `systematic-debugging`, `test-driven-development`, `using-superpowers`, `verification-before-completion`, `writing-skills`; `brainstorming` as an override.
+**obra-superpowers (12):** `brainstorming`, `dispatching-parallel-agents`, `executing-plans`, `finishing-a-development-branch`, `receiving-code-review`, `requesting-code-review`, `subagent-driven-development`, `systematic-debugging`, `test-driven-development`, `using-superpowers`, `verification-before-completion`, `writing-skills`.
 
 - **Review and ship are the `-python-fastapi` variants, though processor isn't FastAPI** (as broker). Their `pre-ship.sh` is processor's gate unmodified: `ruff check`, `ruff format --check`, `pytest` minus `integration`. The Alembic/route steps key on paths processor lacks; the `deploy/` review checks and the post-merge `systemctl restart processor` fit.
 - **`using-mayfly-chat` needs Node ≥ 18**; its wrapper exits 4 without it. co-processor has Node 24 LTS from NodeSource apt, installed 2026-09-30 (#6). Linked because the cohort adopts it together (gregoryfoster/skills#302). A channel URL is read/write/delete access: never commit one.
-- **Superpowers' `using-git-worktrees` and `writing-plans` are not linked**: gregoryfoster's own, same-named, win. So brainstorming's hand-off to `writing-plans` lands plans in `docs/plans/`. Its filename is `YYYY-MM-DD-<topic-slug>.md`: start the topic with the issue number, so the slug is AGENTS.md's `<issue>-<slug>` (e.g. `2026-09-29-1-processor-v1.md`).
+- **Superpowers' `using-git-worktrees` and `writing-plans` are not linked**: gregoryfoster's own, same-named, win. So brainstorming's hand-off to `superpowers:writing-plans` lands plans in `docs/plans/` (AGENTS.md → *Brainstorming* maps the name; a test holds every `superpowers:<name>` to a link or a mapping). Its filename is `YYYY-MM-DD-<topic-slug>.md`: start the topic with the issue number, so the slug is AGENTS.md's `<issue>-<slug>` (e.g. `2026-09-29-1-processor-v1.md`).
 
 Not linked: `init-project-fastapi` (scaffolder), `vendoring-openapi-client` (no sibling HTTP API called), the other stack variants of review/ship, `diagnosing-superpowers` (no sibling links it). The daily refresh never adds symlinks, so a newly published skill is a manual link: diff `ls skills-vendor/*/skills/` against this list.
 
 ## Overrides
 
-| Skill | Overrides | Delta |
-|---|---|---|
-| `brainstorming` | `obra-superpowers/brainstorming` | `docs/superpowers/specs/` → `docs/specs/`, in `SKILL.md` and `spec-document-reviewer-prompt.md`. Otherwise upstream verbatim; `visual-companion.md` and `scripts/` are vendor symlinks. Observo's pattern |
+None since #62. `brainstorming` was one, synced from v6.4.2 to move the design doc to `docs/specs/`, until v7 deferred that path to the partner's preferences; AGENTS.md → *Brainstorming* states them. Where upstream defers, a stated preference beats an override: it needs no re-sync.
 
-The doctor warns when the vendor moves past `synced-from:`. Re-sync by reapplying the delta onto the new upstream text (never the reverse), then bump `synced-from:`: `managing-skills` → *Updating a local override*. Kept minimal on purpose: the heavier cohort forks each needed re-sync issues.
+An override is a regular directory in `skills/` whose `SKILL.md` names `overrides:` and `synced-from:` (tests/test_skills.py holds it to both). The doctor warns when the vendor moves past `synced-from:`. Re-sync by reapplying the delta onto the new upstream text (never the reverse), then bump `synced-from:`: `managing-skills` → *Updating a local override*. Kept minimal on purpose: the heavier cohort forks each needed re-sync issues.
 
 ## Worktrees
 

docs/SOCRATICODE.md

@@ -200,8 +200,8 @@ extraction child volunteers at +1000. The peak that took broker down on
 Revisit if the service's resident memory grows into hundreds of MiB.
 
 **Index scope here.** `.socraticodeignore` drops `skills-vendor/`, `skills/`,
-`.claude/skills/` and `.skills/` (vendored; `skills/brainstorming` is an upstream
-copy with one path changed), both worktree roots, `.wheelhouse`, and
+`.claude/skills/` and `.skills/` (vendored, or an upstream override; none since
+#62), both worktree roots, `.wheelhouse`, and
 `docs/plans/`. Plans stay searchable as the `implementation-plans` artifact
 (scope a search to it with `artifactName`); out of the code index, a superseded
 plan cannot outrank the source. What remains is about 95 tracked files, 48 of

docs/plans/2026-10-22-62-brainstorming-vendor-link.md

@@ -0,0 +1,39 @@
+---
+title: The brainstorming override becomes a vendor link and an AGENTS.md preference (#62)
+date: 2026-10-22
+status: per #62's hand-off from epic #24 (2026-10-21)
+---
+
+# The brainstorming override becomes a vendor link
+
+## Problem
+
+`skills/brainstorming/` is a v6.4.2 copy (`8ca22db`), kept to change one path. The vendor is at v7 (`b739a8a`): `SKILL.md` rewritten, `spec-document-reviewer-prompt.md` gone, `builder-check-prompt.md` added and unlinked. The doctor reports the drift. v7 says "Your human partner's preferences override both" for where the design goes, so a stated preference does the fork's job with no re-sync.
+
+## Approach
+
+- `skills/brainstorming` → symlink `../skills-vendor/obra-superpowers/skills/brainstorming`. `.claude/skills/brainstorming` unchanged.
+- AGENTS.md, a `### Brainstorming` preference under Development Methodology:
+  - a change to the service's behaviour amends the spec of record (a dated **Amended** entry plus the sections it touches), as #29–#57 did;
+  - a new design doc only for work the spec doesn't cover: `docs/specs/YYYY-MM-DD-<issue>-<topic>-design.md`, never `docs/superpowers/specs/`. Issue first, as plans; `-design` kept, as the spec, the override and v7;
+  - `superpowers:<name>` means this repo's `skills/<name>`: `superpowers:writing-plans` is gregoryfoster's `writing-plans`, writing to `docs/plans/`; `superpowers:using-git-worktrees` likewise;
+  - the builder check runs as written; on an amendment, the builder reads the spec's amended sections.
+- docs/SKILLS.md: obra count 11 + override → 12, `brainstorming` in the list; § Overrides removed (its only row) but the rule kept in one line, so a future override still has a home; line 43's naming note points at AGENTS.md.
+- Stale mentions: AGENTS.md Detail Docs and § Agent Skills, `.socraticodeignore:6`, `.socraticodecontextartifacts.json:21`, docs/SOCRATICODE.md:203, `tests/test_socraticode_config.py:74`. `tests/test_drift.py:115` stays: `skills/brainstorming` is still a non-runtime path.
+
+## Test
+
+`tests/test_skills.py`:
+- `test_skills_md_inventory_matches_the_links` checks the obra count too (it skipped it for the "+ override" heading). Red now: the heading says 11, the list names 12.
+- New: every `superpowers:<name>` a linked superpowers skill's `SKILL.md` invokes resolves to `skills/<name>`, and where that entry is not superpowers', AGENTS.md names `` `superpowers:<name>` ``. Red now: AGENTS.md names neither.
+- `test_skills_are_vendor_links_or_declared_overrides` and `test_override_links_resolve` stay, vacuous until the next override.
+
+Known limit: the new test reads vendor text, so an upstream bump that invokes an unlinked skill fails CI on `main` after the hook's push. That is the signal wanted, at the same place `SKILL.md is_file` already fails.
+
+## Ship
+
+Doctor before/after in the PR; `git ls-files -s skills/brainstorming` shows `120000`. PR (`Closes #62`) → `git pull --ff-only` → FF merge → `git pull --ff-only`. No deploy.
+
+## Open questions
+
+None.

skills/brainstorming

@@ -0,0 +1 @@
+../skills-vendor/obra-superpowers/skills/brainstorming