@hyperdreamer/pi-webui 1.10.7 → 1.11.0-beta.10

package/optional-skills/deterministic-subagent-driven-development/scripts/sdd-state.mjs

@@ -0,0 +1,349 @@
+/**
+ * Facade and CLI for the deterministic SDD state helper.
+ *
+ * Importing this module has no side effects: it neither writes output nor sets an
+ * exit code. All parsing and tier logic lives in `lib/plan-policy.mjs`; this file
+ * only adapts that logic to argv.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The skill root, resolved from this module so cwd never affects rendering. */
+const SKILL_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+import { verifyManifest, writeManifest } from "./lib/manifest.mjs";
+import { parsePlanText, roleTier } from "./lib/plan-policy.mjs";
+import { renderPrompt } from "./lib/prompt-renderer.mjs";
+import {
+  clearStaleLock,
+  EXIT,
+  initRun,
+  lockStatus,
+  repairAudit,
+  show,
+  StoreError,
+  transition,
+} from "./lib/state-store.mjs";
+
+export {
+  assertRuntimeList,
+  buildManifest,
+  computeRuntimeHash,
+  ManifestError,
+  readManifest,
+  RUNTIME_FILES,
+  runtimeFilePaths,
+  verifyManifest,
+  writeManifest,
+} from "./lib/manifest.mjs";
+
+export { renderPrompt } from "./lib/prompt-renderer.mjs";
+
+export {
+  clearStaleLock,
+  EXIT,
+  initRun,
+  lockStatus,
+  repairAudit,
+  show,
+  StoreError,
+  transition,
+} from "./lib/state-store.mjs";
+
+export {
+  computeRunId,
+  createInitialState,
+  dispatchKeyFor,
+  EVENT_TYPES,
+  PHASES,
+  reduceState,
+  StateError,
+  STATE_VERSION,
+  TERMINAL_PHASES,
+  TRANSITIONS,
+  validateState,
+} from "./lib/state-machine.mjs";
+
+export {
+  finalReviewerTier,
+  fixerTier,
+  parsePlanText,
+  reReviewerTier,
+  reviewerTier,
+  roleTier,
+  tierDirective,
+  tierEcho,
+  tierLabel,
+  TIERS,
+} from "./lib/plan-policy.mjs";
+
+const USAGE = [
+  "usage:",
+  "  sdd-state validate-plan PLAN_FILE",
+  "  sdd-state role-tier --implementer TIER --role ROLE [--round N]",
+  "  sdd-state init --plan PLAN --state STATE --progress PROGRESS --repo-root ROOT",
+  "                 --worktree TREE --branch BRANCH --base-ref REF --merge-base SHA",
+  "  sdd-state show --state STATE --progress PROGRESS",
+  "  sdd-state transition --state STATE --progress PROGRESS --plan PLAN",
+  "                       --expected-revision N --event-file EVENT_JSON",
+  "  sdd-state repair-audit --state STATE --progress PROGRESS",
+  "  sdd-state lock-status --state STATE",
+  "  sdd-state clear-stale-lock --state STATE --expected-owner-token TOKEN",
+  "                             --decision-file DECISION_JSON",
+  "  sdd-state render-prompt --tier TIER --role ROLE --context CONTEXT_JSON",
+  "                          --output PROMPT_FILE",
+  "  sdd-state manifest-create --source-root SOURCE --package-json PACKAGE_JSON",
+  "                            --output MANIFEST",
+  "  sdd-state manifest-hash --manifest MANIFEST",
+].join("\n");
+
+/** Require a set of flags, naming every missing one at once. */
+function requireFlags(flags, names) {
+  const missing = names.filter((name) => flags.get(name) === undefined);
+  if (missing.length > 0) {
+    throw new Error(`missing required flag(s): ${missing.map((n) => `--${n}`).join(", ")}\n${USAGE}`);
+  }
+  return Object.fromEntries(names.map((name) => [name, flags.get(name)]));
+}
+
+function parseFlags(args) {
+  const flags = new Map();
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith("--")) throw new Error(`unexpected argument: ${token}`);
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new Error(`flag ${token} requires a value`);
+    }
+    flags.set(token.slice(2), value);
+    index += 1;
+  }
+  return flags;
+}
+
+function validatePlanCommand(args) {
+  const planPath = args[0];
+  if (planPath === undefined || args.length > 1) throw new Error(USAGE);
+
+  const bytes = readFileSync(planPath);
+  const parsed = parsePlanText(bytes.toString("utf8"), planPath);
+  return {
+    planPath,
+    planDigest: createHash("sha256").update(bytes).digest("hex"),
+    globalConstraints: parsed.globalConstraints,
+    tasks: parsed.tasks.map((task) => ({
+      number: task.number,
+      title: task.title,
+      implementerTier: task.implementerTier,
+    })),
+  };
+}
+
+function roleTierCommand(args) {
+  const flags = parseFlags(args);
+  const implementer = flags.get("implementer");
+  const role = flags.get("role");
+  if (implementer === undefined || role === undefined) throw new Error(USAGE);
+
+  const rawRound = flags.get("round");
+  if (rawRound === undefined) return roleTier({ implementer, role });
+
+  if (!/^[0-9]+$/u.test(rawRound)) throw new Error(`fix round must be an integer: ${rawRound}`);
+  return roleTier({ implementer, role, round: Number(rawRound) });
+}
+
+function main(argv) {
+  const [command, ...args] = argv;
+  switch (command) {
+    case "validate-plan":
+      console.log(JSON.stringify(validatePlanCommand(args), null, 2));
+      return 0;
+    case "role-tier":
+      console.log(JSON.stringify(roleTierCommand(args)));
+      return 0;
+    case "init": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, [
+        "plan",
+        "state",
+        "progress",
+        "repo-root",
+        "worktree",
+        "branch",
+        "base-ref",
+        "merge-base",
+      ]);
+      const result = initRun({
+        planPath: required.plan,
+        statePath: required.state,
+        progressPath: required.progress,
+        repoRoot: required["repo-root"],
+        worktree: required.worktree,
+        branch: required.branch,
+        baseRef: required["base-ref"],
+        mergeBase: required["merge-base"],
+      });
+      console.log(JSON.stringify({ revision: result.state.revision, phase: result.state.phase }));
+      return 0;
+    }
+    case "show": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, ["state", "progress"]);
+      const result = show({ statePath: required.state, progressPath: required.progress });
+      console.log(JSON.stringify(result, null, 2));
+      // A repairable ledger is reported through the exit code so a script does
+      // not have to parse stdout to notice.
+      return result.audit.status === "AUDIT_REPAIR_NEEDED"
+        ? EXIT.AUDIT_REPAIR_NEEDED
+        : result.audit.status === "AUDIT_CORRUPT"
+          ? EXIT.IDENTITY
+          : 0;
+    }
+    case "transition": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, [
+        "state",
+        "progress",
+        "plan",
+        "expected-revision",
+        "event-file",
+      ]);
+      const revision = required["expected-revision"];
+      if (!/^[0-9]+$/u.test(revision)) {
+        throw new Error(`--expected-revision must be a non-negative integer: ${revision}`);
+      }
+      const result = transition({
+        statePath: required.state,
+        progressPath: required.progress,
+        planPath: required.plan,
+        expectedRevision: Number(revision),
+        eventFile: required["event-file"],
+        worktree: flags.get("worktree"),
+        branch: flags.get("branch"),
+        mergeBase: flags.get("merge-base"),
+      });
+      console.log(JSON.stringify({ revision: result.state.revision, phase: result.state.phase }));
+      return 0;
+    }
+    case "repair-audit": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, ["state", "progress"]);
+      console.log(
+        JSON.stringify(repairAudit({ statePath: required.state, progressPath: required.progress })),
+      );
+      return 0;
+    }
+    case "lock-status": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, ["state"]);
+      console.log(JSON.stringify(lockStatus({ statePath: required.state })));
+      return 0;
+    }
+    case "render-prompt": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, ["tier", "role", "context", "output"]);
+      const raw = readFileSync(required.context, "utf8");
+      if (Buffer.byteLength(raw, "utf8") > 64 * 1024) {
+        throw new Error("the context file exceeds 64 KiB");
+      }
+      let context;
+      try {
+        context = JSON.parse(raw);
+      } catch {
+        throw new Error(`the context file is not valid JSON: ${required.context}`);
+      }
+      const rendered = renderPrompt({
+        tier: required.tier,
+        role: required.role,
+        context,
+        skillRoot: SKILL_ROOT,
+      });
+      // Atomic: validation has already passed, so a partial prompt never appears
+      // at the output path where a dispatch could pick it up.
+      const temporaryPath = `${required.output}.tmp`;
+      writeFileSync(temporaryPath, rendered);
+      renameSync(temporaryPath, required.output);
+      console.log(JSON.stringify({ output: required.output, bytes: Buffer.byteLength(rendered, "utf8") }));
+      return 0;
+    }
+    case "clear-stale-lock": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, ["state", "expected-owner-token", "decision-file"]);
+      console.log(
+        JSON.stringify(
+          clearStaleLock({
+            statePath: required.state,
+            expectedOwnerToken: required["expected-owner-token"],
+            decisionFile: required["decision-file"],
+          }),
+        ),
+      );
+      return 0;
+    }
+    case "manifest-create": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, ["source-root", "package-json", "output"]);
+      const manifest = writeManifest({
+        sourceRoot: required["source-root"],
+        packageJsonPath: required["package-json"],
+        outputPath: required.output,
+      });
+      console.log(
+        JSON.stringify({
+          written: required.output,
+          runtimeHash: manifest.runtimeHash,
+          runtimeFileCount: manifest.runtimeFiles.length,
+          sourcePackage: manifest.sourcePackage,
+        }),
+      );
+      return 0;
+    }
+    case "manifest-hash": {
+      const flags = parseFlags(args);
+      const required = requireFlags(flags, ["manifest"]);
+      // Verify against the manifest's own directory so the check cannot be
+      // pointed at an unrelated tree by passing a mismatched source root.
+      const { manifest, runtimeHash } = verifyManifest(
+        required.manifest,
+        dirname(resolve(required.manifest)),
+      );
+      console.log(
+        JSON.stringify({
+          manifest: required.manifest,
+          runtimeHash,
+          runtimeFileCount: manifest.runtimeFiles.length,
+          verified: true,
+        }),
+      );
+      return 0;
+    }
+    default:
+      throw new Error(command === undefined ? USAGE : `unknown command: ${command}\n${USAGE}`);
+  }
+}
+
+function isDirectExecution() {
+  const entryPath = process.argv[1];
+  if (entryPath === undefined) return false;
+  // Node resolves symlinks for import.meta.url but leaves argv[1] as supplied, so
+  // a literal comparison fails when this file is reached through a symlink. That
+  // failure is silent: main() never runs and the exit code is still 0.
+  return realpathSync(resolve(entryPath)) === realpathSync(fileURLToPath(import.meta.url));
+}
+
+if (isDirectExecution()) {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    // A StoreError carries the exit code its failure mode maps to; anything else
+    // is a validation failure from argument handling.
+    // A StoreError carries the exit code its failure mode maps to. A ManifestError
+    // is not a StoreError, so integrity failures land on VALIDATION alongside
+    // argument handling -- a wrong hash is a bad input, not lock contention.
+    process.exitCode = error instanceof StoreError ? error.code : EXIT.VALIDATION;
+  }
+}

