@sabaiway/agent-workflow-kit 14.8.0 → 14.10.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 14.10.0 — every place a user first looks names the epic, story and task tier and the guide that explains it (AD-156)
+
+**A kit user now meets the tier without running the help.** Until 14.10.0 only the help named the tier and its
+guide. Six more places now carry the phrase `epic, story and task` and the command `/agent-workflow-kit tier` on one
+line, each in its own words: the skill's description, a read-only row of the kit README's command table directly after
+`now`, a short paragraph after step 3 of the root README's start section, a fixed line of the welcome mat in the
+bootstrap and upgrade report footer, a read-only entry of the bootstrap's optional block, and a bullet of the install's `Next —` lines.
+Story S4 of the epic `KIT-USERS-LEARN-THE-TIER-AND-WALK-IT`, its last; contract
+`docs/ai/specs/kit/tier/tier-discovery.md` (new).
+
+- **The welcome mat.** The tier line is printed right after the help line, in every footer, whichever rung fires or
+  none; it is not a rung, since a rung prints only when every rung above it is silent and a user with no backend
+  ready would never reach it. The six rungs and their order are unchanged; with no rung, the two lines stand alone.
+- **The bootstrap block.** The lead-in now says every writer previews first, since the new tier entry writes
+  nothing; every other entry is unchanged.
+- **Proof on the installed copies.** The repository walk fixture `test/tier-walk-e2e.test.mjs` checks each
+  installed surface in both of its states — the installer's recorded output, the installed files and the help
+  rendered from the installed `tools/commands.mjs` — and the root README once, from the repository. Each region
+  is cut by asserted anchors (a missing one fails naming the surface and the anchor, from the new test helper
+  `test/doc-region-harness.test.mjs`), and cells that remove, move or case-change a token assert the surface is named.
+- **No budget raised.** The router byte budgets hold unedited; `bin/install.mjs` grows by its one bullet line, a
+  recorded raise to 585 lines. The help's own text, which the 14.9.0 entry expected with this story, stays as it is:
+  its rendered `tier` line already names the tier and the guide. The command catalog, the rungs and `upgrade.md` are
+  unchanged.
+
+## 14.9.0 — one read-only guide says what an epic, a story and a task are, and names the next step of the walk (AD-155)
+
+**`/agent-workflow-kit tier` answers "what is this tier, and what do I do next?" from the disk alone.** Until 14.9.0
+every tool of the epic, story and task tier worked, but nothing said what the tier is or which step comes next, and
+two refusals of a solo walk had their remedy only in a contract. The new guide prints a fixed text — an epic, a story
+and a task in one sentence each, the five story sessions, both templates by their installed paths, every key of both
+templates with one sentence each, and the Recommendations command — then, per epic, its stage and the ordered steps
+left, the first being the next one. Each step that runs a tool prints its command on its own line, ready to run from
+the project root; an authoring step (copy a template, fill it, edit a row) is named in words. Story S3 of the epic
+`KIT-USERS-LEARN-THE-TIER-AND-WALK-IT`; contract `docs/ai/specs/kit/tier/tier-guide/` (new), with
+`docs/ai/specs/kit/tier/tier-walk.md` at revision 3.
+
+- **The stages.** Per epic: E1 no epic yet, E2 the epic to fix, E3 open with a story in hand, E4 every story landed
+  and the epic to close, E5 landed. Per story in hand: S1 no plan, S2 a plan and no checkpoint, S3 a checkpoint and
+  no brief, S4 a brief with no binding, S5 a brief bound to an older checkpoint, S6 the task in hand, S7 the brief
+  done, S8 the checkpoints pruned and the story to land. A plan left over from a landed story is named as its
+  Cleanup: the checkpoint prune where one exists, then the removal of the plan and its briefs.
+- **Nothing is guessed.** An unreadable epic file or plan, a plan that does not parse, a second plan for one story, a
+  brief the grammar refuses, a malformed binding block, a checkpoint the reader refuses: each is printed as a state
+  with its reader, file and cause, and the guide still exits 0; an epic its check refuses is stage E2, with the
+  check command. A `{{KEY}}` placeholder left in an accepted epic or a
+  stamped brief is named with its file before the stage's steps. Several epics or stories in hand each render.
+- **Read-only, like `now`.** `node tools/tier-guide.mjs [--dir <project>] [--json]`; `--help` only as the whole
+  invocation. Exit 0 anything rendered, 1 the directory is not a git work tree, 2 usage. `--json` prints the same
+  facts as an envelope `{ schema, command, dir, tier, states, entries, skipped }`, each step carrying its text, its
+  kind (`run`, `write` or `fact`) and its command or null. It writes no file and no git state.
+- **Where to find it.** The mode `tier` (mode doc `references/modes/tier.md`), one Inspect entry in the command
+  catalog (so `/agent-workflow-kit help` lists it) and the `### Mode: tier` header in `SKILL.md`. The other places
+  that should mention it (the help's own text, the readmes, the welcome screen, the install's closing lines) come
+  with the epic's next story.
+- **Internals.** `readPlanEntries` moves from `tools/plan-shape-cli.mjs` into `tools/plan-files.mjs`;
+  `plan-shape-cli` and the guide's facts module import it. The repository walk fixture `test/tier-walk-e2e.test.mjs`
+  now reads the guide at every stage, and every tool step but the designed refusal cells is a line the guide
+  printed, run through `/bin/sh` unchanged. The package-content pin names the two tools and the mode doc, and the
+  tarball holds 336 files. The guide's suites do not ship.
+
 ## 14.8.0 — the kit ships an epic template and a task-brief template, each accepted by its checker once filled in (AD-154)
 
 **A first epic and a first task brief can start from a file instead of from a checker's refusal.** Until 14.8.0 the

package/README.md

