@jaybeeuu/agent-cortex 2.1.0 → 2.2.0

package/scripts/lib/release-gates.mjs

@@ -16,9 +16,21 @@ const GITHUB_ACTIONS_BOT = "github-actions[bot]";
 const CHANGESET_PATH = /^\.changeset\/[^/]+\.md$/;
 const CHANGESET_EXEMPT_PATHS = new Set([".changeset/README.md"]);
 
+/** @typedef {{ status: string, path: string }} NameStatusEntry */
+
+/**
+ * @typedef {object} ChangesetGateInput
+ * @property {NameStatusEntry[]} changes
+ * @property {string[]} labels
+ * @property {string} headRef
+ * @property {string} actor
+ */
+
 /**
  * Parse `git diff --name-status` output into `{ status, path }` entries, where
  * `status` is the single-letter change type and `path` is the new path.
+ * @param {string} output
+ * @returns {NameStatusEntry[]}
  */
 export function parseNameStatus(output) {
   return output
@@ -26,7 +38,7 @@ export function parseNameStatus(output) {
     .filter((line) => line.trim() !== "")
     .map((line) => {
       const [status, ...paths] = line.split("\t");
-      return { status: status.charAt(0), path: paths.at(-1) };
+      return { status: status.charAt(0), path: /** @type {string} */ (paths.at(-1)) };
     });
 }
 
@@ -34,6 +46,8 @@ export function parseNameStatus(output) {
  * Decide whether a pull request may skip adding a changeset. Exempt only the
  * Version Packages PR and PRs explicitly labelled `no-publish`; every other PR
  * must add its own changeset.
+ * @param {ChangesetGateInput} input
+ * @returns {{ ok: boolean, reason: string }}
  */
 export function evaluateChangesetGate({ changes, labels, headRef, actor }) {
   if (headRef.startsWith(VERSION_PACKAGES_HEAD_REF) || actor === GITHUB_ACTIONS_BOT) {
@@ -51,11 +65,17 @@ export function evaluateChangesetGate({ changes, labels, headRef, actor }) {
 /**
  * Resolve the command changesets/action should exec for publishing, based on
  * the labels of the PR merged for the pushed commit.
+ * @param {string[]} labels
+ * @returns {string}
  */
 export function resolvePublishCommand(labels) {
   return labels.includes(NO_PUBLISH_LABEL) ? NO_PUBLISH_COMMAND : PUBLISH_COMMAND;
 }
 
+/**
+ * @param {string} path
+ * @returns {boolean}
+ */
 function isChangeset(path) {
   return CHANGESET_PATH.test(path) && !CHANGESET_EXEMPT_PATHS.has(path);
 }

package/scripts/lib/skill-frontmatter.mjs

@@ -33,6 +33,8 @@ const SKIPPED_DIRS = new Set([".git", "node_modules"]);
  * Return the YAML text between the leading `---` delimiters, or null when the
  * document has no frontmatter block. Mirrors PI's extraction step, including
  * newline normalisation and BOM stripping.
+ * @param {string} content
+ * @returns {string | null}
  */
 function extractYaml(content) {
   const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
@@ -44,7 +46,13 @@ function extractYaml(content) {
   return normalized.slice(4, endIndex);
 }
 
-/** True when `value` is a string with at least one non-whitespace character. */
+/**
+ * True when `value` is a string with at least one non-whitespace character.
+ * `yaml`'s `parse` is typed `any`, so the frontmatter values it yields are
+ * taken as `unknown` here and narrowed by this typeof guard.
+ * @param {unknown} value
+ * @returns {value is string}
+ */
 function isNonEmptyString(value) {
   return typeof value === "string" && value.trim() !== "";
 }
@@ -61,6 +69,7 @@ export function validateSkillFrontmatter(content) {
     return ["frontmatter block is missing (expected '---' delimiters)"];
   }
 
+  /** @type {unknown} */
   let frontmatter;
   try {
     frontmatter = parse(yamlText);
@@ -73,23 +82,31 @@ export function validateSkillFrontmatter(content) {
     return ["frontmatter is not a YAML mapping of name/description fields"];
   }
 
+  // The guard above establishes a non-null, non-array object, so the YAML
+  // mapping's fields are readable as unknown values.
+  const fields = /** @type {Record<string, unknown>} */ (frontmatter);
   const errors = [];
-  if (!isNonEmptyString(frontmatter.name)) {
+  if (!isNonEmptyString(fields.name)) {
     errors.push("frontmatter is missing a non-empty name");
   }
-  if (!isNonEmptyString(frontmatter.description)) {
+  if (!isNonEmptyString(fields.description)) {
     errors.push("frontmatter is missing a non-empty description");
-  } else if (frontmatter.description.length > MAX_DESCRIPTION_LENGTH) {
+  } else if (fields.description.length > MAX_DESCRIPTION_LENGTH) {
     errors.push(
-      `description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${frontmatter.description.length})`,
+      `description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${fields.description.length})`,
     );
   }
 
   return errors;
 }
 
-/** Recursively collect every SKILL.md below `dir`, skipping vendored trees. */
+/**
+ * Recursively collect every SKILL.md below `dir`, skipping vendored trees.
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
 async function findSkillFiles(dir) {
+  /** @type {string[]} */
   const found = [];
   let entries;
   try {

package/scripts/lib/skill-links.mjs

@@ -0,0 +1,52 @@
+// Flat-layout link rewriting for installed skills.
+//
+// Skills are authored in a grouped tree (skills/<group>/<name>/), so a handoff to
+// a neighbouring skill is written against that tree — ../../style/style-code/SKILL.md.
+// The pi installer preserves the grouping, so those paths resolve as written. The
+// Claude Code plugin cannot: its scan expects skills/<name>/SKILL.md directly under
+// skills/, so bin/installers/claude.mjs copies every skill flat and the authored path
+// loses its group segment. Rewriting the link at copy time keeps one authored source
+// that is correct in the repo and correct in both install layouts.
+//
+// Zero dependencies so it runs on the CI Node (20) and local Node alike.
+//
+// Known limits. The rewrite keys off the first path segment that matches a skill name,
+// so it cannot tell a skill directory from a same-named directory elsewhere: a target
+// like ../../../docs/plan/x.md (plan is a skill name) becomes ../plan/x.md, pointing at
+// a file that does not exist in the flattened install. An angle-bracket target such as
+// <plan> loses its brackets and gains a ../ for the same reason. Neither shape exists in
+// the corpus today — links only ever enter skills/ trees with plain relative targets —
+// so this is a constraint on new links, not a live bug. A non-md file that links back
+// into a skill tree has the same caveat: only markdown under a skill directory is
+// transformed.
+
+const LINK_RE = /\]\(([^)\s]+)\)/g;
+const NON_RELATIVE_RE = /^(?:[a-z][a-z0-9+.-]*:|\/|#)/i;
+
+/**
+ * Rewrite relative markdown links that traverse a skill directory into flat sibling
+ * references, so they resolve after the grouped tree is flattened.
+ *
+ * `../../style/style-code/SKILL.md` → `../style-code/SKILL.md`. Links that do not
+ * traverse a skill directory (`./EXAMPLES.md`, `../tdd/tests.md`) are left alone, as
+ * are schemes, absolute paths, and anchors.
+ *
+ * @param {string} content  Markdown file content
+ * @param {Set<string> | string[]} skillNames  Every skill name in the install
+ * @returns {string}
+ */
+export function flattenSkillLinks(content, skillNames) {
+  const names = skillNames instanceof Set ? skillNames : new Set(skillNames);
+  /** @param {string} match @param {string} target @returns {string} */
+  return content.replace(LINK_RE, (match, target) => {
+    if (NON_RELATIVE_RE.test(target)) return match;
+    const segments = target.split("/");
+    /** @param {string} segment @returns {boolean} */
+    const isSkill = (segment) => names.has(segment);
+    const skillAt = segments.findIndex(isSkill);
+    // First path segment: a same-directory link, already correct when flattened.
+    if (skillAt <= 0) return match;
+    const rest = segments.slice(skillAt + 1);
+    return `](../${[segments[skillAt], ...rest].join("/")})`;
+  });
+}

package/scripts/lib/verify-worker-tree.mjs

@@ -26,11 +26,20 @@ import { fileURLToPath } from "node:url";
 const execFileAsync = promisify(execFile);
 const SELF = fileURLToPath(import.meta.url);
 
+/**
+ * @param {string} worktree
+ * @param {string[]} args
+ * @returns {Promise<string>}
+ */
 async function git(worktree, args) {
   const { stdout } = await execFileAsync("git", args, { cwd: worktree });
   return stdout.trim();
 }
 
+/**
+ * @param {string} porcelain
+ * @returns {number}
+ */
 function countPaths(porcelain) {
   return porcelain.split("\n").filter((line) => line.trim() !== "").length;
 }
@@ -39,6 +48,8 @@ function countPaths(porcelain) {
  * Check that a worker delivered: clean worktree and at least one commit ahead
  * of `base`. Returns the reasons it failed, so the caller can surface them
  * instead of guessing why a stage did not advance.
+ * @param {{ worktree: string, base: string }} options
+ * @returns {Promise<{ ok: boolean, reasons: string[], commitsAhead: number }>}
  */
 export async function verifyWorkerTree({ worktree, base }) {
   const reasons = [];
@@ -58,7 +69,12 @@ export async function verifyWorkerTree({ worktree, base }) {
 
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
+/**
+ * @param {string[]} argv
+ * @returns {Record<string, string | true>}
+ */
 function parseFlags(argv) {
+  /** @type {Record<string, string | true>} */
   const flags = {};
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -75,6 +91,11 @@ function parseFlags(argv) {
   return flags;
 }
 
+/**
+ * @param {Record<string, string | true>} flags
+ * @param {string} name
+ * @returns {string}
+ */
 function required(flags, name) {
   const value = flags[name];
   if (typeof value !== "string" || value === "") {
@@ -84,6 +105,10 @@ function required(flags, name) {
   return value;
 }
 
+/**
+ * @param {string[]} argv
+ * @returns {Promise<void>}
+ */
 async function main(argv) {
   const flags = parseFlags(argv);
   const verdict = await verifyWorkerTree({

package/scripts/resolve-publish-command.mjs

@@ -4,6 +4,10 @@
 // stay a plain `pnpm <script>` token pair.
 import { resolvePublishCommand } from "./lib/release-gates.mjs";
 
+/**
+ * @param {string} raw
+ * @returns {string[]}
+ */
 function readLabels(raw) {
   try {
     return JSON.parse(raw);

package/skills/engineering/design-an-interface/SKILL.md

@@ -93,10 +93,10 @@ description: "Generate multiple radically different interface designs for a modu
 - [ ] Phase 4 complete: comparison shared and divergence highlighted
 - [ ] Phase 5 complete: candidate synthesized with user input
 
-## Cross-skill references
+## See Also
 
-- `improve-codebase-architecture` invokes this skill for its multi-design step (step 5 of its workflow).
-- Run `grill-with-docs` when the module's domain terminology is unsettled — design names should match the ubiquitous language.
+- [improve-codebase-architecture](../improve-codebase-architecture/SKILL.md) — runs this skill for its multi-design step; load it when the designs feed a deepening decision.
+- [grill-with-docs](../grill-with-docs/SKILL.md) — load when the module's domain terminology is unsettled, so design names match the ubiquitous language.
 
 ## Examples
 

package/skills/engineering/grill-with-docs/SKILL.md

@@ -53,12 +53,10 @@ description: "Grilling session that challenges your plan against the existing do
 - **`CONTEXT.md` is a glossary and nothing else** — the vocabulary stays stable while the design churns around it.
 - **ADRs are rare** — the three criteria keep the ADR log a history of decisions, not a diary.
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use |
-|---|---|
-| A design interview without touching project docs | `grill-me` |
-| A justified recommendation on architecture or technology | `technical-direction` |
+- [grill-me](../../productivity/grill-me/SKILL.md) — the same interview without the doc updates, when no CONTEXT.md or ADR work is wanted.
+- [technical-direction](../technical-direction/SKILL.md) — continues into a justified recommendation once the terminology has settled.
 
 ## Examples
 

package/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -76,11 +76,12 @@ A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a sma
 - [ ] Phase 3 complete: at least two radically different designs presented and compared, with a recommendation given
 - [ ] Phase 4 complete: refactor bead created via `create-task` and the bead ID reported
 
-## Cross-skill references
+## See Also
 
-- Run `design-an-interface` at step 5 for a guided parallel sub-agent design flow.
-- Run `create-task` at step 7 to file the refactor bead.
-- Run `grill-with-docs` when the deepened module's terminology is unsettled — interface names should match the ubiquitous language.
+- [design-an-interface](../design-an-interface/SKILL.md) — step 5 hands the deep-module redesign to its parallel design flow.
+- [create-task](../../planning/create-task/SKILL.md) — step 7 files the refactor as a bead; never call `bd create` directly.
+- [grill-with-docs](../grill-with-docs/SKILL.md) — load when the deepened module's terminology is unsettled.
+- [style-code](../../style/style-code/SKILL.md) — load when the deepened module needs the naming and boundary conventions it will ship with.
 
 ## Examples
 

package/skills/engineering/tdd/SKILL.md

@@ -91,15 +91,13 @@ After all tests pass, run `style-code` to guide the refactoring shape:
 | "This is too simple for TDD" | The simplest changes often have the most hidden assumptions. TDD surfaces them early. |
 | "I already know what the implementation looks like" | Then write the test first to prove it. If the test forces a different interface, the implementation was wrong. |
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| Test-writing conventions (assertions, mocking, structure) | `style-tests` |
-| Code-level style and conventions | `style-code` |
-| Domain terminology for test names and module boundaries | `grill-with-docs` |
+- [style-tests](../../style/style-tests/SKILL.md) — load before writing the first test; it owns assertion strategy, mock discipline, and test-data construction.
+- [style-code](../../style/style-code/SKILL.md) — load at the refactor step for naming and module boundaries.
+- [grill-with-docs](../grill-with-docs/SKILL.md) — load when domain vocabulary is unsettled, so test names and seams use the project's own language.
 
-Reference docs bundled with this skill: `tests.md`, `mocking.md`, `deep-modules.md`, `interface-design.md`, `refactoring.md`.
+Bundled reference docs: `tests.md`, `mocking.md`, `deep-modules.md`, `interface-design.md`, `refactoring.md`.
 
 ## Examples
 

package/skills/engineering/technical-direction/SKILL.md

@@ -54,12 +54,12 @@ Act as a pragmatic, challenging staff engineer: constructive, direct, and eviden
 - **Challenge is the deliverable.** The value of a direction session is the assumptions it surfaces and kills. Optimising for agreement produces a recommendation nobody tested.
 - **Every recommendation carries its tradeoffs.** A choice without documented tradeoffs, revisit triggers, and validation signals cannot be revisited intelligently later.
 
-## Cross-skill references
+## See Also
 
-- `write-a-prd` produces the input brief when no PRD exists yet.
-- `grill-with-docs` sharpens contested terminology and stress-tests the memo against domain docs.
-- `design-an-interface` structures the option-generation step when the decision is about interface shape.
-- `style-documentation` governs the memo's what/whether criteria before writing.
+- [write-a-prd](../../planning/write-a-prd/SKILL.md) — load when the decision needs a requirements brief that does not exist yet.
+- [grill-with-docs](../grill-with-docs/SKILL.md) — load when the contested point is vocabulary rather than technology.
+- [design-an-interface](../design-an-interface/SKILL.md) — load when the decision is interface shape and option generation needs structure.
+- [style-documentation](../../style/style-documentation/SKILL.md) — load to decide whether the decision memo gets written at all.
 
 ## Examples
 

package/skills/planning/classify-bead/REFERENCE.md

@@ -7,13 +7,13 @@ truth for the deterministic tiers; this document mirrors it for verification.
 
 | Tier | `source` | Evidence | Applies the label? |
 |---|---|---|---|
-| 1 | `label` | An `implementation-type:afk` or `implementation-type:hitl` label is already present | no — it is already there |
+| 1 | `label` | An `execution:afk` or `execution:hitl` label is already present | no — it is already there |
 | 2 | `type-field` | The legacy `## Type` section in the bead body declares `AFK`/`HITL` (block or inline form, case-insensitive) | yes |
 | 3 | `heuristic` | A conservative natural-language signal (below) | yes |
 | 4 | *(none)* | Nothing deterministic matched → `escalate: true`; a small/cheap model applies the rubric | after the model decides |
 
-When both `implementation-type` labels are present, AFK wins — matching the
-pre-existing skill wording, which checks `implementation-type:afk` first.
+When both `execution` labels are present, AFK wins — matching the
+pre-existing skill wording, which checks `execution:afk` first.
 
 The classifier runs `bd show <id> --json` and `bd tag <id> <label>`; it never
 re-reads prose from the rendered `bd show` output.

package/skills/planning/classify-bead/SKILL.md

@@ -1,27 +1,27 @@
 ---
 name: classify-bead
-description: Classify a bead as AFK or HITL and apply the implementation-type label. Use when a bead is missing its implementation-type label, when picking up a bead to work on, or when any skill creates a new bead.
+description: Classify a bead as AFK or HITL and apply its `execution` label. Use when a bead is missing its execution label, when picking up a bead to work on, or when any skill creates a new bead.
 ---
 
 # Classify Bead
 
-Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as an `implementation-type` label. A deterministic classifier settles the common cases; only genuine rubric judgement reaches a model.
+Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as an `execution` label (`execution:afk` or `execution:hitl`). A deterministic classifier settles the common cases; only genuine rubric judgement reaches a model.
 
 ## When to use
 
-- A bead is missing its `implementation-type` label and you are about to pick it up.
+- A bead is missing its `execution` label and you are about to pick it up.
 - A skill has just created a new bead and needs it classified before claiming or scheduling.
 - You are unsure of a bead's classification and want to resolve it deterministically.
 
 ## When NOT to use
 
-- The bead already carries an `implementation-type` label — check `bd label list <id>` before invoking, and never re-classify a labelled bead.
+- The bead already carries an `execution` label — check `bd label list <id>` before invoking, and never re-classify a labelled bead.
 - You are creating a new task — `create-task` classifies internally; do not spawn this skill separately.
 - The work item is not a bead (e.g. a Jira ticket or plain code task) — use `write-a-ticket` or start the work directly.
 
 ## Invocation
 
-Run the deterministic classifier first. It resolves the existing label, the legacy `## Type` field, and explicit heuristic signals without a model call:
+Run the deterministic classifier first. It resolves the existing `execution` label, the legacy `## Type` field, and explicit heuristic signals without a model call:
 
 ```bash
 # Run from the TARGET project's directory — bd resolves its beads DB from cwd.
@@ -34,11 +34,11 @@ node <skill-scripts>/classify-bead.mjs <bead-id>
 
 `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded — it varies by harness and install location, so never hardcode one harness's path. Only run inline when no task-spawning capability exists in the current environment.
 
-**Callers should run the classifier themselves before spawning this subagent.** If `implementation-type` is already present, or the classifier resolves the bead, there is no subagent call to make.
+**Callers should run the classifier themselves before spawning this subagent.** If an `execution` label is already present, or the classifier resolves the bead, there is no subagent call to make.
 
 ## Workflow
 
-1. **Check for an existing label.** `bd label list <id>` — `implementation-type:afk` present → **AFK**; `implementation-type:hitl` present → **HITL**. Stop.
+1. **Check for an existing label.** `bd label list <id>` — `execution:afk` present → **AFK**; `execution:hitl` present → **HITL**. Stop.
 
 2. **Run the deterministic classifier.** `node <skill-scripts>/classify-bead.mjs <id>`. A resolved classification is already tagged; stop and report it.
 
@@ -51,7 +51,7 @@ node <skill-scripts>/classify-bead.mjs <bead-id>
 
    **AFK** — otherwise: the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
 
-4. **Apply the label.** `bd tag <id> implementation-type:afk` (or `:hitl`). The classifier does this for the deterministic tiers; do it yourself only after step 3.
+4. **Apply the label.** `bd tag <id> execution:afk` (or `execution:hitl`). The classifier does this for the deterministic tiers; do it yourself only after step 3.
 
 5. **Return the classification.** Report `AFK` or `HITL` so the calling skill or agent can act on it.
 
@@ -77,11 +77,16 @@ Tier precedence (label → `## Type` → heuristics → rubric), the heuristic s
 - Classification gates automation against human attention: AFK beads feed ralph's autonomous pipeline, HITL beads route to a person. Prefer AFK because human time is the scarce resource, and later review gates still catch agent mistakes.
 - The rubric is deterministic, so most classifications are a lookup. The executable encodes that lookup once, and the model is reserved for beads whose evidence is genuinely ambiguous.
 
+## See Also
+
+- [create-task](../create-task/SKILL.md) — calls this classifier for every bead it creates; the two must agree on label vocabulary.
+- [ralph](../../workflow/ralph/SKILL.md) — reads `bd ready -l execution:afk`; a mislabelled bead is invisible to the pipeline.
+
 ## Verification checklist
 
 - [ ] `bd label list <id>` was checked before any other step.
 - [ ] The deterministic classifier ran before any rubric subagent.
 - [ ] A rubric subagent ran only when the classifier reported `escalate: true`.
 - [ ] The full bead body was read before classifying from first principles.
-- [ ] `bd tag <id> implementation-type:<afk|hitl>` is present afterwards.
+- [ ] `bd tag <id> execution:<afk|hitl>` is present afterwards.
 - [ ] The calling skill or agent received the classification in the report.

package/skills/planning/classify-bead/scripts/classify-bead.mjs

@@ -1,8 +1,9 @@
+// @ts-check
 // Deterministic bead classifier — resolves an AFK/HITL classification from
 // evidence already present on a bead before any model judgement is spent.
 //
 // Tier order (see skills/planning/classify-bead/SKILL.md):
-//   1. implementation-type label   — an existing decision is authoritative
+//   1. execution label              — an existing decision is authoritative
 //   2. legacy ## Type field        — back-compat with pre-label beads
 //   3. conservative heuristics     — explicit natural-language signals only
 //   4. escalate                    — hand to the rubric (small/cheap model)
@@ -24,8 +25,8 @@ import { pathToFileURL } from 'node:url';
  * @property {boolean} escalate                      True when model judgement is required (tier 4).
  */
 
-const AFK_LABEL = 'implementation-type:afk';
-const HITL_LABEL = 'implementation-type:hitl';
+const AFK_LABEL = 'execution:afk';
+const HITL_LABEL = 'execution:hitl';
 
 // Heuristic signals are deliberately conservative: they only fire on explicit
 // natural-language phrasing that maps directly onto the rubric's criteria.
@@ -94,7 +95,7 @@ function extractTypeField(description) {
 }
 
 /**
- * Resolve a bead's implementation type from the evidence it already carries,
+ * Resolve a bead's execution class from the evidence it already carries,
  * without spending a model call.
  *
  * @param {{ labels?: string[], description?: string }} bead

package/skills/planning/create-task/REFERENCE.md

@@ -1,15 +1,16 @@
 # Create Task — Reference
 
-Detail behind `skills/planning/create-task/SKILL.md`. The script (`scripts/create-chores.ts`) is the source of truth for this contract; this document mirrors it for verification.
+Detail behind `skills/planning/create-task/SKILL.md`. The script (`scripts/create-chores.mjs`) is the source of truth for this contract; this document mirrors it for verification.
 
 ## Script invocation
 
 ```
-tsx create-chores.ts --parent <bead-id> [--priority <0-4>]
+node <skill-scripts>/create-chores.mjs --parent <bead-id> [--priority <0-4>]
 ```
 
 - Reads `<skill>/pipeline.json`; creates each stage chore via `bd create` and wires dependencies via `bd dep add`.
 - Prints a JSON object mapping each stage ID to its chore bead ID, plus `featurePrReview` for the PR gate.
+- Expands a bead that already exists — it never creates a parent. It is also not idempotent: running it against a bead that already has stage chores creates a second chain, so callers check for existing `stage:*` children first (ralph's expansion guard).
 
 ## Stage chore beads
 
@@ -24,10 +25,58 @@ One per stage in `pipeline.json` (currently `code`, `verify`, `review`, `documen
 
 - **Type**: `task`
 - **Title**: `[<parent-id>] PR Review and Merge`
-- **Labels**: `implementation-type:hitl`, `lifecycle:feature-pr` — exactly one `implementation-type` label. The gate declares its own labels, so the script passes `--no-inherit-labels` and it never picks up the parent's `implementation-type:afk`. Stage chores do **not** opt out; they keep inheriting `:afk`.
+- **Labels**: `execution:hitl`, `lifecycle:feature-pr` — exactly one `execution` label. The gate declares its own labels, so the script passes `--no-inherit-labels` and it never picks up the parent's `execution:afk`. Stage chores do **not** opt out; they keep inheriting `execution:afk` from the parent.
+- **Parent contract**: the parent must carry `execution:afk`. Stage chores inherit the parent's labels, so a parent labelled `execution:hitl` (or unlabelled) produces a chore tree that no executor routes. The script does not classify — it only checks that it was given a parent ID.
 - **Dependencies**: `parent-child` to the parent bead; `blocks` on the final document stage chore (`document`, falling back to the last stage in `pipeline.json`).
 - **Purpose**: human review of the agent PR (agent branch → feature branch) before the feature closes.
 
+## Hierarchy
+
+Ownership is `--parent` at create time; ordering is `bd dep add`. The full shape for a
+workstream, from container down to stage chore:
+
+| Level | Type | Execution | Created by | Ownership |
+|---|---|---|---|---|
+| Feature | `feature` | `execution:hitl` | `create-task` step 5 | — |
+| Planning bead ("Plan: <feature title>") | `task` | `execution:hitl` | `create-task` step 6 | `--parent <feature>` |
+| Impl task (one per deliverable) | `task` | `execution:afk` | `create-task` step 6 | `--parent <feature>` |
+| Stage chore | `chore` | inherited `execution:afk` | `create-chores.mjs` | `--parent <impl-task>` |
+| PR gate | `task` | `execution:hitl` | `create-chores.mjs` | `--parent <impl-task>`, `--no-inherit-labels` |
+
+Stage chores come from running `create-chores.mjs` once per impl task (`--parent <impl-task>`),
+never against the feature itself — its parent must carry `execution:afk`.
+
+Every impl task depends on the planning bead (`bd dep add <impl-task> <planning-bead>`), so
+`bd ready` withholds them until planning closes. Nothing aggregates a child's execution class
+onto its parent: the container is human-owned because a person decides when it is done, and
+each child states the class of its own work.
+
+### Planning bead body
+
+Cold-start ready — another person picks it up with no chat history:
+
+```markdown
+## What and why
+
+The deliverable this feature produces and the problem it solves.
+
+## Decisions already made
+
+- Decision — rationale
+
+## Open questions / risks
+
+- Question — who answers it
+
+## References
+
+- Bead IDs, files, docs consulted
+
+## Acceptance Criteria
+
+- [ ] The user confirms planning is sufficient for this feature.
+```
+
 ## Current pipeline stages
 
 | id | title | dependsOn |