shapeup-sdlc 1.6.2 → 1.7.0

package/skills/tech-lead/scripts/init-run.mjs

@@ -1,18 +1,17 @@
 #!/usr/bin/env node
 // GATE L0.1 — START THE RUN. The orchestrator's first tool call, before any prose.
 //
-// WHY THIS EXISTS (measured, not theorized).
+// WHY THIS EXISTS (reproduced, not theorized).
 //
-// On the SDD harness benchmark (`sdd-harness-bench`, F2, Haiku 4.5, n=5, zero variance) the
-// orchestrator was dispatched with a valid spec and did this:
+// Dispatched with a valid spec, the orchestrator did this:
 //
-//     TOOL   Skill(tech-lead, "--unattended --rounds 3\n\n# F2 — category budgets…")
+//     TOOL   Skill(tech-lead, "--unattended --rounds 3\n\n# the requirement…")
 //     TEXT   "The tech-lead skill is orchestrating the full Shape Up harness. It will: 1. …"
 //     FINAL  (same text — session ends)
 //
-// It loaded a 450-line instruction file describing eleven gates and returned a description of
-// eleven gates. No code, no board, no gate artifacts — and prose that reads exactly like a
-// successful run. 29% acceptance, 10 escaped defects, five times out of five.
+// It loaded an instruction file describing eleven gates and returned a description of eleven
+// gates. No code, no board, no gate artifacts — and prose that reads exactly like a successful
+// run, with every defect still in the deliverable.
 //
 // Two guards existed and neither could see it:
 //   • `gate-intake.mjs` (L0.0) fires on an EMPTY intake. Intake was valid here. Correct no-op.
@@ -34,10 +33,10 @@
 //     assumed someone had established. Previously that someone was the model, deciding to.
 //     An invariant that depends on the model choosing to establish it is a prompt, not a gate.
 //
-// It also HASHES the intake into the receipt. The benchmark's first (wrong) diagnosis was that
-// requirement text was dropped on the hand-off. It was not, on re-run — but nothing on disk
-// could have settled that either way. Now it can: the intake that reached the orchestrator is
-// recorded verbatim next to its digest, so "the spec was dropped" is checkable, not arguable.
+// It also HASHES the intake into the receipt. The first (wrong) diagnosis of the failure above was
+// that requirement text had been dropped on the hand-off. It had not — but nothing on disk could
+// settle that either way. Now it can: the intake that reached the orchestrator is recorded
+// verbatim next to its digest, so "the spec was dropped" is checkable, not arguable.
 //
 // USAGE
 //   node init-run.mjs --slug <slug> --intake-file <path>            [options]   <- prefer this
@@ -46,13 +45,14 @@
 //
 // PREFER --intake-file. A multi-line requirement inlined into a shell argument is where this step
 // goes wrong: quoting breaks, a `#` after a newline trips path validation, and the run spends six
-// turns fighting its own command line instead of starting. Measured, on this project's benchmark.
+// turns fighting its own command line instead of starting. Observed, repeatedly.
 //
 //   --auto-level    interactive | auto | unattended   (default: interactive)
 //   --lens          lite | standard | cross-context   (default: standard)
 //   --max-rounds N  outer circuit breaker             (default: 3)
 //   --attempts N    inner per-scope T0 budget         (default: 5)
 //   --spec-folder   SHARED spec deliverable path      (default: shapeup/<slug>/spec/)
+//   --dimensions    comma-separated eval dimensions   (default: spec-conformance)
 //   --gate-answers  path | preset name                (see gate-answers.mjs; recorded, not read)
 //   --wall-clock-budget N  deadline breaker, seconds  (off by default; see budget-check.mjs)
 //   --cwd           project root                      (default: process.cwd())
@@ -74,6 +74,7 @@ import { createHash } from "node:crypto";
 import { decideLane, treeSize } from "./fit-check.mjs";
 import { isMain } from "./lib/is-main.mjs";
 import { runArgs } from "./lib/argv.mjs";
+import { uncoerce } from "./lib/contract-md.mjs";
 import { deriveSnapshot } from "./run-snapshot.mjs";
 import { localRoot, activeScope, globLocal, globShared } from "./lib/paths.mjs";
 
@@ -82,6 +83,35 @@ export const RECEIPT_VERSION = 1;
 const AUTO_LEVELS = new Set(["interactive", "auto", "unattended"]);
 const LENSES = new Set(["lite", "standard", "cross-context"]);
 