package/optional-skills/deterministic-writing-plans/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: deterministic-writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code, and the plan will be executed by the deterministic subagent-driven-development controller
+---
+
+# Deterministic Writing Plans
+
+## Overview
+
+Write implementation plans that the deterministic subagent-driven-development
+controller can run without manual repair. Assume the implementer has zero
+context for this codebase and questionable taste: document which files to
+touch, the actual code, how to test it, and what neighbouring tasks named
+things. Give them bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume a skilled developer who knows almost nothing about our toolset or
+problem domain, and who does not know good test design well.
+
+**Announce at start:** "I'm using the deterministic-writing-plans skill to
+create the implementation plan."
+
+**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
+(user preferences for plan location override this default).
+
+## What makes this different
+
+Every task carries a machine-checked tier annotation, and headings are exactly
+`## Task N:`. The controller parses the plan; a plan that does not satisfy the
+grammar is rejected outright with a diagnostic, not repaired. Two consequences:
+
+- **Copy `templates/plan-skeleton.md` and edit it.** It is a literal, valid plan
+  and a test parses it with the controller's own parser on every run. Starting
+  from it means starting from something known to parse.
+- **The grammar is the whole contract.** A hand-written plan that satisfies it
+  is just as valid. Nothing checks which skill produced a plan.
+
+**Using the wrong skill?** If no controller will run this plan, use the plain
+`writing-plans` skill instead. The grammar here is additive and harmless to a
+human reader, so a deterministic plan is never wrong for a human to execute, but
+tier annotations are pure overhead when nothing dispatches on them.
+
+## Non-negotiable grammar
+
+Verified against the controller's parser, not paraphrased. See
+`references/grammar.md` for the observed diagnostics and the eight rejections
+pinned in `tests/grammar-rejections.test.mjs`.
+
+- Task heading is exactly `## Task <N>: <Title>`. `###` is an error, not a
+  tolerated variant. `<N>` starts at 1 and increases by 1 with no gaps.
+- Each task carries exactly one `**Implementer tier:** <Value>` line, outside
+  any code fence, where `<Value>` is TitleCase: `Economy`, `Fast`, `Standard`,
+  `Advanced`, `Capable`, or `Frontier`. Lowercase is a hard error. A trailing
+  space is a hard error.
+- `## Global Constraints` may appear at most once, and must precede the first
+  task. A second one is a hard error (`duplicate Global Constraints section`);
+  one placed after Task 1 is a hard error (`Global Constraints must precede the
+first task`).
+- Fenced content is inert. A tier line inside a fence does not count, and the
+  task will be rejected as having no tier.
+- Do not put a `---` rule immediately after `## Global Constraints` or at the
+  end of a task. The parser absorbs it into that section, and the text is
+  injected verbatim into child briefs.
+- **Never use a plain `##` heading inside a task body.** Any non-canonical H2
+  terminates the task silently: every line after it, including remaining steps
+  and the commit step, is discarded with no diagnostic. Use `###` or deeper for
+  subheadings within a task. This is the most destructive mistake available to
+  a plan author, because the plan still validates.
+
+## Plan Document Header
+
+**Every plan MUST start with this header.** The grammar does not enforce it, so
+nothing will reject a plan without it; it is required because a reader arriving
+cold, human or agent, has no other orientation.
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use the deterministic
+> deterministic-subagent-driven-development controller to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+## Global Constraints
+
+[The spec's project-wide requirements — version floors, dependency limits,
+naming and copy rules, platform requirements — one line each, with exact
+values copied verbatim from the spec.]
+```
+
+`## Global Constraints` carries a specific obligation. It is injected verbatim
+into **every** task brief, and it is the only channel to a subagent that never
+sees the plan. Copy exact values from the spec rather than summarizing: a child
+cannot infer a version floor stated approximately. One line each. If the spec
+has no project-wide requirements, say so in one explicit line rather than
+omitting the section.
+
+## Choosing the implementer tier
+
+Annotate **only** the implementer. The task reviewer, re-reviewer, fixer, and
+the three final roles are derived by formula from it; naming them in the plan
+invites disagreement with the controller's `role-tier`, which is authoritative.
+
+The tier table lives in the controller's plan contract, at
+`../deterministic-subagent-driven-development/references/plan-contract.md`, under "Choosing the
+implementer tier". Read it there rather than from a copy here, so there is one
+source of truth. The two skills ship together, so that path resolves; if you
+have installed this skill alone, the table is the one thing you are missing. Two rules from it
+matter enough to restate:
+
+- **`standard` is the floor whenever the implementer must decide anything.**
+  Cheap models take two to three times the turns on multi-step work, which
+  costs more in total than the tier saved.
+- **A wrong tier is a cost and latency defect, not a correctness one.** Review
+  gates catch bad implementations. Do not treat the annotation as a quality
+  lever, and do not inflate every task to `capable` "to be safe".
+
+Honest caveat: the mapping from task shape to tier is reasoned, not measured. No
+eval yet establishes that `advanced` beats `standard` on a given task shape. Use
+it as a default, and override it when you know something about the work.
+
+## Scope Check
+
+If the spec covers multiple independent subsystems, suggest breaking it into
+separate plans, one per subsystem. Each plan should produce working, testable
+software on its own.
+
+## File Structure
+
+Before defining tasks, map out which files will be created or modified and what
+each is responsible for. This is where decomposition gets locked in.
+
+- Design units with clear boundaries and well-defined interfaces. One clear
+  responsibility per file.
+- Prefer smaller, focused files. You reason best about code you can hold in
+  context at once, and edits are more reliable when files are focused.
+- Files that change together live together. Split by responsibility, not by
+  technical layer.
+- In existing codebases follow established patterns. Do not unilaterally
+  restructure, though splitting a file you are already modifying is reasonable.
+
+## Task Right-Sizing
+
+A task is the smallest unit that carries its own test cycle and is worth a fresh
+reviewer's gate. Fold setup, configuration, scaffolding, and documentation into
+the task whose deliverable needs them. Split only where a reviewer could
+meaningfully reject one task while approving its neighbour. Each task ends with
+an independently testable deliverable.
+
+Every task is dispatched to a fresh subagent that sees only its own brief plus
+`## Global Constraints`. A task that assumes conversational context will fail.
+
+## Bite-Sized Step Granularity
+
+Each step is one action, two to five minutes: write the failing test; run it and
+confirm it fails; write the minimal implementation; run the tests and confirm
+they pass; commit. Steps use `- [ ]` checkbox syntax.
+
+Those boxes are a readability convention here, not the progress mechanism. The
+controller's `state.json` is canonical and it pins the plan's digest, so editing
+the plan mid-run, including ticking a box, changes the digest and halts the run
+for a human decision. Leave the boxes unticked and let the controller track.
+
+## Files blocks
+
+Each task opens with the exact paths it touches, using `path:start-end` line
+ranges for modifications so an implementer edits the right region:
+
+```text
+**Files:**
+- Create: `src/parse/tokens.ts`
+- Modify: `src/cli/index.ts:1-20`
+- Test: `src/parse/tokens.test.ts`
+```
+
+## Interfaces blocks are load-bearing
+
+Each task states what it consumes and what it produces, with exact names and
+types:
+
+```text
+**Interfaces:**
+- Consumes: `tokenize(input: string): Token[]` from Task 1, with
+  `Token = { kind: "word" | "space"; text: string }`.
+- Produces: `runCli(argv: string[]): Promise<number>`, resolving to the exit code.
+```
+
+This is not documentation. An implementer sees only its own brief, so this block
+is the only way it learns the names its neighbours use. A task that consumes an
+earlier task's output without restating the signature will guess, and guess wrong.
+
+## No Placeholders
+
+Every step must contain the actual content the implementer needs. These are
+**plan failures** — never write them:
+
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" without the actual test code
+- "Similar to Task N" — repeat the code; tasks are read in isolation, and in
+  this controller they are literally dispatched in isolation
+- Steps that say what to do without showing how (code steps need code blocks)
+- References to types, functions, or methods not defined in any task
+
+## Self-Review
+
+After writing the plan, check it against the spec with fresh eyes. This is a
+checklist you run yourself, not a subagent dispatch.
+
+1. **Spec coverage.** For each requirement in the spec, name the task that
+   implements it. List gaps and add tasks for them.
+2. **Placeholder scan.** Search for the red flags above and fix them.
+3. **Type consistency.** Do types, signatures, and property names in later
+   tasks match what earlier tasks defined? `clearLayers()` in Task 3 and
+   `clearFullLayers()` in Task 7 is a bug.
+4. **Interfaces completeness.** For each task after the first, does its
+   Consumes block restate every signature it depends on?
+5. **Grammar.** Run the controller's `validate-plan` against the saved file.
+   Run `sdd-state validate-plan docs/superpowers/plans/<file>.md` from the
+   controller's `scripts/` directory. Do not hand over a plan you have not
+   seen parse.
+
+Fix inline; no need to re-review.
+
+## Execution Handoff
+
+State where the plan was saved and that it validated. Then hand off to the
+deterministic subagent-driven-development controller, which dispatches a fresh
+subagent per task with two-stage review between tasks.