@@ -234,6 +234,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit status` | any time | **read-only** single view of **versions + deployment + settings + bridges**: which members (kit / memory / engine / the two bridges) are installed and at what version (with an honest "installed on this machine" note when one is behind) and — in a project — what's deployed (`docs/ai`, the version stamps, and the **visibility**: visible / hidden / unclear), and the **feature-spec adoption state** (`not adopted` / `adopting (N draft)` / `adopted (N live, M draft)` / `could not be read`, plus `declined` when recorded), plus your settings (orchestration recipes, attribution, velocity) and the bridges' readiness. The two version axes (package number vs deployment-structure head) stay decoupled. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit now` | any time | **read-only** answer to where work stands in four blocks: **NOW** names every plan in flight, its phase, current and next step, and the tree evidence; **STEPS** gives every ledger row its evidence-derived status; **QUEUE** folds named rows under their full heading paths and calls position priority only in the judged backlog; **CAMPAIGN** shows the source-size practice figures and config state. The plan's own text never sets a status; a contradicted claim prints beside it. A block that cannot be derived is WITHHELD with its cause; NOW has two halves, plans and tree, each independently a value or WITHHELD, and NOW itself is WITHHELD only when both are. Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit tier` | any time | **read-only** guide to the epic, story and task tier: what each level is, and the next step of the walk, with the command that runs it wherever a tool does. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents five named recipes for composing the carriers of a step — the bridges and the full-tool executor subagent — into plan → execute → review — **Solo / Reviewed / Council / Delegated / Subagent** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready, or when the executor vehicle is missing/unusable), and offers the choice. The activity/slot registry (six activities) is rendered by `procedures` and by `set-recipe --help`. The orchestrator runs it via the bridge skills or the executor vehicle and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution` / `routine` / `feedback-triage` / `epic` / `task`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + carrier readiness (`plan-authoring`: author, fold, review; default Reviewed when a backend is ready, Council on request; slot-aware incl. Delegated and Subagent) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same) — except `feedback-triage`, whose record-bound block carries the check with `--excerpts`, the resolved member lines (ready bridge commands, the ready lens brief, or explicit skipped members), and either the record round-table command for a bridge obligation or the no-receipt fact otherwise: the record is the artifact. `--override <slot>=<value>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<value>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend or a subagent, never commits**; hand-editing stays fully supported. |

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: agent-workflow-kit
-description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
+description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow". New to the epic, story and task tier? Run `/agent-workflow-kit tier`.
 disable-model-invocation: true
 metadata:
-  version: '14.8.0'
+  version: '14.10.0'
 ---
 
 # agent-workflow-kit
@@ -115,6 +115,10 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/status.md` before actin
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/now.md` before acting.
 
+### Mode: tier
+
+read-only — read `${CLAUDE_SKILL_DIR}/references/modes/tier.md` before acting.
+
 ### Mode: recommendations
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md` before acting.

package/bin/install.mjs

@@ -551,6 +551,7 @@ const main = async () => {
 Next — open your agent inside a project and run the skill:
   • first time in this project  ->  /agent-workflow-kit
   • project already has the kit  ->  /agent-workflow-kit upgrade
+  • new to the epic, story and task tier  ->  /agent-workflow-kit tier
   • per agent: Claude Code -> /agent-workflow-kit · Devin Local -> /agent-workflow-kit ·
     Codex -> its /skills menu -> agent-workflow-kit (Codex may also auto-trigger it)
 

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "14.8.0",
+  "version": "14.10.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.8.0",
+  "version": "14.10.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/bootstrap.md

@@ -43,7 +43,8 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
     independent axes: a packaging-only release bumps the package but leaves the lineage head until a
     migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
     STOP (never downgrade).
-11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`). **After the footer, present ONE compact optional-accelerators block** — every entry preview-first, a one-line why each, nothing runs without a yes:
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`). **After the footer, present ONE compact optional-accelerators block** — a one-line why each; every writer previews first, and nothing runs without a yes:
+    - `/agent-workflow-kit tier` — read-only: explains the epic, story and task tier and names the next step of the walk;
     - `/agent-workflow-kit velocity` — routine read-only commands stop prompting (incl. the `--kit-tools` tier for the kit's own read-only tools; `${CLAUDE_SKILL_DIR}/references/modes/velocity.md`);
     - `/agent-workflow-kit agents` — cheap-model subagents take the mechanical work (sweeps, changelog skeletons, gate triage; `${CLAUDE_SKILL_DIR}/references/modes/agents.md`);
     - **gates seeding + hook** — offer to seed `docs/ai/gates.json` from the commands recon already recorded (step 1), via the consent-gated preview in `${CLAUDE_SKILL_DIR}/references/modes/gates.md` — this block is where that offer fires; then, once gates are declared, `/agent-workflow-kit hook` auto-approves exactly those declared commands (`${CLAUDE_SKILL_DIR}/references/modes/hook.md`);

package/references/modes/tier.md

@@ -0,0 +1,21 @@
+### Mode: tier
+
+<!-- opt-in-capability: none — an inspection surface that configures nothing -->
+
+Read-only. The tier guide: what an epic, a story and a task are, and where the walk of this project stands. It writes no file, cache, receipt, lock or git state; it never commits and never runs a subscription CLI.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/tier-guide.mjs --dir <project> --json`.
+
+Render the returned envelope compactly in the user's conversational language. Never paste the JSON. Keep every path and every command verbatim, each command on its own line so it runs as printed; translate only the prose around them.
+
+Keep this order: the tier text (what each level is, the five story sessions, the two templates, the glossary of their keys, the Recommendations pointer); then every rendered state with its reader, file, cause and next command; then per epic its stage, any placeholder left and the accepted check; then each story in hand with its stage, any placeholder left and its ordered actions; then the epic's own ordered actions (for example the check, the close, or the Cleanup a landed story left over). The first action printed is the next step. Several epics or stories each render; never pick one silently.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Anything rendered, every rendered state included. |
+| 1 | Nothing rendered: the `--dir` is not a git work tree; the cause is printed on stderr. |
+| 2 | Usage: an unknown argument, a `--dir` without a value, or `--help` / `-h` combined with anything. |
+
+**Invariants:** read-only · every printed command runnable as printed from the project root · compact user-language render with paths and commands verbatim · `process.exitCode`, never `process.exit()`.

package/references/shared/report-footer.md

@@ -77,7 +77,7 @@ skipping the installed-versions block."* — never a silent skip (Hard Constrain
 the rest of the report — and the commit gate — proceeds.
 
 **Welcome mat — the last line(s) of the footer.** After the version block and the backend-status