+/**
+ * The eval dimension set when the caller names none. Kept to the base correctness dimension so an
+ * unconfigured run behaves exactly as it did before this flag existed.
+ */
+export const DEFAULT_DIMENSIONS = ["spec-conformance"];
+
+/**
+ * Parse `--dimensions` into the set written to the ledger. Shape-validated only, NOT checked against
+ * the dimensions that ship: adding `references/dimensions/<id>.md` and naming it here is the
+ * documented injection path, so a closed list here would make the evaluator's own extension point
+ * unreachable. An id with no file behind it is skipped-with-a-warning at dimension resolution, which
+ * is where that check belongs and where it can actually see the files.
+ *
+ * @param {(string|null|undefined)} raw - The comma-separated flag value; absent → the default set.
+ * @returns {string[]} Trimmed, de-duplicated ids in the caller's order.
+ * @throws {Error} If the list is empty or an entry is not a kebab-case id.
+ */
+export function parseDimensions(raw) {
+  if (raw === null || raw === undefined) return [...DEFAULT_DIMENSIONS];
+  const ids = String(raw).split(",").map((s) => s.trim()).filter(Boolean);
+  if (!ids.length) throw new Error("--dimensions: empty list — omit the flag to use the default [spec-conformance]");
+  for (const id of ids) {
+    if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(id)) {
+      throw new Error(`--dimensions: "${id}" is not a dimension id (kebab-case, e.g. spec-conformance, tdd-surface, integration)`);
+    }
+  }
+  return [...new Set(ids)];
+}
+
 /** Slugify a free-text feature name into a filesystem-safe run id. */
 export function slugify(text) {
   return String(text || "")
@@ -124,7 +154,10 @@ export function runFrontmatter({ slug, config, startedAt }) {
     `feature: ${slug}`,
     `spec_folder: ${config.spec_folder}`,
     `lens: ${config.lens}`,
-    "eval_dimensions: [spec-conformance]",
+    // The ledger is the ONE place the dimension set lives: resume-state reads it back off this line
+    // and the workflow hands it to every evaluate order. Written through the same list dialect the
+    // parser reads (contract-md), never hand-joined.
+    `eval_dimensions: ${uncoerce(config.eval_dimensions ?? DEFAULT_DIMENSIONS)}`,
     `max_rounds: ${config.max_rounds}`,
     `attempt_budget: ${config.attempt_budget}`,
     `wall_clock_budget_s: ${config.wall_clock_budget_s ?? "~"}`,
@@ -164,7 +197,8 @@ export function runFrontmatter({ slug, config, startedAt }) {
 export const ARGV_SPEC = {
   usage: 'init-run.mjs (--intake-file <path> | --intake-text "<req>" | --intake-stdin) ' +
          "[--slug <slug>] [--auto-level interactive|auto|unattended] [--lens <lens>] " +
-         "[--max-rounds N] [--attempts N] [--spec-folder <dir>] [--gate-answers <preset|path>] " +
+         "[--max-rounds N] [--attempts N] [--spec-folder <dir>] [--dimensions <a,b>] " +
+         "[--gate-answers <preset|path>] " +
          "[--lane full|tiny] [--tiny] [--wall-clock-budget <seconds>] [--cwd <dir>] [--force]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
@@ -177,6 +211,7 @@ export const ARGV_SPEC = {
   "max-rounds": { type: "int", min: 1 },
   attempts: { type: "int", min: 1 },
   "spec-folder": { type: "path" },
+  dimensions: { type: "str" },
   "gate-answers": { type: "str" },
   lane: { type: "str" },
   tiny: { type: "flag" },
@@ -220,10 +255,17 @@ export function main() {
   if (!AUTO_LEVELS.has(auto_level)) fail(2, `--auto-level must be one of: ${[...AUTO_LEVELS].join(", ")}`);
   const lens = args.lens ?? "standard";
   if (!LENSES.has(lens)) fail(2, `--lens must be one of: ${[...LENSES].join(", ")}`);
+  // GATE L0.5 — the eval dimension set, resolved ONCE here and carried by the ledger. Before this
+  // flag the line was a constant, so a dimension the PO asked for at L0.5 had nowhere to be
+  // recorded and the run graded spec-conformance whatever the answer had been.
+  let eval_dimensions;
+  try { eval_dimensions = parseDimensions(args.dimensions ?? null); }
+  catch (e) { fail(2, e.message); }
 
   const config = {
     auto_level,
     lens,
+    eval_dimensions,
     max_rounds: args.maxRounds ?? 3,
     attempt_budget: args.attempts ?? 5,
     spec_folder: args.specFolder ?? `${globShared(slug, "spec")}/`,
@@ -242,7 +284,7 @@ export function main() {
     })(),
     // The third breaker (see scripts/budget-check.mjs). Null = off, which is the default and
     // keeps every existing run behaving exactly as before. Set it in any lane with a hard clock
-    // — CI, a benchmark, an overnight run — so the harness trips its own breaker and ships what
+    // — CI, an overnight run — so the harness trips its own breaker and ships what
     // is green, instead of being killed from outside and shipping nothing.
     wall_clock_budget_s: args.wallClockBudget ?? null,
   };
@@ -258,9 +300,9 @@ export function main() {
   // step, the runtime named a mechanism that does not exist, on a script whose failure mode was
   // already invisible (see lib/is-main.mjs — under a symlinked install this whole body did not run).
   //
-  // Measured consequence, on the SDD harness benchmark's F4 handoff: a fresh session in a workspace
-  // with an open run spent 82–120 turns before its first write, largely on forensics against this
-  // step, and closed 0/3 of the gap.
+  // Observed consequence on a handoff: a fresh session in a workspace with an open run burns most
+  // of its budget before its first write, largely on forensics against this step, and closes none
+  // of the gap.
   //
   // So the refusal now DOES the resume work instead of describing it. It emits the derived snapshot
   // — the same file-only derivation `hooks/session-rehydrate.mjs` injects — so the orchestrator gets

package/skills/tech-lead/scripts/lib/argv.mjs

@@ -37,7 +37,7 @@
 // rewrite call sites. Unknown flags are rejected rather than silently swallowed as positionals:
 // a typo'd `--rounds 2` that lands in `_` is the same defect wearing a different hat.
 //
-// `tests/structural/13-argv-contract.mjs` executes every entry point with each declared int flag
+// The structural suite executes every entry point with each declared int flag
 // both empty and non-numeric, and asserts exit 2 with a parseable reason and no artifact on disk.
 
 /** Thrown by {@link parseArgs} when argv does not satisfy the spec. `detail` is the wire shape. */

package/skills/tech-lead/scripts/lib/contract-md.mjs

@@ -38,7 +38,7 @@ import { join } from "node:path";
 // Per-type layout: which array-of-objects field lives under which heading.
 //
 // `signatures` names the columns that identify a table as THAT field's, and it exists because of
-// HD-001: the heading match is exact, so a table written under `# Wiring map — <slug>` instead of
+// The heading match is exact, so a table written under `# Wiring map — <slug>` instead of
 // `## Wiring` parsed as ABSENT, and every reader downstream treats absent as "none declared". The
 // observed consequence was `trace-lint` reporting `🟢 green · 0/0 engines reach src/cli/main.js`
 // for a committed map holding six correct rows — the gate whose whole purpose is that no engine
@@ -91,7 +91,7 @@ export const UNREADABLE = "$unreadable_tables";
  */
 export function coerce(raw) {
   let trimmed = String(raw ?? "").trim();
-  // HD-005 — A MARKDOWN CODE SPAN IS FORMATTING, NOT PART OF THE VALUE.
+  // A MARKDOWN CODE SPAN IS FORMATTING, NOT PART OF THE VALUE.
   //
   // These contracts are MARKDOWN on disk, and a code span is the idiomatic way to write a path or
   // an identifier in one; this repo's own prose backticks every path it names. Read literally,
@@ -99,7 +99,7 @@ export function coerce(raw) {
   // anywhere — so `trace-lint` reported "engine file not on disk" and then "reachability is not
   // demonstrated" for a wiring map whose engines all resolve AND all reach the entry point. The
   // gate that exists so no engine ships orphaned failing CLOSED, on a correct map, is the same
-  // silent-format family as HD-001..HD-004 arriving from the other direction.
+  // silent-format family as the parser defects above, arriving from the other direction.
   //
   // Stripped ONLY when the whole value is a single span: a cell like
   // "Registered as the `add` entry in `TABLE`" is prose that happens to contain spans, and its
@@ -125,7 +125,7 @@ export function coerce(raw) {
  */
 export function uncoerce(v) {
   if (v === null || v === undefined) return "~";
-  // HD-002's other half. A member containing the delimiter must go back out QUOTED, or the round
+  // The other half of the comma defect. A member containing the delimiter must go back out QUOTED, or the round
   // trip that wrote it re-reads as several members — the same shredding, arriving from the writer's
   // side instead of the reader's.
   if (Array.isArray(v)) return `[${v.map((x) => (/[,"]/.test(String(x)) ? JSON.stringify(String(x)) : String(x))).join(", ")}]`;
@@ -135,7 +135,7 @@ export function uncoerce(v) {
 /**
  * Split a `[a, b]` list body on commas that are NOT inside quotes.
  *
- * HD-002. The old implementation was `body.split(",")`, and it shredded any member carrying a
+ * The old implementation was `body.split(",")`, and it shredded any member carrying a
  * comma — even a correctly quoted one. Measured: a `scope-architect` run probed the running CLI,
  * confirmed `tag` was unimplemented, and wrote the honest entry its own SKILL.md asks for —
  *   ["TBD — `tag` is not in dispatch.js's TABLE (exits 1, confirmed against the running CLI). A
@@ -191,12 +191,12 @@ export function splitFrontmatter(md) {
     const key = line.slice(0, c).trim();
     const inline = line.slice(c + 1).trim();
 
-    // HD-003. An indented run beneath a key is a YAML BLOCK SEQUENCE, and it used to be skipped
+    // An indented run beneath a key is a YAML BLOCK SEQUENCE, and it used to be skipped
     // entirely — so `e2e_verification_fixtures:` followed by two `- "node …"` lines parsed to
     // null, the members vanished, and no reader could tell "declared nothing" from "declared
     // something I discarded". Measured: a scope-architect run wrote three scopes of researched
     // fixtures in this form and every one evaporated. It is ACCEPTED now, because it is the form a
-    // model reaches for by default and the one that carries prose members without HD-002's quoting
+    // model reaches for by default and the one that carries prose members without the quoting
     // problem — and anything indented that is NOT a block sequence is reported rather than dropped.
     const block = [];
     let stray = 0;
@@ -322,13 +322,13 @@ export function parseContract(md, spec = SCOPE_CONTRACT) {
   const { meta, body } = splitFrontmatter(md);
   const tables = parseTables(body);
   const out = { ...meta };
-  // Frontmatter-level diagnostics (HD-003) and table-level ones (HD-001) share one channel, so a
+  // Frontmatter-level diagnostics and table-level ones share one channel, so a
   // reader asks `unreadableReason()` once and cannot check for one while missing the other.
   const unreadable = [...(meta[UNREADABLE] || [])];
   delete out[UNREADABLE];
   for (const [field, heading] of Object.entries(spec.tables || {})) {
     if (tables[heading]) { out[field] = tables[heading]; continue; }
-    // HD-001. The field is absent — but is it absent because nobody declared it, or because the
+    // The field is absent — but is it absent because nobody declared it, or because the
     // author declared it somewhere this parser does not look? Those are opposite facts and the
     // old code returned the same thing for both. A table carrying this field's signature columns,
     // under a heading the spec does not claim, is the second case.
@@ -351,7 +351,7 @@ export function parseContract(md, spec = SCOPE_CONTRACT) {
  * The one-line reason a contract could not be read, or null when it read cleanly.
  *
  * Exported so every consumer asks the same question the same way. A reader that skips this is
- * back to treating "I could not see your table" as "you declared no table", which is HD-001.
+ * back to treating "I could not see your table" as "you declared no table" — the whole defect class.
  * @param {Object|null} contract - A parsed contract (or a `readContract()` result's `.contract`).
  * @returns {string|null} A human-readable failure, or null if the contract parsed cleanly.
  */

package/skills/tech-lead/scripts/lib/is-main.mjs

@@ -1,6 +1,6 @@
 // isMain — "was this module executed directly, or imported?"
 //
-// WHY THIS FILE EXISTS (measured on the SDD harness benchmark, not theorized).
+// WHY THIS FILE EXISTS (observed, not theorized).
 //
 // Eighteen of this plugin's scripts and hooks decided whether to do anything at all with:
 //
@@ -12,22 +12,21 @@
 //
 //  1. A SYMLINKED DIRECTORY ANYWHERE IN THE PATH. Node resolves `import.meta.url` through
 //     symlinks; `process.argv[1]` is the string as typed. On macOS `/var` is a symlink to
-//     `/private/var`, so EVERY path under the system temp directory mismatches — which is how
-//     the benchmark installs this plugin (`/var/folders/…/package`). nvm, pnpm's content store,
+//     `/private/var`, so EVERY path under the system temp directory mismatches — which is where
+//     an npm-packed install lands (`/var/folders/…/package`). nvm, pnpm's content store,
 //     Homebrew and any symlinked checkout do the same thing on every platform.
 //
 //  2. A SPACE OR OTHER URL-RESERVED CHARACTER IN THE PATH. `import.meta.url` is percent-encoded
 //     (`My%20Plugins`); the template literal is not (`My Plugins`). So a plugin installed under
 //     `~/Library/Application Support/…` or any directory with a space in its name mismatches too.
 //
-// WHAT THAT COST, measured. `init-run.mjs` is GATE L0.1 — the orchestrator's mandatory first tool
-// call, the script that writes the run receipt everything else is derived from. Under a `/var`
-// path it exited 0 with empty stdout and wrote no receipt. The orchestrator could not distinguish
-// "the run opened" from "nothing happened", and in the benchmark's F4 handoff rows it spent
-// 82–120 turns before its first write doing forensics on its own bootstrap — retrying the script
-// six ways, hitting five separate permission refusals trying to capture an exit code, and finally
-// running `find /` to look for its own skill. Session B cost $4.57–$10.36 and recovered 0/3 of
-// the gap while the artifact it needed sat on disk the entire time.
+// WHAT THAT COSTS. `init-run.mjs` is GATE L0.1 — the orchestrator's mandatory first tool call, the
+// script that writes the run receipt everything else is derived from. Under a `/var` path it
+// exited 0 with empty stdout and wrote no receipt. The orchestrator then cannot distinguish "the
+// run opened" from "nothing happened", and burns its budget on forensics against its own
+// bootstrap — retrying the script several ways, hitting permission refusals trying to capture an
+// exit code, and finally searching the filesystem for its own skill — while the artifact it needs
+// sits on disk the entire time.
 //
 // The same guard sits in seven hooks, including `gate-zerowork`, `safety-spine` and
 // `sandbox-guard`. This project's stated organising idea is that "every invariant that matters
@@ -36,7 +35,7 @@
 // an enforcement layer can have, because it is indistinguishable from working.
 //
 // THE FIX. Compare resolved URL to resolved URL, using `pathToFileURL` so encoding matches and
-// `realpathSync` so symlinks match. `tests/structural/11-is-main.mjs` asserts that no file
+// `realpathSync` so symlinks match. The structural suite asserts that no file
 // reintroduces the fragile form, and actually executes each entry point through a symlinked
 // directory AND through a directory with a space in its name to prove the guard holds — because
 // this defect was invisible to every test that invoked scripts by their real path.

package/skills/tech-lead/scripts/lib/paths.mjs

@@ -2,17 +2,18 @@
 //
 // WHY THIS FILE EXISTS (measured by grepping the shipped tree, not theorized).
 //
-// The two storage roots were hard-coded in ~90 files, in TWO syntaxes that no single search finds:
+// The two storage roots were hard-coded across the tree in TWO syntaxes that no single search
+// finds:
 //
-//     "docs/shapeup-sdlc/<slug>/scopes/..."            568 string literals
-//     join(cwd, "docs", "shapeup-sdlc", slug, ...)      48 segment-built sites
+//     "docs/shapeup-sdlc/<slug>/scopes/..."            spelled string literals
+//     join(cwd, "docs", "shapeup-sdlc", slug, ...)      segment-built sites
 //
 // A find/replace over the first set leaves the second silently pointing at the old root. That is
 // the failure mode this project keeps rediscovering: a change that appears complete, produces no
 // error, and is wrong — `lib/is-main.mjs` (a guard duplicated 18 times, inert under a symlink) and
 // `lib/argv.mjs` (`rNaN-a1.json` written with exit 0) are the same defect at different layers. The
 // remedy each time is to give the duplicated thing one home and add a test that no one may bypass
-// it (`tests/structural/45-paths.mjs`, mirroring #11a).
+// it — asserted by the structural suite.
 //
 // It also removes a live ambiguity. `gate-answers.mjs` resolved three candidate paths and
 // `sandbox-guard.mjs` built a fourth independently; the same filename meant "my personal lane" at
@@ -21,7 +22,7 @@
 // TIER DISCIPLINE, restated here because this is where it becomes mechanical:
 //   SHARED (committed) — prose a teammate reads: shaping, spec, contracts, requirements, report.
 //   LOCAL (gitignored) — run state, envelopes, verification artifacts, machine policy.
-// See docs/design/adr/0001-consumer-file-organization.md.
+// See ADR-0001 (consumer file organization).
 //
 // Zero dependencies. Pure — every function takes `cwd` and returns a path; nothing here touches
 // the filesystem, so importing this module can never have a side effect.
@@ -122,10 +123,11 @@ export const report = (cwd, slug) => join(sharedRoot(cwd, slug), "REPORT.md");
 export const knowledgeBaseDir = (cwd) => join(sharedDir(cwd), "knowledge-base");
 /** One worker's coaching file. */
 export const knowledgeBase = (cwd, skill) => join(knowledgeBaseDir(cwd), `${skill}.md`);
-/** Migration bookkeeping — committed by necessity (ADR-0001 exception 3). */
-export const harnessVersion = (cwd) => join(sharedDir(cwd), ".harness-version");
-/** Applied-migration record — committed by necessity (ADR-0001 exception 3). */
-export const harnessMigrations = (cwd) => join(sharedDir(cwd), ".harness-migrations");
+// `.harness-version` and `.harness-migrations` were resolved here, committed by necessity as
+// ADR-0001's third exception. Their sole writer was the upgrade path's data-migration runner, which
+// has been removed; no code in the plugin has written either file since. The helpers went with
+// them rather than remaining as resolvable paths to files nothing produces — a path helper is a
+// claim that the file is part of the layout, and this one would have been false.
 
 // ---------------------------------------------------------------------------
 // LOCAL — run state
@@ -167,8 +169,6 @@ export const spikesDir = (cwd, slug) => join(localRoot(cwd, slug), "spikes");
 export const traceDir = (cwd, slug) => join(localRoot(cwd, slug), "trace");
 /** The discovered-task ledger every discovery flow appends to. */
 export const discoveryLedger = (cwd, slug) => join(localRoot(cwd, slug), "discovery", "ledger.md");
-/** Queued worker escalations awaiting adjudication. */
-export const escalatesDir = (cwd, slug) => join(localRoot(cwd, slug), "escalates");
 /**
  * Adjudicated decisions, read back by `compile-order` as binding precedent.
  *
@@ -191,6 +191,8 @@ export const workingDir = (cwd, slug) => join(localRoot(cwd, slug), "working");
 
 /** The pointer the sandbox guard reads to answer "which scope is checked out?". */
 export const activeScope = (cwd) => join(localDir(cwd), "active-scope");
+/** The pointer the sandbox guard reads to answer "which order is executing?". */
+export const activeOrder = (cwd) => join(localDir(cwd), "active-order");
 /** Hook receipts — one row per evaluation, so `allow` carries evidence. */
 export const decisions = (cwd) => join(localDir(cwd), "decisions.jsonl");
 /** Human-authored safety escape hatch. LOCAL so no PR can widen another machine's envelope. */
@@ -266,13 +268,13 @@ export const globLocal = (slug, ...parts) => [LOCAL, slug, ...parts].join("/");
  * A deliverable glob, POSIX-separated for the same reason as {@link globLocal}.
  * @param {string} slug - Feature slug.
  * @param {...string} parts - Glob segments under the feature's shared root.
- * @returns {string} e.g. `docs/shapeup-sdlc/checkout/scopes/*.json`.
+ * @returns {string} e.g. `shapeup/checkout/scopes/*.md`.
  */
 export const globShared = (slug, ...parts) => [SHARED, slug, ...parts].join("/");
 
 /**
  * The coaching file a coachable worker reads, as a repo-relative path for the WorkOrder payload.
  * @param {string} skill - Worker name (task-executor | ba-pitch-analyzer | qa-edge-hunter).
- * @returns {string} e.g. `docs/shapeup-sdlc/knowledge-base/task-executor.md`.
+ * @returns {string} e.g. `shapeup/knowledge-base/task-executor.md`.
  */
 export const relKnowledgeBase = (skill) => [SHARED, "knowledge-base", `${skill}.md`].join("/");