@jaybeeuu/agent-cortex 1.40.0 → 1.41.1

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

@@ -0,0 +1,85 @@
+# classify-bead reference
+
+Detail behind `SKILL.md`. The executable `scripts/classify-bead.mjs` is the source of
+truth for the deterministic tiers; this document mirrors it for verification.
+
+## Tier precedence
+
+| 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 |
+| 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.
+
+The classifier runs `bd show <id> --json` and `bd tag <id> <label>`; it never
+re-reads prose from the rendered `bd show` output.
+
+## Heuristic signals
+
+Heuristics only fire on explicit phrasing. They are checked in this order,
+mirroring the rubric's "a human is required if any criterion is true" rule.
+
+HITL (human required):
+
+- `requires human`, `human sign-off|approval|judgement|decision`
+- `manual step|action|intervention`
+- `visually review|inspect|verify`
+- `stakeholder sign-off|approval`
+- `credentials|secrets setup|rotation|provisioning`
+- `provisioning` within 40 characters of `infrastructure|infra|server|cluster`
+
+AFK (explicitly no human):
+
+- `no human action|input|review|intervention|judgement`
+
+AFK (machine-checkable acceptance):
+
+- `machine-checkable`
+- `automated test|tests|check|checks|verification`
+
+Anything else escalates. Widening this list trades model calls for
+misclassification risk; only add phrasing that maps directly onto a rubric
+criterion.
+
+Matching is literal, not semantic, and the patterns are not negation-aware —
+"no human approval is required" still matches the HITL tier. The error direction
+is toward HITL, which is visible and correctable, so prefer unambiguous phrasing
+over more patterns.
+
+## CLI
+
+```bash
+node classify-bead.mjs <bead-id> [--dry-run]   # resolve (and tag) one bead
+node classify-bead.mjs --audit [--limit <n>]   # measure the split over recent beads
+```
+
+Run from the target project's directory — `bd` resolves its beads DB from cwd.
+JSON goes to stdout:
+
+- Classification: `{ id, classification, source, reason, escalate, applied, label }`
+- Audit: `{ sampled, bySource, deterministic, needsRubric, deterministicRatio }`
+
+Exit codes: `0` success (including `escalate`, which is a valid outcome), `2`
+usage error, `1` `bd` failure. `BD_PATH` overrides the `bd` executable.
+
+## Measured split
+
+This is the "measure first" number that sizes the win over spawning a subagent.
+Reproduce it against the repo's beads DB:
+
+```bash
+node <skill-scripts>/classify-bead.mjs --audit --limit 100
+```
+
+Measured 2026-09-18 on `agent-cortex`: 78 of the newest 100 beads resolved
+deterministically (77 from an existing label, 1 from a heuristic) and 22 needed
+the rubric. That is the share of classifications that skip the model entirely
+when the caller runs the classifier before spawning a subagent. The sample is
+the newest 100 beads, so the ratio moves as beads are created — re-run the
+command rather than quoting this snapshot. The deterministic rate is higher on
+backlogs labelled at planning time; freshly created beads with neither a label
+nor a `## Type` field lean on the heuristic tier.

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

@@ -5,7 +5,7 @@ description: Classify a bead as AFK or HITL and apply the implementation-type la
 
 # 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.
+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.
 
 ## When to use
 
@@ -21,71 +21,67 @@ Determine whether a bead requires human action (HITL) or can be completed autono
 
 ## Invocation
 
-Run this skill as a background subagent via {{TOOL:task}} so bead content never loads into the calling agent's context. Classification is a rubric lookup, not code generation — a small, cheap model is sufficient. Pass the bead ID and the `bd prime` output; the subagent runs the workflow below and reports back the classification plus the `bd tag` command it applied.
+Run the deterministic classifier first. It resolves the existing label, the legacy `## Type` field, and explicit heuristic signals without a model call:
 
-Only run inline when no task-spawning capability exists in the current environment.
+```bash
+# Run from the TARGET project's directory — bd resolves its beads DB from cwd.
+node <skill-scripts>/classify-bead.mjs <bead-id>
+```
 
