shapeup-sdlc 1.6.2

package/skills/ba-pitch-analyzer/scripts/spec-lint.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// Spec lint (pure-skill architecture v1.0, plan §8.2).
+//
+// The mechanical half of the old ba-pitch-analyzer Phase 7a self-audit + Phase 7c parse steps
+// + Phase 6b PA1/PA2 lints — checkbox walking and glob checks a model should never grade on
+// its own output (a worker grading itself was always a judge-purity smell):
+//
+//   PA1  a scope substrate aligned 1:1 with a single top-level directory (directory-thinking)
+//   PA2  a scope substrate resolving to more than the size cap (~15 files)
+//   DISJOINT  a path matched by two scopes' allowed_file_substrate without BOTH declaring it
+//             in shared_substrate
+//   STRUCTURE spec tree completeness (usecases/ ≥1 UC, domain-model, UC ## Steps),
+//             unresolved wikilinks, task frontmatter completeness, unlocks edge-symmetry,
+//             depends_on referencing unknown tasks
+//   TIER-DIRECTION  a committed (SHARED) spec doc wikilinking the LOCAL board ([[tasks/...]]).
+//             Persisted links flow LOCAL→SHARED only: task ids are machine-local (boards
+//             regenerate and renumber) and .shapeup/ is gitignored — a committed task
+//             link dangles on every fresh clone. Cite the UC or scope_id instead.
+//   UC-ANCHOR a task whose use_case_refs is empty or names a UC with no usecases/UC-*.md —
+//             the LOCAL→SHARED anchor must be complete (single-anchor rule; SPIKE/CHORE/
+//             DOCS/MIGRATION tasks anchor elsewhere and are exempt)
+//
+// Zero dependencies (glob matcher inlined from hooks/sandbox-guard.mjs). Judgment stays in the skill
+// (gap severity, lens choice); this script only reports facts.
+//
+// Usage:  node skills/ba-pitch-analyzer/scripts/spec-lint.mjs --slug <slug> [--cwd <dir>]
+// Prints a JSON report. Exit 0 = no red findings, 1 = at least one red.
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { resolve, join, relative } from "node:path";
+import { parseBoard, deriveUnlocks } from "./board-derive.mjs";
+import { isMain } from "../../tech-lead/scripts/lib/is-main.mjs";
+import { runArgs } from "../../tech-lead/scripts/lib/argv.mjs";
+import { LOCAL } from "../../tech-lead/scripts/lib/paths.mjs";
+import { specDir, scopesDir, tasksDir } from "../../tech-lead/scripts/lib/paths.mjs";
+import { readAllContracts, unreadableReason, SCOPE_CONTRACT } from "../../tech-lead/scripts/lib/contract-md.mjs";
+
+// Inlined from hooks/sandbox-guard.mjs so this skill ships self-contained (a skill's scripts
+// must not reach outside its own folder — channels that copy only skills/ would dangle).
+/**
+ * Compile a substrate glob into an anchored RegExp (inlined from sandbox-guard so the skill ships
+ * self-contained). Supports single-star, double-star, and double-star-slash segment wildcards.
+ * @param {string} glob - The glob pattern.
+ * @returns {RegExp} A full-string (`^…$`) matcher for repo-relative paths.
+ */
+export function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        re += glob[i + 2] === "/" ? "(?:[^/]+/)*" : ".*";
+        i += glob[i + 2] === "/" ? 2 : 1;
+      } else re += "[^/]*";
+    } else if ("\\^$.|?+()[]{}".includes(c)) re += "\\" + c;
+    else re += c;
+  }
+  return new RegExp(`^${re}$`);
+}
+
+const SIZE_CAP = 15;
+
+/**
+ * Recursively list repo-relative file paths under a root, skipping .git/node_modules/.shapeup.
+ * @param {string} root - The base the results are made relative to.
+ * @param {string} [dir=root] - Current directory being walked (callers omit it).
+ * @param {string[]} [acc=[]] - Accumulator (callers omit it).
+ * @returns {string[]} Repo-relative paths of every file found.
+ */
+function walkFiles(root, dir = root, acc = []) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === ".git" || e.name === "node_modules" || e.name === LOCAL) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walkFiles(root, p, acc);
+    else acc.push(relative(root, p));
+  }
+  return acc;
+}
+
+/**
+ * Lint scope contracts for PA1 (directory-thinking), PA2 (size cap), and DISJOINT substrate overlap.
+ * @param {Array<{scope_id:string, topology_type?:string, allowed_file_substrate?:string[],
+ *   shared_substrate?:string[]}>} scopes - The scope contracts.
+ * @param {string[]} repoFiles - Repo-relative file list the substrate globs resolve against.
+ * @returns {Array<{rule:string, level:("red"|"warn"), scope:string, detail:string}>} Findings; [] when clean.
+ */
+export function lintScopes(scopes, repoFiles) {
+  const findings = [];
+  /**
+   * Resolve a list of substrate globs to the repo files they match.
+   * @param {(string[]|undefined)} globs - Glob patterns (undefined → none).
+   * @returns {string[]} The repo-relative files matched by any glob (deduplication is the caller's).
+   */
+  const resolveGlobs = (globs) => {
+    const res = (globs || []).map((g) => globToRegExp(g));
+    return repoFiles.filter((f) => res.some((r) => r.test(f)));
+  };
+  for (const s of scopes) {
+    const allowed = s.allowed_file_substrate || [];
+    // PA1 — directory-thinking: every glob confined to ONE layer directory (e.g. all of it
+    // under apps/web/). A flow slice crosses layers (apps/web/cart + apps/api/cart passes).
+    const layers = new Set(allowed.map((g) => g.split("/").slice(0, 2).join("/")));
+    if (allowed.length && layers.size === 1 && s.topology_type !== "CHOWDER") {
+      findings.push({ rule: "PA1", level: "red", scope: s.scope_id, detail: `substrate aligns 1:1 with '${[...layers][0]}/' — slice by flow, not by directory` });
+    }
+    // PA2 — resolved file count over the cap (chowder absorbs true strays).
+    const files = resolveGlobs(allowed);
+    if (files.length > SIZE_CAP && s.topology_type !== "CHOWDER") {
+      findings.push({ rule: "PA2", level: "warn", scope: s.scope_id, detail: `substrate resolves to ${files.length} files (cap ~${SIZE_CAP}) — consider splitting` });
+    }
+  }
+  // DISJOINT — pairwise overlap not covered by BOTH scopes' shared_substrate.
+  for (let i = 0; i < scopes.length; i++) {
+    for (let j = i + 1; j < scopes.length; j++) {
+      const a = scopes[i], b = scopes[j];
+      const filesA = new Set(resolveGlobs(a.allowed_file_substrate));
+      const overlap = resolveGlobs(b.allowed_file_substrate).filter((f) => filesA.has(f));
+      const sharedA = (a.shared_substrate || []).map(globToRegExp);
+      const sharedB = (b.shared_substrate || []).map(globToRegExp);
+      for (const f of overlap) {
+        const declared = sharedA.some((r) => r.test(f)) && sharedB.some((r) => r.test(f));
+        if (!declared) findings.push({ rule: "DISJOINT", level: "red", scope: `${a.scope_id}+${b.scope_id}`, detail: `${f} is in both substrates but not in both shared_substrate lists — PA3 waiting to happen` });
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Lint spec-tree completeness, wikilink resolution, tier-direction, task frontmatter/graph
+ * integrity (edge symmetry, dependency existence), and UC-anchor completeness.
+ * @param {{specDir:string, tasks:Array<object>}} input - The SHARED spec dir and the parsed board.
+ * @returns {Array<{rule:string, level:("red"|"warn"), detail:string}>} Findings; [] when clean.
+ */
+export function lintStructure({ specDir, tasks }) {
+  const findings = [];
+  const ucDir = join(specDir, "usecases");
+  if (!existsSync(join(specDir, "domain-model.md"))) findings.push({ rule: "STRUCTURE", level: "red", detail: "domain-model.md missing" });
+  const ucs = existsSync(ucDir) ? readdirSync(ucDir).filter((f) => /^UC-.*\.md$/.test(f)) : [];
+  if (!ucs.length) findings.push({ rule: "STRUCTURE", level: "red", detail: "usecases/ has no UC-*.md — nothing to build or grade against" });
+  for (const f of ucs) {
+    const body = readFileSync(join(ucDir, f), "utf8");
+    if (!/^##\s+Steps/m.test(body)) findings.push({ rule: "STRUCTURE", level: "warn", detail: `${f} has no ## Steps section` });
+  }
+  // Wikilinks in spec docs must resolve within the spec dir — and never cross the tier
+  // boundary: a SHARED doc linking the LOCAL board is the wrong direction by construction.
+  const specFiles = existsSync(specDir) ? walkFiles(specDir) : [];
+  const names = new Set(specFiles.map((f) => f.replace(/\.md$/, "")));
+  for (const f of specFiles.filter((x) => x.endsWith(".md"))) {
+    const body = readFileSync(join(specDir, f), "utf8");
+    for (const m of body.matchAll(/\[\[([^\]#|]+)/g)) {
+      const target = m[1].trim().replace(/\.md$/, "");
+      if (target.startsWith("tasks/")) {
+        findings.push({ rule: "TIER-DIRECTION", level: "red", detail: `${f} → [[${m[1].trim()}]] links the LOCAL board from a committed doc — links flow LOCAL→SHARED only; cite the UC or scope_id instead (task ids renumber per machine)` });
+        continue;
+      }
+      if (!names.has(target) && ![...names].some((n) => n.endsWith(`/${target}`) || n === target)) {
+        findings.push({ rule: "WIKILINK", level: "warn", detail: `${f} → [[${m[1].trim()}]] unresolved in spec dir` });
+      }
+    }
+  }
+  // Task frontmatter + graph integrity (edge symmetry = the mechanized KB-BA-001 check).
+  const ids = new Set(tasks.map((t) => t.id));
+  const derived = deriveUnlocks(tasks);
+  for (const t of tasks) {
+    for (const k of ["id", "status"]) if (!t[k] || t[k] === "unknown") findings.push({ rule: "TASK", level: "red", detail: `${t.file} missing frontmatter ${k}` });
+    for (const d of t.depends_on) if (!ids.has(d)) findings.push({ rule: "TASK", level: "red", detail: `${t.id} depends_on ${d} which does not exist` });
+    if (JSON.stringify([...t.unlocks].sort()) !== JSON.stringify(derived[t.id] || [])) {
+      findings.push({ rule: "EDGE-SYMMETRY", level: "red", detail: `${t.id} unlocks ${JSON.stringify(t.unlocks)} ≠ derived inverse ${JSON.stringify(derived[t.id])} — run board-derive.mjs --write` });
+    }
+  }
+  // UC-ANCHOR — the LOCAL→SHARED anchor must be complete: every implementation task names
+  // ≥1 UC (single-anchor rule, task-generation.md) and each named UC exists on disk.
+  // SPIKE/CHORE/DOCS/MIGRATION tasks anchor elsewhere (api_ref / linked_docs) — exempt.
+  const ucIds = new Set(ucs.map((f) => f.replace(/\.md$/, "")));
+  const anchorExempt = new Set(["spike", "chore", "docs", "migration"]);
+  for (const t of tasks) {
+    if (anchorExempt.has((t.type || "").toLowerCase())) continue;
+    const refs = t.use_case_refs || [];
+    if (!refs.length) {
+      findings.push({ rule: "UC-ANCHOR", level: "red", detail: `${t.id} has empty use_case_refs — every task must anchor into the committed spec (LOCAL→SHARED, single-anchor rule)` });
+      continue;
+    }
+    for (const r of refs) {
+      const ucId = r.replace(/^\[\[|\]\]$/g, "").replace(/^usecases\//, "");
+      if (!ucIds.has(ucId)) findings.push({ rule: "UC-ANCHOR", level: "red", detail: `${t.id} use_case_refs "${r}" does not resolve to usecases/${ucId}.md` });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Run the full spec lint (scopes + structure) for a slug.
+ * @param {{cwd:string, slug:string}} opts - Working root and feature slug.
+ * @returns {{slug:string, scopes:number, tasks:number, red:number, warn:number,
+ *   findings:Array<object>}} Counts and the combined findings from {@link lintScopes} and
+ *   {@link lintStructure}.
+ */
+export function lint({ cwd, slug }) {
+  const specRoot = specDir(cwd, slug);
+  const contracts = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT);
+  const scopes = contracts.map((c) => c.contract);
+  const tasks = parseBoard(tasksDir(cwd, slug));
+  const repoFiles = walkFiles(cwd);
+  const findings = [
+    // HD-001. A contract whose table this parser cannot see reads as a contract that declared no
+    // table, and every rule below then passes for the part it could not read. Loud, not empty.
+    ...contracts
+      .map(({ contract, path }) => ({ reason: unreadableReason(contract), scope: contract.scope_id || path }))
+      .filter((x) => x.reason)
+      .map((x) => ({ rule: "CONTRACT-UNREADABLE", level: "red", scope: x.scope, detail: `${x.reason} — the rules below could not check what they could not read` })),
+    ...lintScopes(scopes, repoFiles),
+    ...lintStructure({ specDir: specRoot, tasks }),
+  ];
+  return {
+    slug,
+    scopes: scopes.length,
+    tasks: tasks.length,
+    red: findings.filter((f) => f.level === "red").length,
+    warn: findings.filter((f) => f.level === "warn").length,
+    findings,
+  };
+}
+
+/** The typed argv contract (see `skills/tech-lead/scripts/lib/argv.mjs`). */
+export const ARGV_SPEC = {
+  usage: "spec-lint.mjs --slug <slug> [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  cwd: { type: "path" },
+};
+
+const isMainModule = isMain(import.meta.url);
+if (isMainModule) {
+  const args = runArgs(ARGV_SPEC);
+  const report = lint({ cwd: resolve(args.cwd || process.cwd()), slug: args.slug });
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(report.red > 0 ? 1 : 0);
+}

package/skills/coach/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: coach
+description: "Use this skill to turn raw Product Owner / Tech Lead feedback at the Ship Sign-off (L4 Gate) into structured, team-shared guidelines that future harness runs read back. Triggers on: \"coach this feedback\", \"record this for next sprint\", \"update the knowledge base\", \"RLHF the harness\", and Vietnamese \"ghi lại cho sprint sau\", \"cập nhật knowledge base\". tech-lead invokes it automatically at GATE L4 when the PO gives substantive feedback instead of a bare 'y'. NOT for grading work (spec-evaluator), fixing bugs (task-executor), or filing discovered tasks (the ledger)."
+---
+
+# Coach Skill — RLHF for the harness
+
+The `/coach` skill closes the learning loop. After a feature ships, the PO/TL drops raw,
+unstructured feedback at the L4 Gate ("the executor keeps over-engineering DTOs", "the BA
+under-scopes mobile"). The coach distills that into durable **guidelines** and files them where
+the relevant worker will read them on its **next** run — so the lesson is learned once and applied
+by the whole team forever, not re-explained every sprint.
+
+Two properties make this useful and were missing before:
+
+1. **Team-shared, not local.** Guidelines are written under `shapeup/knowledge-base/`,
+   which is **committed** (the `.shapeup/` run-trace root is gitignored — guidelines written
+   there would never reach a teammate). A `git pull` is all a team member needs to inherit the
+   harness's accumulated judgment.
+2. **Read back, not write-only.** Each guideline is filed under the **one skill that will act on
+   it**, in that skill's own file, so the consumer loads only its own rules. `task-executor`,
+   `ba-pitch-analyzer`, and `qa-edge-hunter` each read their file at the top of their run.
+
+```
+PO feedback at L4 ─► /coach ─► [parse into candidate rules] ─► ⏸ GATE COACH-1 (categorize, ask — never assume)
+                                                                          │
+                          shapeup/knowledge-base/<skill>.md ◄───┤  (one file per coachable skill, committed)
+                                                                          │
+                  next run: task-executor / ba-pitch-analyzer / qa-edge-hunter reads its own file
+                                                                          │
+              shapeup/knowledge-base/harness-defects.md ◄───────┘  (mechanism at fault →
+                  drafted raw idea for the Betting Table — read by no worker, committed)
+```
+
+---
+
+## Coachable skills (the only valid categories)
+
+A guideline is only useful if a worker reads it back. These three workers have a read-side hook;
+they are the **complete** set of categories the gate may offer:
+
+| Category | File | The worker reads it at | Good for |
+|----------|------|------------------------|----------|
+| `task-executor`     | `shapeup/knowledge-base/task-executor.md`     | Phase 1 (Context Load) | implementation discipline, code style, surgical-change habits, recurring over/under-engineering |
+| `ba-pitch-analyzer` | `shapeup/knowledge-base/ba-pitch-analyzer.md` | Phase 1 (Ingest & Scan) | scoping, task decomposition, DDD/spec habits, missed test-surface patterns |
+| `qa-edge-hunter`    | `shapeup/knowledge-base/qa-edge-hunter.md`    | Phase Q1 (Charter Map) | recurring edge classes, lenses that keep finding bugs, areas worth probing |
+
+**Not coachable.** `spec-evaluator` is deliberately excluded — the harness has a **single-judge**
+rule and the knowledge base is guidance, never an invariant; routing rules into the evaluator would
+turn advice into a second grader. `orient`, `shapeup`, `tech-lead`, and `translator` have no
+read-side hook, so a rule filed there would never be read. If feedback truly targets one of these,
+say so plainly — do **not** force-fit it into a coachable category.
+
+**Harness defect ≠ worker steering.** When the feedback's root cause is the *mechanism itself* —
+a hook that fail-opens, a gate that reads the wrong file, two skill contracts that contradict
+each other — no amount of steering a worker fixes it, and filing it as a KB rule misdiagnoses a
+defect as a habit (island-escape's KB-BA-002 filed an orchestration/hook defect as BA guidance,
+on a premise the skill contracts contradict). That is what the `harness-defect` category below is
+for: the coach records it in the committed defect register as a drafted **raw idea** for the
+Betting Table — the debt-free path ("remaining findings + new feedback → new raw idea") — and it
+never lands in any worker's KB.
+
+---
+
+## Envelope contract — the domain layer
+
+Orchestrated, this skill is dispatched like every worker: a **WorkOrder** in (`--order <path>`,
+operation `coach`), a **WorkResult** out. Standalone, the raw feedback is passed directly; it
+maps onto the one payload field registered for this worker in the central domain registry
+(`skills/tech-lead/schemas/domain.schema.json`, `x-payload-by-worker`):
+
+| Payload field | Standalone form | Meaning |
+|---|---|---|
+| `payload.feedback` | positional text | The PO's raw L4 feedback to distill and categorize at GATE COACH-1 |
+
+The WorkResult may carry only `files_touched`, `artifacts`, `assumptions`, `deviations`
+(`x-result-by-worker`): the knowledge-base files written under
+`shapeup/knowledge-base/` return as `files_touched`/`artifacts` — the coach itself is
+not coachable and never returns discoveries, verdicts, or task results.
+
+---
+
+## Instructions
+
+### Step 1 — Parse the raw feedback into discrete candidate rules
+Feedback is usually a blob covering several points. Split it into atomic, generalized candidate
+rules — one actionable lesson each. Generalize the specific incident into a habit ("DTO had 9
+fields nobody used" → "Prefer the minimum DTO that satisfies the AC; don't add speculative
+fields"). Keep the originating why — a rule without its reason gets ignored or misapplied.
+
+### Step 2 — ⏸ GATE COACH-1: Categorize (ASK, never assume)
+This is the load-bearing gate. **Do not infer which skill a rule belongs to** — a
+miscategorized rule lands in a file the wrong worker reads (or no worker reads). Present every
+candidate rule and ask the PO to assign each one. Emit this block, then stop and wait:
+
+```
+⏸ GATE COACH-1 — Categorize feedback
+For each candidate rule, which skill should act on it?
+Valid: [task-executor] [ba-pitch-analyzer] [qa-edge-hunter]
+       [harness-defect — mechanism at fault, file as raw idea] [skip — not coachable]
+
+  R1. "<generalized rule>"   (why: <reason>)        → ?
+  R2. "<generalized rule>"   (why: <reason>)        → ?
+  ...
+
+Reply with an assignment per rule, e.g. "R1→task-executor, R2→harness-defect, R3→skip".
+A rule may map to more than one skill if it genuinely applies to both (e.g. "R1→task-executor, ba-pitch-analyzer").
+```
+
+Rules to honor at this gate:
+- **No silent defaulting.** If the PO's reply is ambiguous or leaves a rule unassigned, ask once
+  more for that rule specifically. Never pick a category on the PO's behalf.
+- **`skip` is a first-class answer.** Feedback aimed at a non-coachable skill, or one-off context
+  with no general lesson, is recorded as skipped in your summary and **not** written anywhere.
+- **Respect the single-judge rule.** If the PO tries to assign a rule to `spec-evaluator`,
+  surface that it isn't coachable (guidance ≠ invariant) and offer the nearest real target
+  (usually `ba-pitch-analyzer`, which owns the spec/test-surface) or `skip`.
+- **Recommend `harness-defect` when the mechanism is at fault.** If a candidate rule's "why"
+  blames a gate, hook, script, or a contradiction between skill contracts (rather than a
+  worker's judgment), say so and recommend `harness-defect` — but the PO still decides. The
+  telltale: the rule asks a worker to compensate for something the harness was supposed to
+  enforce ("cross-check X because the bookkeeping step gets skipped").
+
+### Step 3 — Merge each assigned rule into its skill's knowledge-base file
+For each `<skill>` that received at least one rule:
+1. Ensure `shapeup/knowledge-base/<skill>.md` exists (create from the template below if
+   not — the directory is committed, so the file ships to the team on the next commit).
+2. Read the existing file. Merge the new rule(s):
+   - **Consolidate** overlapping rules into one stronger statement.
+   - **Deduplicate** — if the lesson is already captured, reinforce/sharpen it rather than adding a
+     near-duplicate. Bump nothing silently; note the merge in your summary.
+   - **Generalize** a specific incident into a reusable guideline.
+3. Assign each new rule a stable id `KB-<SKILL-INITIALS>-NNN` (e.g. `KB-TE-001`, `KB-BA-004`,
+   `KB-QA-002`) and stamp it with the originating feature slug + date so a future reader can trace
+   it back.
+4. Rewrite the file. Keep it tight — the consumer loads it every run, so prune stale or
+   contradicted rules rather than letting it grow unboundedly. A rule whose premise the current
+   skill contracts contradict is a `harness-defect` in disguise — move it to the register
+   (Step 3b) and note the reclassification, don't keep re-teaching a misdiagnosis.
+
+### Step 3b — File `harness-defect` rules to the defect register (raw ideas, not steering)
+
+For each rule the PO assigned `harness-defect`, append an entry to
+`shapeup/knowledge-base/harness-defects.md` (create from the template below if
+missing). This file is **committed but read by no worker** — it is the PO's backlog of drafted
+raw ideas for the Betting Table, not guidance. Each entry gets a stable id `HD-NNN`, the
+observed symptom, the suspected mechanism at fault, and a one-paragraph raw-idea draft the PO
+can carry straight into Shaping. A report-only mention would evaporate (the write-only failure
+this skill exists to prevent); a worker-KB entry would steer the wrong actor — the register is
+the one spot that is both durable and inert.
+
+```markdown
+# Harness Defect Register
+
+> Filed by `/coach` from Ship-Gate (L4) feedback the PO categorized as `harness-defect` at
+> GATE COACH-1. **Read by no worker** — these are drafted raw ideas for the Betting Table
+> (the debt-free path), not guidelines. Remove an entry when its fix ships or its pitch is bet.
+
+## Defects
+- **HD-001** — <symptom observed at ship>. Suspected mechanism: <gate/hook/skill contract>.
+  Raw idea: <one-paragraph pitch seed>. · from `<feature-slug>` (<date>)
+```
+
+### Step 4 — Report back
+Summarize: which rules went to which file (with ids), which were consolidated into existing rules,
+which were filed as harness defects (HD ids — remind the PO these await a Betting Table decision,
+nothing acts on them automatically), and which were skipped (and why). Remind the PO that these are **guidelines** the named workers read
+on their next run — they steer `task-executor`, `ba-pitch-analyzer`, and `qa-edge-hunter`, but they
+are **not invariants** and the `spec-evaluator` verdict is unaffected (single-judge rule). Note that
+the files are committed, so a teammate inherits them on `git pull`.
+
+---
+
+## Knowledge-base file template
+
+When creating `shapeup/knowledge-base/<skill>.md` for the first time:
+
+```markdown
+# Knowledge Base — <skill>
+
+> Team-shared guidelines distilled from PO/TL feedback at the Ship Gate (L4) by `/coach`.
+> Read by `<skill>` at the top of its run. **Guidelines, not invariants** — they steer the
+> worker; they never override a spec or change the spec-evaluator verdict (single-judge rule).
+> Committed on purpose: a teammate inherits these on `git pull`.
+
+## Guidelines
+- **KB-<XX>-001** — <generalized rule>. _(why: <reason>)_  ·  from `<feature-slug>` (<date>)
+- **KB-<XX>-002** — <generalized rule>. _(why: <reason>)_  ·  from `<feature-slug>` (<date>)
+```
+
+---
+
+## Hard Rules
+| Rule | Rationale |
+|------|-----------|
+| Never assume a category — GATE COACH-1 asks the PO for every rule | A miscategorized rule reaches the wrong reader or none; the PO's intent is authoritative |
+| Only `task-executor`, `ba-pitch-analyzer`, `qa-edge-hunter` are valid worker categories | They are the only workers with a read-side hook; a rule elsewhere is never read |
+| A mechanism-at-fault rule goes to the defect register (`harness-defect`), never a worker KB | Steering a worker to compensate for a broken gate/hook misdiagnoses a defect as a habit and hides it from the Betting Table |
+| `spec-evaluator` is never a category | Single-judge rule: the KB is guidance, not an invariant — routing rules into the judge creates a second grader |
+| Write only under `shapeup/knowledge-base/` (committed) | The `.shapeup/` run-trace is gitignored; guidelines there never reach the team |
+| Guidelines, not invariants | The consumer weighs them; they don't gate, score, or override the spec |
+| Keep each file tight — prune as you merge | Consumers load it every run; unbounded growth becomes token cost and noise |