-line, print *"Run `/agent-workflow-kit help` to see every command."* then **one** recommended next
+line, print *"Run `/agent-workflow-kit help` to see every command."* and *"New to the epic, story and task tier? Run `/agent-workflow-kit tier`."* then **one** recommended next
 step, chosen **caveat-aware** from signals already in hand (the version block's notes, the settings
 areas of the same `--json` envelope, and the backend-status line — no new helper call) in this
 priority order:
@@ -99,7 +99,7 @@ priority order:
    placed) → the optional *`/agent-workflow-kit agents`* opt-in (never run it without a yes);
 6. else **gates are declared but the approval hook is not wired** (the envelope's hook settings:
    at least one declared gate, wired = no) → the optional *`/agent-workflow-kit hook`* opt-in
-   (never run it without a yes). If no rung applies, the help line above stands alone.
+   (never run it without a yes). If no rung applies, the two lines above stand alone.
 
 Keep it compact — a few short lines, plain language, no kit-internal terms.
 

package/tools/commands.mjs

@@ -91,6 +91,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Show where work stands: NOW answers the plan and tree, STEPS the evidence-derived ledger state, QUEUE its named positions, and CAMPAIGN its size-practice figures; the plan’s own text never sets a status.',
   },
+  {
+    key: 'tier',
+    invocation: invocationOf('tier'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'Explain the epic, story and task tier in plain words and name the next step of the walk, with the command that runs it wherever a tool does: the tier guide reads the disk alone.',
+  },
   {
     key: 'backends',
     invocation: invocationOf('backends'),

package/tools/plan-files.mjs

@@ -2,13 +2,24 @@
 // Phase 2). A LEAF: Node built-ins only, read-only fs (one injectable readdir), no CLI, no side
 // effects on import — extracted so the procedures read surface lists plans without importing
 // review-state (whose graph reaches the flow-store write API). review-state re-exports everything
-// here, so every existing consumer keeps its import site. Dependency-free, Node >= 22.
+// here except readPlanEntries, so every existing consumer keeps its import site. Dependency-free, Node >= 22.
 
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 export const PLANS_REL = 'docs/plans';
 
+// The plans directory's entries as plan-shape-cli and the tier guide read them: absent is an empty
+// list, any other read error is thrown with its code.
+export const readPlanEntries = (cwd) => {
+  try {
+    return readdirSync(join(cwd, PLANS_REL), { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw new Error(`${PLANS_REL} could not be read (${error?.code ?? 'fs error'})`);
+  }
+};
+
 // Scratch by the naming convention: EXECUTE-/FEEDBACK-/TASK- prefixes, or a name carrying PROMPT/prompt/
 // handoff. queue.md is the series index, never a plan.
 export const isScratchPlanName = (name) =>

package/tools/plan-shape-cli.mjs

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 
-import { readdirSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
-import { plansInFlight, PLANS_REL } from './plan-files.mjs';
+import { plansInFlight, PLANS_REL, readPlanEntries } from './plan-files.mjs';
 import { buildFacts, openRepo } from './plan-shape-facts.mjs';
 import { checkPlan, checkPlanStructure, formatFindings, parseLedger, PLAN_TITLE_PREFIX, verifyPlan } from './plan-shape.mjs';
 
@@ -21,15 +20,6 @@ const readPlan = (path) => {
   return result.content;
 };
 
-const readPlanEntries = (cwd) => {
-  try {
-    return readdirSync(join(cwd, PLANS_REL), { withFileTypes: true });
-  } catch (error) {
-    if (error?.code === 'ENOENT') return [];
-    throw new Error(`${PLANS_REL} could not be read (${error?.code ?? 'fs error'})`);
-  }
-};
-
 const getPaths = (text) => {
   try {
     const rows = parseLedger(text).rows.filter((row) => row.valid);

package/tools/tier-guide-facts.mjs

@@ -0,0 +1,315 @@
+// spec:tier-guide — docs/ai/specs/kit/tier/tier-guide/index.md and its part guide-stages.md
+import { lstatSync } from 'node:fs';
+import { posix, resolve } from 'node:path';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { resolveGitLocation } from './git-env.mjs';
+import { EPICS_REL, readEpicStore } from './epic-store.mjs';
+import { checkEpic } from './epic-shape.mjs';
+import { QUEUE_PATH, checkClaims, judgeClose, sweepSiblings } from './epic-shape-ledger.mjs';
+import { PLANS_REL, isScratchPlanName, plansInFlight, readPlanEntries } from './plan-files.mjs';
+import { PIN_FILE, readStoryLine } from './plan-shape-ownership.mjs';
+import { PLAN_HEADINGS, checkPlan, isSweep, parseLedger } from './plan-shape.mjs';
+import { buildFacts, openRepo } from './plan-shape-facts.mjs';
+import { newestCheckpoint } from './checkpoint.mjs';
+import { withRepository } from './checkpoint-core.mjs';
+import { parseBrief } from './task-brief.mjs';
+import { escapeForDisplay, isRenderableLine, shellQuoteArg } from './repo-lex.mjs';
+
+const WORK_TREE = 'work-tree';
+const LF = '\n';
+const MARKDOWN = '.md';
+const INFO = 'info';
+const LANDED = 'landed';
+const EPIC_TYPE = /^type:\s*epic\s*$/;
+const FRONT = '---';
+const CR_END = /\r$/;
+const SPAN = /\{\{([\s\S]*?)\}\}/g;
+const PLAN_STEM = /^[A-Za-z0-9_-]+$/;
+// The brief grammar's Plan field, matched one line at a time as task-brief matches it.
+const PLAN_FIELD = /^Plan: (docs\/plans\/[^/]+\.md)$/;
+const TASK_PREFIX = 'TASK-';
+const TASK_NUMBER = /-T([1-9][0-9]*)\.md$/;
+const OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const NO_CHECKPOINT = 'no-checkpoint';
+const HEADER_CODES = new Set(['sibling-header', 'sibling-read']);
+const HEAD_ARGS = ['rev-parse', '-q', '--verify', 'HEAD^{commit}'];
+const STAND_IN_EPIC = 'NEW-EPIC';
+const E1_CAUSE = `no epic file in ${EPICS_REL}`;
+const EPIC_TEMPLATE = '../references/authoring/EPIC_TEMPLATE.md';
+const TASK_TEMPLATE = '../references/authoring/TASK_TEMPLATE.md';
+const TEMPLATE_VERBS = new Set(['create', 'modify']);
+const READERS = Object.freeze({ store: 'readEpicStore', sweep: 'sweepSiblings', entries: 'readPlanEntries',
+  plans: 'plansInFlight', plan: 'checkPlan', brief: 'parseBrief', sequence: 'newestCheckpoint', head: 'readGit' });
+
+const q = shellQuoteArg;
+const action = (kind, text, command = null) => ({ kind, text: escapeForDisplay(text), command });
+const lineOf = (kind, text, parts) => (parts.every(isRenderableLine)
+  ? action(kind, text, parts.join(' '))
+  : action(kind, `${text} (not printed as a command: ${parts.filter((part) => !isRenderableLine(part)).map(escapeForDisplay).join(', ')} cannot stand on one line)`));
+const makeTools = (toolsDir) => {
+  const tool = (name) => q(`${toolsDir}/${name}`);
+  const node = (kind, text, name, ...args) => lineOf(kind, text, ['node', tool(name), ...args]);
+  return {
+    epicCheck: (path, kind = 'run') => node(kind, `check the epic ${path}`, 'epic-shape-cli.mjs', '--check', q(path)),
+    review: (path) => node('run', `read the review brief of the epic ${path}; the solo review is the reading of it`, 'epic-shape-cli.mjs', '--review-brief', q(path)),
+    close: (path) => node('run', `close the epic ${path}`, 'epic-shape-cli.mjs', '--close', q(path)),
+    planCheck: (plan) => node('run', `check the plan ${plan}`, 'plan-shape-cli.mjs', '--check', q(plan)),
+    planVerify: (plan) => node('run', `verify the plan ${plan} against the tree`, 'plan-shape-cli.mjs', '--verify', q(plan)),
+    mint: (plan) => node('run', `mint a checkpoint of the plan ${plan}`, 'checkpoint.mjs', 'mint', '--plan', q(plan)),
+    prune: (plan) => node('run', `prune the checkpoints of the plan ${plan}`, 'checkpoint.mjs', 'prune', '--plan', q(plan)),
+    stamp: (brief) => node('run', `stamp the brief ${brief}`, 'task-brief.mjs', 'stamp', q(brief)),
+    check: (brief) => node('run', `check the brief ${brief}`, 'task-brief.mjs', 'check', q(brief)),
+    reviewState: () => node('run', 'check the review state of the tree', 'review-state.mjs', '--check'),
+    copy: (template, target, text) => lineOf('write', text, ['cp', q(resolve(toolsDir, template)), q(target)]),
+  };
+};
+const state = (reader, file, cause, next = null) => ({ reader, file, cause: escapeForDisplay(cause), next });
+const findSpans = (file, text) => [...text.matchAll(SPAN)].map(([, span]) => ({ file, span: escapeForDisplay(span) }));
+const readText = (cwd, path) => {
+  const result = readRegularFileNoFollow(resolve(cwd, path));
+  return result.outcome === 'ok' ? { text: result.content } : { cause: `${result.outcome}: ${result.code ?? result.className ?? 'unreadable'}` };
+};
+const isPresent = (cwd, path) => lstatSync(resolve(cwd, path), { throwIfNoEntry: false }) !== undefined;
+// The lines of a file as the kit's readers see them: a CRLF file reads as its LF twin.
+const linesOf = (text) => text.split(LF).map((line) => line.replace(CR_END, ''));
+const declaresEpic = (text) => {
+  const lines = linesOf(text);
+  if (lines[0] !== FRONT) return false;
+  const end = lines.indexOf(FRONT, 1);
+  return end > 0 && lines.slice(1, end).some((line) => EPIC_TYPE.test(line));
+};
+const stripPath = (finding) => (finding.message.startsWith(`${finding.path}: `) ? finding.message.slice(finding.path.length + 2) : finding.message);
+
+const readHead = (cwd, env) => withRepository(cwd, { env }, (context) => {
+  const result = context.run(HEAD_ARGS, context.top, undefined, context.env);
+  const stdout = String(result.stdout ?? '').trim();
+  if (result.status === 0 && OID.test(stdout)) return { ok: true, oid: stdout };
+  if (result.status === 1 && stdout === '' && !result.error) return { ok: true, oid: null };
+  return { ok: false, reason: String(result.stderr ?? result.error?.message ?? 'HEAD could not be read').trim() };
+});
+
+const readStore = (cwd) => {
+  const store = readEpicStore(cwd);
+  if (store.outcome === 'refused') return { states: [state(READERS.store, EPICS_REL, store.reason)], entries: [], epics: [], blocked: true };
+  const entries = store.entries ?? [];
+  const states = entries.filter((entry) => entry.outcome === 'unreadable' || entry.outcome === 'non-regular')
+    .map((entry) => state(READERS.store, `${EPICS_REL}/${entry.name}`, `${entry.outcome}: ${entry.reason ?? entry.kind}`));
+  const sweep = sweepSiblings(entries, EPICS_REL);
+  const headerFindings = sweep.findings.filter((finding) => HEADER_CODES.has(finding.code));
+  const refused = new Set(headerFindings.map((finding) => finding.path));
+  const epics = entries.filter((entry) => typeof entry.text === 'string' && entry.name.endsWith(MARKDOWN)
+    && !refused.has(`${EPICS_REL}/${entry.name}`) && declaresEpic(entry.text));
+  const siblingStates = headerFindings.filter((finding) => finding.code !== 'sibling-read');
+  return { entries, epics, headerFindings, skipped: sweep.counts.skipped, blocked: false,
+    states: [...states, ...siblingStates.map((finding) => ({ finding }))] };
+};
+
+const judgeEpic = (entries, entry) => {
+  const path = `${EPICS_REL}/${entry.name}`;
+  const others = entries.filter((other) => other.name !== entry.name);
+  const shape = checkEpic(entry.text, path);
+  const sweep = sweepSiblings(others, EPICS_REL);
+  const claims = shape.findings.length === 0 && sweep.ok ? checkClaims([shape.epic, ...sweep.epics]) : { findings: [] };
+  const findings = [...shape.findings, ...sweep.findings, ...claims.findings];
+  return { path, others, epic: shape.epic, accepted: !findings.some((finding) => finding.severity !== INFO) };
+};
+
+const planOf = (text) => linesOf(text).map((line) => PLAN_FIELD.exec(line)?.[1]).find(Boolean) ?? null;
+const planShape = (row, epicId) => `The shape: the title # Plan: and a name; the five headings; under Goal and boundary the line Story: ${row.id} of ${epicId} and a governing spec path under docs/ai/specs or the words not adopted; one ledger row per file in six fields (id, verb, path, responsibility, budget, anchor) — a create or modify row an anchor that resolves to one place and, with no declared source-size cap, the budget n/a, a delete row a dash (—) in budget and anchor; the total line last, its before figure the current lines of every deleted file and of every modify row with a numeric budget, so total: 0 → 0 lines when every row is a create or modify with the budget n/a; at least one - bullet under Verification.`;
+
+// The Story line is read under Goal and boundary alone, as plan-shape reads it.
+const storyOf = (text) => {
+  const { document } = parseLedger(text);
+  const goal = document.headings.find((heading) => heading.text === PLAN_HEADINGS[0]);
+  const end = goal && document.headings.find((heading) => heading.index > goal.index && heading.level <= 2);
+  const lines = goal ? document.lines.slice(goal.index + 1, end?.index).map((line, offset) => ({ text: line, line: goal.index + 2 + offset })) : [];
+  return readStoryLine(lines);
+};
+const readPlan = (cwd, tools, path) => {
+  const read = readText(cwd, path);
+  if (read.text === undefined) return { path, text: null, story: null, failure: state(READERS.plans, path, read.cause) };
+  try {
+    const { story, findings } = storyOf(read.text);
+    if (findings.length) return { path, text: read.text, story: null, failure: state(READERS.plan, path, findings[0].message, tools.planCheck(path)) };
+    return { path, text: read.text, story, failure: null };
+  } catch (error) {
+    return { path, text: read.text, story: null, failure: state(READERS.plan, path, error.message, tools.planCheck(path)) };
+  }
+};
+
+const readPlans = (cwd, tools) => {
+  try {
+    const listing = readPlanEntries(cwd);
+    const names = plansInFlight(cwd, () => listing);
+    const plans = names.map((name) => readPlan(cwd, tools, `${PLANS_REL}/${name}`));
+    const briefs = listing.filter((entry) => entry.isFile() && entry.name.startsWith(TASK_PREFIX) && entry.name.endsWith(MARKDOWN))
+      .map((entry) => {
+        const path = `${PLANS_REL}/${entry.name}`;
+        const read = readText(cwd, path);
+        return { path, name: entry.name, text: read.text ?? '', cause: read.cause ?? null, plan: planOf(read.text ?? ''),
+          number: Number(TASK_NUMBER.exec(entry.name)?.[1] ?? 1) };
+      });
+    return { ok: true, plans, briefs, states: plans.filter((plan) => plan.failure).map((plan) => plan.failure) };
+  } catch (error) {
+    return { ok: false, state: state(READERS.entries, PLANS_REL, error.message) };
+  }
+};
+
+const readBinding = (brief) => {
+  if (brief.cause) return { refused: brief.cause };
+  const parsed = parseBrief(brief.text);
+  if (!parsed.ok) return { refused: parsed.reason };
+  if (parsed.unclosed || parsed.blocks.length > 1) return { refused: 'binding: the block count is not one closed block', binding: true };
+  if (parsed.blocks.length === 0) return { parsed, bound: false };
+  const value = (() => { try { return JSON.parse(parsed.blocks[0].source); } catch { return null; } })();
+  const isOid = (field) => typeof field === 'string' && OID.test(field);
+  if (!isOid(value?.checkpoint) || !isOid(value?.head)) return { refused: 'binding: the block carries no checkpoint and head', binding: true };
+  return { parsed, bound: true, checkpoint: value.checkpoint, head: value.head };
+};
+
+const judgeStory = (context, epicPath, epicId, row) => {
+  const { cwd, tools, plans } = context;
+  const own = plans.plans.filter((plan) => plan.story?.id === row.id && plan.story?.epic === epicId);
+  const stateOf = (stage, actions, extra = {}) => ({ story: { id: row.id, plan: extra.plan ?? null, stage, residual: extra.residual ?? [], actions } });
+  if (own.length > 1) return { state: state(READERS.plans, own[0].path, `story ${row.id} of ${epicId} has ${own.length} plans: ${own.map((plan) => plan.path).join(', ')}`) };
+  if (own.length === 0) {
+    if (plans.states.length) return {};
+    const stem = `${epicId}-${row.id}`;
+    const standIn = `${PLANS_REL}/${stem}${MARKDOWN}`;
+    if (!PLAN_STEM.test(stem) || isScratchPlanName(`${stem}${MARKDOWN}`)) {
+      return stateOf('S1', [tools.review(epicPath), action('write', `author the plan by hand under ${PLANS_REL} at a name of ASCII letters, digits, dashes and underscores with no EXECUTE-, FEEDBACK- or TASK- prefix and no PROMPT, prompt or handoff, since the epic id and story id make no such name. ${planShape(row, epicId)}`)]);
+    }
+    if (isPresent(cwd, standIn)) return { state: state(READERS.plans, standIn, `the plan stand-in path is taken by a file carrying no Story line ${row.id} of ${epicId} under Goal and boundary: move the line there, or rename or remove the file`) };
+    return stateOf('S1', [tools.review(epicPath), action('write', `author the plan by hand at ${standIn}. ${planShape(row, epicId)}`)]);
+  }
+  const plan = own[0];
+  try {
+    return judgePlan(context, epicPath, row, plan, stateOf);
+  } catch (error) {
+    return { state: state(READERS.plan, plan.path, error.message, tools.planCheck(plan.path)) };
+  }
+};
+
+const judgePlan = (context, epicPath, row, plan, stateOf) => {
+  const { cwd, env, tools, plans, head, today } = context;
+  const stem = posix.basename(plan.path, MARKDOWN);
+  const standIn = (number) => `${PLANS_REL}/${TASK_PREFIX}${stem}-T${number}${MARKDOWN}`;
+  const taken = plans.briefs.find((brief) => brief.plan !== null && brief.plan !== plan.path && brief.path === standIn(brief.number));
+  if (taken) return { state: state(READERS.brief, taken.path, `the brief stand-in path is taken by a brief of ${taken.plan}: rename or remove it`) };
+  const briefs = plans.briefs.filter((brief) => brief.plan === plan.path || (brief.plan === null && brief.path === standIn(brief.number)));
+  const judged = briefs.map((brief) => ({ ...brief, ...readBinding(brief) }));
+  const refusedBrief = judged.find((brief) => brief.refused);
+  if (refusedBrief) return { state: state(READERS.brief, refusedBrief.path, refusedBrief.refused,
+    refusedBrief.binding ? tools.check(refusedBrief.path) : tools.stamp(refusedBrief.path)) };
+  const top = Math.max(0, ...judged.map((brief) => brief.number));
+  const inHandAll = judged.filter((brief) => brief.number === top);
+  if (inHandAll.length > 1) return { state: state(READERS.brief, inHandAll[0].path, `briefs ${inHandAll.map((brief) => brief.path).join(', ')} carry one task number`) };
+  const inHand = inHandAll[0];
+  const rows = parseLedger(plan.text).rows.filter((ledgerRow) => ledgerRow.valid);
+  const briefed = new Set(judged.map((brief) => brief.parsed.rowId));
+  const unbriefed = rows.find((ledgerRow) => !briefed.has(ledgerRow.id));
+  const residual = judged.filter((brief) => brief.bound).flatMap((brief) => findSpans(brief.path, brief.text));
+  const extra = { plan: plan.path, residual };
+  const newest = newestCheckpoint(cwd, plan.path, { env });
+  const noHead = () => ({ state: state(READERS.head, null, 'HEAD is unborn: no commit to compare the brief with') });
+  const copyAction = (ledgerRow, number) => (ledgerRow && TEMPLATE_VERBS.has(ledgerRow.verb) && !isSweep(ledgerRow.path) && posix.basename(ledgerRow.path) !== PIN_FILE
+    ? [tools.copy(TASK_TEMPLATE, standIn(number), `copy the task template to ${standIn(number)}`),
+      action('write', `fill every key of the brief template's closed list in ${standIn(number)}, Row: ${ledgerRow.id}`), tools.stamp(standIn(number))]
+    : [action('write', `write the brief of row ${ledgerRow?.id ?? 'none'} by hand at ${standIn(number)} per the brief grammar (checkpoint, task-brief); the task template does not fit it`), tools.stamp(standIn(number))]);
+  if (!newest.ok && !String(newest.reason).startsWith(NO_CHECKPOINT)) return { state: state(READERS.sequence, plan.path, newest.reason) };
+  if (!newest.ok) {
+    if (!judged.some((brief) => brief.bound)) {
+      const paths = rows.flatMap((ledgerRow) => [ledgerRow.path, ledgerRow.anchorPath].filter(Boolean));
+      const result = checkPlan(plan.text, buildFacts(cwd, { paths, repo: openRepo(cwd) }));
+      if (result.findings.length) return { state: state(READERS.plan, plan.path, result.findings[0].message, tools.planCheck(plan.path)) };
+      return stateOf('S2', [tools.planCheck(plan.path), tools.mint(plan.path)], extra);
+    }
+    if (head.oid === null) return noHead();
+    if (!unbriefed && inHand.bound && inHand.head !== head.oid) {
+      return stateOf('S8', [action('write', `edit the story row ${row.id} of ${epicPath} to read state: landed ${today}`)], extra);
+    }
+    return { state: state(READERS.sequence, plan.path, 'the sequence was pruned before the story was done', tools.mint(plan.path)) };
+  }
+  if (!inHand) return stateOf('S3', copyAction(rows[0], 1), extra);
+  if (!inHand.bound) return stateOf('S4', [tools.stamp(inHand.path)], extra);
+  if (head.oid === null) return noHead();
+  if (inHand.head !== head.oid) {
+    return stateOf('S7', unbriefed ? [tools.mint(plan.path), ...copyAction(unbriefed, top + 1)]
+      : [tools.planVerify(plan.path), tools.prune(plan.path)], extra);
+  }
+  if (inHand.checkpoint !== newest.oid) return stateOf('S5', [tools.stamp(inHand.path)], extra);
+  const files = inHand.parsed.files.map((file) => file.path);
+  return stateOf('S6', [tools.check(inHand.path),
+    action('write', `bring the Files of ${inHand.path} to the row's post-state, the test first, until every Acceptance line is green`),
+    ...inHand.parsed.acceptance.map(([command]) => lineOf('run', 'run the Acceptance command of the brief', [command])),
+    tools.reviewState(),
+    lineOf('run', 'stage the Files of the brief', ['git', '--literal-pathspecs', 'add', '--', ...files.map(q)]),
+    lineOf('run', 'commit the Files of the brief', ['git', 'commit', '-m', q(inHand.parsed.title)])], extra);
+};
+
+const cleanupOf = (context, epicId, rows) => context.plans.plans
+  .filter((plan) => plan.story?.epic === epicId && rows.some((row) => row.id === plan.story.id && row.state === LANDED))
+  .flatMap((plan) => {
+    const newest = newestCheckpoint(context.cwd, plan.path, { env: context.env });
+    const prune = !newest.ok && String(newest.reason).startsWith(NO_CHECKPOINT) ? [] : [context.tools.prune(plan.path)];
+    return [...prune, action('write', `remove the plan ${plan.path} and its briefs: the Cleanup of a landed story`)];
+  });
+
+const judgeEntry = (context, store, entry) => {
+  const judged = judgeEpic(store.entries, entry);
+  const { tools } = context;
+  const id = posix.basename(judged.path, MARKDOWN);
+  const base = { stage: 'E2', id, path: judged.path, cause: null, fact: null, residual: [], actions: [tools.epicCheck(judged.path)], stories: [] };
+  if (!judged.accepted) return { entry: base, states: [] };
+  const { epic } = judged;
+  const residual = findSpans(judged.path, entry.text);
+  const accepted = { ...base, residual };
+  if (epic.fields.state === LANDED) return { entry: { ...accepted, stage: 'E5', actions: cleanupOf(context, id, epic.rows) }, states: [] };
+  const landed = new Set(epic.rows.filter((row) => row.state === LANDED).map((row) => row.id));
+  const inHand = epic.rows.filter((row) => row.state !== LANDED && row.dependsOn.every((dependency) => landed.has(dependency)));
+  if (inHand.length === 0) {
+    const queueRead = readRegularFileNoFollow(resolve(context.cwd, QUEUE_PATH));
+    const queue = queueRead.outcome === 'ok' ? queueRead.content : { outcome: queueRead.outcome, reason: queueRead.code ?? queueRead.className };
+    const closed = judgeClose({ epic: entry.text, path: judged.path, queue, entries: judged.others });
+    const edits = closed.findings.filter((finding) => finding.severity !== INFO).map((finding) => (finding.code === 'close-result'
+      ? action('write', `add the line Result line: ${context.today} under ## Acceptance of ${judged.path}`)
+      : action('write', finding.code === 'close-queue' ? `delete the queue row: ${stripPath(finding)}` : stripPath(finding))));
+    return { entry: { ...accepted, stage: 'E4', actions: [...edits, tools.close(judged.path), ...cleanupOf(context, id, epic.rows)] }, states: [] };
+  }
+  const stories = inHand.map((row) => judgeStory(context, judged.path, id, row));
+  return { entry: { ...accepted, stage: 'E3', fact: tools.epicCheck(judged.path, 'fact'), actions: cleanupOf(context, id, epic.rows),
+    stories: stories.filter((story) => story.story).map((story) => story.story) }, states: stories.filter((story) => story.state).map((story) => story.state) };
+};
+
+const judgeFirstEpic = (context, store) => {
+  const standIn = `${EPICS_REL}/${STAND_IN_EPIC}${MARKDOWN}`;
+  if (isPresent(context.cwd, standIn)) return { states: [state(READERS.store, standIn, 'the epic stand-in path is taken by a file that is not an epic: rename or remove it')], entries: [] };
+  return { states: [], entries: [{ stage: 'E1', id: null, path: null, cause: E1_CAUSE, fact: null, residual: [], actions: [
+    action('write', `create the epic store directory ${EPICS_REL}`, `mkdir -p ${EPICS_REL}`),
+    context.tools.copy(EPIC_TEMPLATE, standIn, `copy the epic template to ${standIn}`),
+    action('write', `fill every key of the epic template's closed list in ${standIn}; EPIC_ID is ${STAND_IN_EPIC}, the file stem`),
+    context.tools.epicCheck(standIn)], stories: [] }] };
+};
+
+export const readTierFacts = ({ cwd, env, toolsDir, today }) => {
+  const location = resolveGitLocation(cwd, { env });
+  if (location.state !== WORK_TREE) return { location, states: [], entries: [], skipped: 0 };
+  const store = readStore(cwd);
+  const tools = makeTools(toolsDir);
+  const firstEpic = store.epics[0] ? `${EPICS_REL}/${store.epics[0].name}` : null;
+  const storeStates = store.states.map((item) => (item.finding
+    ? state(READERS.sweep, item.finding.path, stripPath(item.finding), firstEpic ? tools.epicCheck(firstEpic) : null) : item));
+  if (store.blocked) return { location, states: storeStates, entries: [], skipped: 0 };
+  const plans = readPlans(cwd, tools);
+  const head = readHead(cwd, env);
+  const headStates = head.ok ? [] : [state(READERS.head, null, head.reason)];
+  if (!plans.ok) return { location, states: [...storeStates, plans.state, ...headStates], entries: [], skipped: store.skipped };
+  const context = { cwd, env, tools, plans, head: head.ok ? head : { oid: null }, today };
+  if (store.epics.length === 0) {
+    const first = store.headerFindings.length ? { states: [], entries: [] } : judgeFirstEpic(context, store);
+    return { location, states: [...storeStates, ...plans.states, ...headStates, ...first.states], entries: first.entries, skipped: store.skipped };
+  }
+  const judged = store.epics.map((entry) => judgeEntry(context, store, entry));
+  return { location, states: [...storeStates, ...plans.states, ...headStates, ...judged.flatMap((item) => item.states)],
+    entries: judged.map((item) => item.entry), skipped: store.skipped };
+};

package/tools/tier-guide.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// spec:tier-guide — docs/ai/specs/kit/tier/tier-guide/index.md
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { shellQuoteArg } from './repo-lex.mjs';
+import { readTierFacts } from './tier-guide-facts.mjs';
+
+const SCHEMA = 1;
+const TOOLS_DIR = dirname(fileURLToPath(import.meta.url));
+const INDENT = '  ';
+const HELP = `tier — read-only: what the epic, story and task tier is, and the next step of the walk.
+
+Usage:
+  node tier-guide.mjs [--dir PROJECT] [--json]
+
+--dir   the project to read (default: the current directory).
+--json  the JSON envelope instead of the plain text.
+--help  answered only when it is the whole invocation.
+
+Exit codes: 0 anything rendered, a rendered state included; 1 nothing rendered (a --dir that is not a
+git work tree); 2 usage.
+
+Reads only: no store, no receipt, no cache, no lock.`;
+
+const EPIC_KEYS = [
+  ['DATE', 'the day the epic was last updated, YYYY-MM-DD.'],
+  ['EPIC_TITLE', 'the epic in a few plain words.'],
+  ['INTENT', 'what the epic sets out to change.'],
+  ['VALUE', 'what a user gains once every story has landed.'],
+  ['NON_GOALS', 'what the epic will not do.'],
+  ['ACCEPTANCE', 'how anyone can tell the epic is done.'],
+  ['SPECS', 'the contracts the epic governs, or none.'],
+  ['STORY_NAME', 'the first story in a few plain words.'],
+  ['OWNED_PATHS', 'the files the first story owns, comma separated.'],
+  ['EPIC_ID', 'the epic file\'s own stem; the Queue line must equal it.'],
+  ['QUEUE_BUCKET', 'the queue section the epic\'s row stands in.'],
+];
+const TASK_KEYS = [
+  ['TASK_NAME', 'the task in a few plain words; the commit title.'],
+  ['STORY_ID', 'the story the task serves: S1, S2 and so on.'],
+  ['EPIC_ID', 'the epic the story belongs to, its file stem.'],
+  ['PLAN_PATH', 'the plan under docs/plans that carries the row.'],
+  ['ROW_ID', 'the ledger row the task carries.'],
+  ['TEST_PATH', 'the test file of the row, written first.'],
+  ['MODULE_PATH', 'the module file of the row.'],
+  ['ACCEPTANCE_COMMAND', 'a command line that proves the task done.'],
+  ['EXPECTED_OUTCOME', 'what that command answers when the task is done.'],
+  ['NEGATIVE_CASE', 'a case the task must not break.'],
+  ['NEGATIVE_OUTCOME', 'what stays true in that case.'],
+  ['TEST_MAX_LINES', 'the line budget of the test file.'],
+  ['MODULE_MAX_LINES', 'the line budget of the module file.'],
+];
+const renderTier = (toolsDir, cwd) => [
+  'An epic is one outcome too large for one plan, split into stories in its ledger under docs/ai/epics.',
+  'A story is one row of an epic\'s ledger, carried by one plan under docs/plans.',
+  'A task is one row of a story\'s plan, carried by one brief bound to a checkpoint.',
+  'A story runs as five sessions: spec, plan, tests, code, diff review + release + record.',
+  `The epic template: ${resolve(toolsDir, '../references/authoring/EPIC_TEMPLATE.md')}`,
+  `The task template: ${resolve(toolsDir, '../references/authoring/TASK_TEMPLATE.md')}`,
+  'Epic template keys:',
+  ...EPIC_KEYS.map(([key, text]) => `${INDENT}${key}: ${text}`),
+  'Task template keys:',
+  ...TASK_KEYS.map(([key, text]) => `${INDENT}${key}: ${text}`),
+  'What the setup still lacks against the reference profile is the Recommendations screen:',
+  `node ${shellQuoteArg(`${toolsDir}/recommendations.mjs`)} --cwd ${shellQuoteArg(cwd)}`,
+];
+
+const valueAt = (argv, index, flag) => {
+  const value = argv[index + 1];
+  if (value === undefined || value === '' || value.startsWith('-')) throw fail(2, `${flag} takes a value`);
+  return value;
+};
+const parseArgv = (argv) => {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    if (argv.length !== 1) throw fail(2, '--help is answered only when it is the whole invocation');
+    return { help: true };
+  }
+  return argv.reduce((parsed, arg, index) => {
+    if (parsed.skip) return { ...parsed, skip: false };
+    if (arg === '--dir') return { ...parsed, dir: valueAt(argv, index, arg), skip: true };
+    if (arg === '--json') return { ...parsed, json: true };
+    throw fail(2, `unknown argument "${arg}" — run with --help`);
+  }, { help: false, dir: '.', json: false, skip: false });
+};
+
+const renderActions = (actions, indent) => actions.flatMap((item, index) =>
+  [`${indent}${index + 1}. ${item.text}`, ...(item.command === null ? [] : [item.command])]);
+const renderResidual = (residual, indent) => residual.map(({ file, span }) => `${indent}placeholder ${span} in ${file}`);
+const renderEntry = (entry) => [
+  `${INDENT}epic ${entry.id ?? '-'} ${entry.path ?? '-'} - stage ${entry.stage}`,
+  ...(entry.cause ? [`${INDENT}${entry.cause}`] : []),
+  ...renderResidual(entry.residual, INDENT),
+  ...(entry.fact ? [`${INDENT}accepted: ${entry.fact.text}`, entry.fact.command] : []),
+  ...entry.stories.flatMap((story) => [`${INDENT}story ${story.id} - stage ${story.stage}`,
+    ...renderResidual(story.residual, INDENT + INDENT), ...renderActions(story.actions, INDENT + INDENT)]),
+  ...renderActions(entry.actions, INDENT),
+];
+const renderPlain = (tier, facts) => [
+  'TIER', ...tier,
+  ...(facts.states.length ? ['STATES', ...facts.states.flatMap((item) => [
+    `${INDENT}${item.reader}${item.file === null ? '' : ` ${item.file}`}: ${item.cause}`,
+    ...(item.next ? [`${INDENT}${INDENT}next: ${item.next.text}`, ...(item.next.command === null ? [] : [item.next.command])] : [])])] : []),
+  `EPICS (entries skipped: ${facts.skipped})`, ...facts.entries.flatMap(renderEntry),
+].join('\n');
+
+export const main = (argv, io = {}) => {
+  const log = io.log ?? console.log;
+  const error = io.error ?? console.error;
+  const parsed = (() => {
+    try { return parseArgv(argv); } catch (err) { error(err.message); return null; }
+  })();
+  if (parsed === null) return 2;
+  if (parsed.help) { log(HELP); return 0; }
+  const cwd = resolve(io.cwd ?? process.cwd(), parsed.dir);
+  const env = { ...(io.env ?? process.env), GIT_OPTIONAL_LOCKS: '0' };
+  const today = io.today ?? new Date().toISOString().slice(0, 10);
+  const facts = readTierFacts({ cwd, env, toolsDir: TOOLS_DIR, today });
+  if (facts.location.state !== 'work-tree') {
+    error(`${cwd} is not a git work tree (${facts.location.state}: ${facts.location.cause})`);
+    return 1;
+  }
+  const tier = renderTier(TOOLS_DIR, cwd);
+  log(parsed.json ? JSON.stringify({ schema: SCHEMA, command: 'tier', dir: cwd, tier,
+    states: facts.states, entries: facts.entries, skipped: facts.skipped }, null, 2) : renderPlain(tier, facts));
+  return 0;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));