-**Callers should check `bd label list <id>` themselves first.** If `implementation-type` is already present, skip spawning this skill entirely — spawning a subagent purely to re-read a label that already exists wastes a full agent call.
+- Output carries `"classification": "afk" | "hitl"` → done. The classifier applied the label; report the classification. Do not spawn a subagent.
+- Output carries `"escalate": true` → no deterministic signal. Spawn this skill as a background subagent via {{TOOL:task}} (a small, cheap model) with the bead ID and the `bd prime` output; the subagent applies the rubric below and tags the bead.
+- `--dry-run` resolves without applying the label. `--audit [--limit <n>]` reports the deterministic-vs-rubric split over recent beads.
 
-## Workflow
-
-1. **Check for an existing label.**
-
-   ```bash
-   bd label list <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.
 
-   - `implementation-type:afk` present → classification is **AFK**. Stop here.
-   - `implementation-type:hitl` present → classification is **HITL**. Stop here.
+**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.
 
-2. **Check the `## Type` field (back-compat).**
+## Workflow
 
-   ```bash
-   bd show <id>
-   ```
+1. **Check for an existing label.** `bd label list <id>` — `implementation-type:afk` present → **AFK**; `implementation-type:hitl` present → **HITL**. Stop.
 
-   Locate the `## Type` section in the bead body. `HITL` or `AFK` (case-insensitive) determines the classification; continue to step 4. This field predates the label system, so treat it as authoritative when present.
+2. **Run the deterministic classifier.** `node <skill-scripts>/classify-bead.mjs <id>`. A resolved classification is already tagged; stop and report it.
 
-3. **Classify from first principles** — only when neither the label nor the `## Type` field is present. Read the full bead body and apply the rubric:
+3. **Apply the rubric** — only when the classifier reports `escalate: true`. Read the full bead body:
 
-   **HITL** — the bead requires a human if at least one of the following is true:
+   **HITL** — a human is required if at least one of the following holds:
    - The outcome cannot be verified by an agent (e.g. visual review, stakeholder sign-off, UX judgement call).
    - A manual action only a human can perform is required (e.g. credential setup, secrets management, external service configuration, infrastructure provisioning outside the codebase).
    - A decision must be made that the agent cannot make unilaterally (e.g. architectural choice between equally valid options, regulatory or legal sign-off).
 
-   **AFK** — the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
-
-4. **Apply the label.**
+   **AFK** — otherwise: the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
 
-   ```bash
-   bd tag <id> implementation-type:afk    # or implementation-type:hitl
-   ```
+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.
 
 5. **Return the classification.** Report `AFK` or `HITL` so the calling skill or agent can act on it.
 
+Tier precedence (label → `## Type` → heuristics → rubric), the heuristic signal list, the CLI contract, and the measured deterministic split are in `REFERENCE.md`.
+
 ## Red Flags
 
-- Classifying a bead without the caller-side `bd label list` check — you either overwrite a recorded decision or waste an agent spawn re-reading a label that already exists.
+- Classifying a bead without the caller-side `bd label list` check — you either overwrite a recorded decision or waste a call re-reading a label that already exists.
+- Spawning the rubric subagent when the classifier returned a classification — the deterministic tier is the point.
 - Defaulting to HITL for a complex task whose acceptance criteria are machine-checkable — complexity alone is not a criterion.
-- Choosing a class without reading the bead body when neither the label nor `## Type` is present.
+- Choosing a class without reading the bead body when the classifier escalated.
 
 ## Common Rationalizations
 
 | Rationalization | Rebuttal |
-|---|---|
 | "This task is complex, so it must be HITL" | Complexity is not a criterion. HITL applies only when a human is genuinely required to complete or verify. |
 | "I'll mark it HITL to be safe" | HITL consumes scarce human attention. Prefer AFK — ralph's review gates still catch agent mistakes. |
-| "The label is probably already there, I'll skip the check" | One `bd label list` command settles it. Skipping it either overwrites a decision or spawns an agent to re-read a label. |
+| "The label is probably already there, I'll skip the check" | One `bd label list` command settles it, and the classifier checks it too. |
+| "Heuristics are good enough for this one" | The classifier uses conservative, explicit signals only. If it escalated, read the body. |
 
 ## Philosophy / rationale
 