package/optional-skills/deterministic-writing-plans/references/grammar.md

@@ -0,0 +1,84 @@
+# Grammar, as observed
+
+Every row below was produced by running the controller's `parsePlanText` against
+the input, not by reading the regexes. The pinning tests are in
+`tests/grammar-rejections.test.mjs`; each asserts the specific diagnostic, so a
+reworded message fails loudly instead of passing a loose match.
+
+The authority is `optional-skills/deterministic-subagent-driven-development/scripts/lib/plan-policy.mjs`:
+
+```js
+const TASK_HEADING = /^## Task ([1-9][0-9]*): (\S(?:.*\S)?)$/u;
+const TIER_FIELD =
+  /^\*\*Implementer tier:\*\* (Economy|Fast|Standard|Advanced|Capable|Frontier)$/u;
+const GLOBAL_HEADING = /^## Global Constraints$/u;
+```
+
+## Accepted
+
+| Input                                                 | Result                            |
+| ----------------------------------------------------- | --------------------------------- |
+| `## Task 1: Only task` + `**Implementer tier:** Fast` | parses; tier normalized to `fast` |
+
+TitleCase in the document, lowercase on the wire. The parser normalizes at that
+boundary, so no dispatch site has to remember to.
+
+## Rejected
+
+| Mistake                                        | Diagnostic                                                                                                                 |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `### Task 1: Only task`                        | `task-like heading is not canonical` — names the depth found, the depth required, and emits the corrected heading verbatim |
+| `**Implementer tier:** fast`                   | `malformed Implementer tier field: **Implementer tier:** fast`                                                             |
+| `**Implementer tier:** Fast ` (trailing space) | `malformed Implementer tier field`                                                                                         |
+| tier line absent                               | `Task 1 has no Implementer tier`, with the exact line to add                                                               |
+| `## Task 1:` then `## Task 3:`                 | `expected Task 2 but found Task 3`                                                                                         |
+| tier line inside a ``` fence                   | `Task 1 has no Implementer tier` — fenced content is inert                                                                 |
+| two `## Global Constraints` sections           | `duplicate Global Constraints section`                                                                                     |
+| `## Global Constraints` after Task 1           | `Global Constraints must precede the first task`                                                                           |
+
+The depth diagnostic is worth quoting in full, because it repairs the plan for you:
+
+```text
+<plan>:3: task-like heading is not canonical: ### Task 1: Only task
+  found heading depth "###" but the deterministic controller requires "##"
+  rewrite it as: ## Task 1: Only task
+  and give every task a tier line on its own: **Implementer tier:** Advanced
+  a tier-annotated plan is a precondition of tiered dispatch; the controller never guesses a tier
+```
+
+The two worth internalizing are the ones that look correct on screen: a
+lowercase tier reads naturally because lowercase is what travels on the wire,
+and a trailing space is invisible. Both are hard errors.
+
+## The `##` truncation trap
+
+Worse than the rule trap below, and the reason to read this file. A plain `##`
+heading inside a task body terminates the task. Every line after it is
+discarded: remaining steps, the commit step, everything. The plan still
+validates, and there is no diagnostic.
+
+Observed, with `## Notes` placed after Step 1 of a three-step task:
+
+```text
+tasks parsed: 1
+body: "- [ ] **Step 1: first**"
+Step 2 survived? false
+Commit step survived? false
+```
+
+`plan-policy.mjs` treats any non-canonical H2 as terminating the open section
+without capturing it. `###` and deeper are safe, as is bold text used as a
+pseudo-heading. Use `###` for any subheading within a task.
+
+Pinned by `tests/grammar-rejections.test.mjs`, which asserts both the loss under
+`##` and the survival under `###`.
+
+## The horizontal-rule trap
+
+The parser attributes a `---` line to the section it follows. A rule immediately
+after `## Global Constraints`, or at the end of a task body, is absorbed into
+that section's text and then injected verbatim into child briefs. It is not a
+parse error, so nothing warns you. Let headings do the separating.
+
+Pinned by `tests/plan-skeleton.test.mjs`, which asserts no `^-{3,}$` line
+survives in the constraints or any task body.