-- Classification gates automation against human attention: AFK beads feed ralph's autonomous pipeline, HITL beads are routed to a person. We prefer AFK because human time is the scarce resource, and later review gates still catch agent mistakes — escalate only when completion or verification genuinely requires a human.
-- The rubric is deterministic, so this skill is a lookup rather than deep reasoning — which is why a cheap subagent suffices and the step 1 early exit exists.
+- 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.
 
 ## Verification checklist
 
 - [ ] `bd label list <id>` was checked before any other step.
-- [ ] Classification followed the precedence order: existing label → `## Type` → first-principles rubric.
-- [ ] The full bead body was read before classifying from first principles (step 3).
-- [ ] `bd tag <id> implementation-type:<afk|hitl>` was applied.
-- [ ] The calling skill or agent received the classification in the report.
+- [ ] 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.
+- [ ] The calling skill or agent received the classification in the report.

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

@@ -0,0 +1,292 @@
+// 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
+//   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)
+//
+// Zero dependencies: run with `node classify-bead.mjs <bead-id>`.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+
+/** @typedef {'afk' | 'hitl'} Classification */
+/** @typedef {'label' | 'type-field' | 'heuristic'} ResolutionSource */
+
+/**
+ * @typedef {object} Resolution
+ * @property {Classification | null} classification  Resolved class, or null when the rubric must decide.
+ * @property {ResolutionSource | null} source        Which tier produced the resolution.
+ * @property {string} reason                         Human-readable justification for the resolution.
+ * @property {boolean} escalate                      True when model judgement is required (tier 4).
+ */
+
+const AFK_LABEL = 'implementation-type:afk';
+const HITL_LABEL = 'implementation-type:hitl';
+
+// Heuristic signals are deliberately conservative: they only fire on explicit
+// natural-language phrasing that maps directly onto the rubric's criteria.
+// Anything short of that escalates to the rubric rather than guessing.
+
+// Rubric: a human is required to perform or verify the work.
+const HITL_SIGNALS = [
+  /\brequires? (a )?human\b/i,
+  /\bhuman (sign-?off|approval|judgement|decision)\b/i,
+  /\bmanual (step|action|intervention)\b/i,
+  /\bvisual(ly)? (review|inspect|verify)\b/i,
+  /\bstakeholder (sign-?off|approval)\b/i,
+  /\b(credential|secret)s? (setup|rotation|provisioning)\b/i,
+  /\bprovision(ing)?\b[^.]{0,40}\b(infrastructure|infra|server|cluster)\b/i,
+];
+
+// Rubric: the bead explicitly rules out human involvement.
+const AFK_EXPLICIT_SIGNALS = [
+  /\bno human (action|input|review|intervention|judgement)\b/i,
+];
+
+// Rubric: acceptance criteria an agent can check without a human.
+const AFK_SIGNALS = [
+  /\bmachine-checkable\b/i,
+  /\bautomated (test|tests|check|checks|verification)\b/i,
+];
+
+/** @param {RegExp[]} patterns @param {string} text */
+function matchesAny(patterns, text) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+/**
+ * @param {Classification} classification
+ * @param {ResolutionSource} source
+ * @param {string} reason
+ * @returns {Resolution}
+ */
+function resolved(classification, source, reason) {
+  return { classification, source, reason, escalate: false };
+}
+
+/** @param {string} reason @returns {Resolution} */
+function needsRubric(reason) {
+  return { classification: null, source: null, reason, escalate: true };
+}
+
+/**
+ * Read the legacy `## Type` section out of a bead description.
+ *
+ * Accepts both the block form (`## Type` then a following `AFK`/`HITL` line)
+ * and the inline form (`## Type: AFK`). Returns null when the section is absent
+ * or carries an unrelated value.
+ *
+ * @param {string} description
+ * @returns {Classification | null}
+ */
+function extractTypeField(description) {
+  const inline = description.match(/^[ \t]*#{1,6}[ \t]*Type[ \t]*:[ \t]*(AFK|HITL)\b/im);
+  if (inline) return /** @type {Classification} */ (inline[1].toLowerCase());
+
+  const block = description.match(/^[ \t]*#{1,6}[ \t]*Type[ \t]*\r?\n+[ \t]*(AFK|HITL)[ \t]*(?:\r?\n|$)/im);
+  if (block) return /** @type {Classification} */ (block[1].toLowerCase());
+
+  return null;
+}
+
+/**
+ * Resolve a bead's implementation type from the evidence it already carries,
+ * without spending a model call.
+ *
+ * @param {{ labels?: string[], description?: string }} bead
+ * @returns {Resolution}
+ */
+export function resolveClassification({ labels = [], description = '' }) {
+  if (labels.includes(AFK_LABEL)) return resolved('afk', 'label', `${AFK_LABEL} label already present`);
+  if (labels.includes(HITL_LABEL)) return resolved('hitl', 'label', `${HITL_LABEL} label already present`);
+
+  const typeField = extractTypeField(description);
+  if (typeField) return resolved(typeField, 'type-field', `legacy ## Type field declares ${typeField.toUpperCase()}`);
+
+  // Conservative heuristics: a HITL signal wins over an AFK one, mirroring the
+  // rubric's "a human is required if any criterion is true" rule.
+  if (matchesAny(HITL_SIGNALS, description)) {
+    return resolved('hitl', 'heuristic', 'description states a human-required action or verification');
+  }
+  if (matchesAny(AFK_EXPLICIT_SIGNALS, description)) {
+    return resolved('afk', 'heuristic', 'description explicitly rules out human involvement');
+  }
+  if (matchesAny(AFK_SIGNALS, description)) {
+    return resolved('afk', 'heuristic', 'description states machine-checkable acceptance criteria');
+  }
+
+  return needsRubric('no deterministic signal; rubric judgement required');
+}
+
+/** @param {Classification} classification */
+function labelFor(classification) {
+  return classification === 'afk' ? AFK_LABEL : HITL_LABEL;
+}
+
+/** @typedef {{ label: number, typeField: number, heuristic: number, rubric: number }} SourceCounts */
+
+/**
+ * @typedef {object} AuditSummary
+ * @property {number} sampled
+ * @property {SourceCounts} bySource
+ * @property {number} deterministic     Beads resolved without a model call.
+ * @property {number} needsRubric       Beads that would escalate to the rubric.
+ * @property {number} deterministicRatio deterministic / sampled (0 when empty).
+ */
+
+/**
+ * Measure what share of a bead sample the deterministic tiers resolve. This is
+ * the "measure first" number that sizes the win over spawning a subagent.
+ *
+ * @param {Array<{ labels?: string[], description?: string }>} beads
+ * @returns {AuditSummary}
+ */
+export function auditBeads(beads) {
+  /** @type {SourceCounts} */
+  const bySource = { label: 0, typeField: 0, heuristic: 0, rubric: 0 };
+
+  for (const bead of beads) {
+    const { source } = resolveClassification(bead);
+    if (source === 'label') bySource.label += 1;
+    else if (source === 'type-field') bySource.typeField += 1;
+    else if (source === 'heuristic') bySource.heuristic += 1;
+    else bySource.rubric += 1;
+  }
+
+  const deterministic = bySource.label + bySource.typeField + bySource.heuristic;
+  return {
+    sampled: beads.length,
+    bySource,
+    deterministic,
+    needsRubric: bySource.rubric,
+    deterministicRatio: beads.length === 0 ? 0 : deterministic / beads.length,
+  };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const USAGE =
+  'Usage: node classify-bead.mjs <bead-id> [--dry-run]\n' +
+  '       node classify-bead.mjs --audit [--limit <n>]';
+
+const DEFAULT_AUDIT_LIMIT = 100;
+
+// BD_PATH env override lets machines where bd is not on PATH pin a location.
+const BD_PATH = process.env.BD_PATH || 'bd';
+const execFileAsync = promisify(execFile);
+
+class UsageError extends Error {}
+
+/**
+ * @param {string[]} argv
+ * @returns {{ beadId: string | null, audit: boolean, limit: number, dryRun: boolean, help: boolean }}
+ */
+function parseArgs(argv) {
+  const options = {
+    beadId: /** @type {string | null} */ (null),
+    audit: false,
+    limit: DEFAULT_AUDIT_LIMIT,
+    dryRun: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--audit') {
+      options.audit = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--limit') {
+      const value = Number.parseInt(argv[++i] ?? '', 10);
+      if (!Number.isInteger(value) || value <= 0) throw new UsageError('--limit requires a positive integer');
+      options.limit = value;
+    } else if (arg.startsWith('-')) {
+      throw new UsageError(`unknown option: ${arg}`);
+    } else if (options.beadId) {
+      throw new UsageError(`unexpected argument: ${arg}`);
+    } else {
+      options.beadId = arg;
+    }
+  }
+
+  return options;
+}
+
+/** @type {(args: string[]) => Promise<string>} */
+async function defaultExec(args) {
+  const { stdout } = await execFileAsync(BD_PATH, args, { encoding: 'utf-8' });
+  return stdout;
+}
+
+/**
+ * @param {object} options
+ * @param {string[]} options.argv                      CLI arguments (without node/script).
+ * @param {(args: string[]) => Promise<string>} [options.exec]  bd runner; injectable for tests.
+ * @param {(chunk: string) => void} [options.write]    stdout sink; injectable for tests.
+ * @returns {Promise<number>} process exit code.
+ */
+export async function runCli({ argv, exec = defaultExec, write = (chunk) => process.stdout.write(chunk) }) {
+  const options = parseArgs(argv);
+
+  if (options.help) {
+    write(`${USAGE}\n`);
+    return 0;
+  }
+
+  if (options.audit) {
+    const beads = JSON.parse(
+      await exec(['list', '--all', '--json', '--limit', String(options.limit), '--sort', 'created']),
+    );
+    write(`${JSON.stringify(auditBeads(beads), null, 2)}\n`);
+    return 0;
+  }
+
+  if (!options.beadId) {
+    write(`${USAGE}\n`);
+    return 2;
+  }
+
+  const [bead] = JSON.parse(await exec(['show', options.beadId, '--json']));
+  if (!bead) throw new Error(`bead not found: ${options.beadId}`);
+
+  const resolution = resolveClassification(bead);
+  const label = resolution.classification ? labelFor(resolution.classification) : null;
+  const applied = label !== null && resolution.source !== 'label' && !options.dryRun;
+
+  if (applied) await exec(['tag', options.beadId, /** @type {string} */ (label)]);
+
+  write(
+    `${JSON.stringify(
+      {
+        id: options.beadId,
+        classification: resolution.classification,
+        source: resolution.source,
+        reason: resolution.reason,
+        escalate: resolution.escalate,
+        applied,
+        label,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  return 0;
+}
+
+// Only run the CLI when invoked directly, so tests can import the pure tiers.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runCli({ argv: process.argv.slice(2) })
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((error) => {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = error instanceof UsageError ? 2 : 1;
+    });
+}

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

@@ -24,7 +24,7 @@ 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`
+- **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`.
 - **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.
 

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

@@ -33,15 +33,23 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
    bd dep add <new-id> <parent> --type parent-child
    ```
 
-2. **Check for an existing classification label.** Run `bd label list <id>`. If `implementation-type` is already present, skip step 3 — re-classifying a labelled bead wastes a subagent call.
+2. **Classify deterministically.** Run the `classify-bead` classifier — it resolves an existing label, the legacy `## Type` field, and explicit heuristic signals without a model call, and applies the label itself when it resolves:
 
-3. **Classify the bead.** Delegate to the `classify-bead` skill as a subagent via {{TOOL:task}} — do not classify inline. It returns `AFK` or `HITL` and applies the `implementation-type` label.
+   ```bash
+   # Run from the TARGET project's directory — bd resolves its beads DB from cwd.
+   node <skill-scripts>/../../classify-bead/scripts/classify-bead.mjs <new-id>
+   ```
+
+   - `"classification": "afk" | "hitl"` → the label is applied; branch on that class in step 3.
+   - `"escalate": true` → delegate to the `classify-bead` skill as a subagent via {{TOOL:task}}; it applies the rubric and tags the bead.
+
+   `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded. Sibling skills sit alongside this skill's directory in every harness, so `../../classify-bead/scripts/` resolves to the classifier.
 
-4. **Branch on classification.**
+3. **Branch on classification.**
    - **HITL** — stop here. Report the bead ID and classification to the caller. Do not create pipeline chores: a human drives the work, so the chore tree does not apply.
-   - **AFK** — continue to step 5.
+   - **AFK** — continue to step 4.
 
-5. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and deterministically creates all stage chores plus the PR gate bead in one shot:
+4. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and deterministically creates all stage chores plus the PR gate bead in one shot:
 
    ```bash
    # Run from the TARGET project's directory — bd resolves its beads DB from cwd;
@@ -53,12 +61,13 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
    `<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.
 
-6. **Report.** Return the parent bead ID, the classification (`AFK`), and the created child bead IDs from the script output (including `featurePrReview`).
+5. **Report.** Return the parent bead ID, the classification (`AFK`), and the created child bead IDs from the script output (including `featurePrReview`).
 
 ## Red Flags
 
 - **Running the script from the wrong directory.** Chores land in whatever `.beads` tree `bd` resolves from cwd — the target project's root is the only safe cwd.
-- **Classifying inline.** The `classify-bead` rubric is a subagent's job (with a label short-circuit); inlining yours means re-reading bead content and drifting from the rubric.
+- **Spawning the `classify-bead` subagent when the classifier already resolved the bead.** The deterministic script is the short-circuit; a subagent is only for `escalate: true`.
+- **Skipping the classifier and classifying by hand.** The rubric is a subagent's job; a hand-rolled guess drifts from it.
 - **Expanding an HITL bead.** If classification is HITL, stop — creating a chore tree for human-driven work is wrong.
 - **Hardcoding `<skill-scripts>`.** The install path differs per harness (plugin cache, installed-plugins, dev checkout); resolve it at runtime.
 
@@ -66,7 +75,7 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 | Rationalization | Rebuttal |
 |---|---|
-| "I know this task is AFK — I'll skip the classify-bead call" | Classification is a rubric check against the full bead body; assumptions masked by familiarity cause mislabelled work to hit the wrong queue. |
+| "I know this task is AFK — I'll skip the classifier" | The classifier resolves the label, `## Type`, and explicit signals in one command; skipping it leaves the bead unlabelled or forces a needless subagent. |
 | "I'll create the chores by hand instead of running the script" | The script is the single source of truth for titles, labels, dep chains, and the PR gate. Hand-created chores drift silently. |
 | "The pipeline is overkill for this small task" | If the work is worth tracking at all, the stage chore tree is what lets ralph execute and gate it. Not ready for that? Use `record-idea`. |
 
@@ -77,7 +86,7 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 ## Cross-skill references
 
-- `classify-bead` — classify the new bead via subagent (step 3).
+- `classify-bead` — deterministic classifier first, rubric subagent only on escalation (step 2).
 
 ## Examples
 
@@ -93,8 +102,8 @@ The full bead-property contract (titles, labels, dependencies per chore and for
 
 - [ ] Parent bead exists with the correct title, description, and priority.
 - [ ] `parent-child` dependency added when a parent epic was supplied.
-- [ ] `implementation-type` label present on the parent bead (`bd label list <id>`).
+- [ ] `implementation-type` label present on the parent bead (`bd label list <id>`) — resolved by the classifier or, on escalation, the rubric subagent.
 - [ ] HITL path: no pipeline chores created, caller told the classification. AFK path: script ran from the target project's cwd and its JSON contains every stage ID plus `featurePrReview`.
 - [ ] Chore titles/labels/dependencies match the contract (`[<parent-id>] <stage title>`, `stage:<id>`, `parent-child` to parent, `blocks` per `dependsOn`), verified against `REFERENCE.md`.
-- [ ] PR gate task exists with `implementation-type:hitl` + `lifecycle:feature-pr` labels and blocks the final document stage chore.
+- [ ] PR gate task exists and blocks the final document stage chore, carrying **exactly one** `implementation-type` label — `implementation-type:hitl` (never an inherited `implementation-type:afk` alongside it) — plus `lifecycle:feature-pr`.
 - [ ] Report returned the parent bead ID, classification, and all child bead IDs.

package/skills/planning/create-task/scripts/create-chores.ts

@@ -106,6 +106,10 @@ const prGateBeadId = run([
   '--priority', priority,
   '--labels', 'implementation-type:hitl,lifecycle:feature-pr',
   '--parent', parentId,
+  // The gate declares its own labels; opt out of bd's create-time parent-label
+  // inheritance so its explicit :hitl is never joined by an inherited :afk.
+  // Stage chores deliberately keep inheriting :afk -- do not add this there.
+  '--no-inherit-labels',
   '--silent',
 ]);
 run(['bd', 'dep', 'add', prGateBeadId, documentStageBeadId, '--type', 'blocks']);

package/skills/planning/write-a-prd/SKILL.md

@@ -25,7 +25,7 @@ description: Create a PRD through user interview, codebase exploration, and modu
 3. **Interview relentlessly.** Walk down each branch of the design tree, resolving dependencies between decisions one by one, until the user's understanding and yours are identical. Every open question at this point becomes ambiguity in the PRD.
 4. **Sketch the modules.** List the major modules to build or modify, actively looking for deep modules — ones that encapsulate rich behaviour behind a simple, stable interface testable in isolation. Confirm the list with the user, plus which modules they want tests written for.
 5. **Write the PRD.** Render the template in `FORMAT.md` (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes). Make the user-story list extremely extensive so it covers all aspects of the feature.
-6. **File the bead.** Create the epic with `bd create "<title>" --type epic --priority P1 --body-file -`, piping the rendered PRD to stdin, then run `classify-bead` (as a subagent, per its invocation instructions) to label it AFK or HITL.
+6. **File the bead.** Create the epic with `bd create "<title>" --type epic --priority P1 --body-file -`, piping the rendered PRD to stdin, then run the `classify-bead` classifier (`node <this-skill-dir>/../classify-bead/scripts/classify-bead.mjs <epic-id>`, run from the target project's cwd) to label it AFK or HITL. Escalate to the `classify-bead` subagent only when the classifier reports `escalate: true`.
 
 Run the steps in order. Skip a step only when the user confirms it is unnecessary (e.g. the codebase is already explored).
 
@@ -59,7 +59,7 @@ Run the steps in order. Skip a step only when the user confirms it is unnecessar
 - Use `record-idea` when the idea is not yet ready to build.
 - Use `write-a-ticket` when the spec targets an external tracker rather than a bead.
 - Run `prd-to-tasks` on the filed epic to break the PRD into an executable backlog.
-- Run `classify-bead` on the new epic — the repo labels every new bead AFK or HITL.
+- Run the `classify-bead` classifier on the new epic — the repo labels every new bead AFK or HITL. Its `scripts/` directory sits next to this skill's directory in every harness, so `<this-skill-dir>/../classify-bead/scripts/classify-bead.mjs` resolves it. Escalate to its rubric subagent only when the classifier reports `escalate: true`.
 
 ## Examples
 

package/skills/style/style-code/REFERENCE.md

@@ -1,6 +1,36 @@
-# Additional Examples
+# Examples
 
-Extended before/after pairs for less common style-code patterns.
+Before/after pairs for `style-code`. The most common patterns come first; the rest are
+extended pairs for less frequent cases.
+
+## Common patterns
+
+### Types at boundaries
+
+| Instead of… | Write… |
+|---|---|
+| `function handleRequest(raw: any) { ... }` with no validation | `function handleRequest(raw: unknown): HandlerResult { ... }` validated at the ingress boundary |
+| `const user = JSON.parse(raw)` with unchecked cast | `const user = parseUser(JSON.parse(raw))` validated with `parseUser` at the deserialisation edge |
+
+### Naming
+
+| Instead of… | Write… |
+|---|---|
+| `function process(items) { ... }` | `function resolveOverdueAccounts(accounts: Account[]) { ... }` |
+| `interface Config { ... }` | `interface ExportOptions { ... }` |
+
+### Scoping
+
+| Instead of… | Write… |
+|---|---|
+| One commit fixing a bug, renaming a module, and adding an abstraction | One commit per concern, each reviewable on its own |
+
+### Stateful objects
+
+| Instead of… | Write… |
+|---|---|
+| ```ts // factory closure hiding mutable state function createStepRegistry() { const steps = new Map<string, Step>(); return { register: (name, step) => steps.set(name, step), resolve: (name) => steps.get(name), }; } ``` | ```ts // a class names the state it owns class StepRegistry { #steps = new Map<string, Step>(); register(name: string, step: Step): void { this.#steps.set(name, step); } resolve(name: string): Step \| undefined { return this.#steps.get(name); } } ``` |
+| ```ts class C { private steps = new Map<string, Step>(); } ``` (compile-time only — erases away) | ```ts class C { #steps = new Map<string, Step>(); } ``` (runtime-enforced native private field) |
 
 ## Validation and error handling