@sabaiway/agent-workflow-kit 14.7.0 → 14.9.0

package/CHANGELOG.md

@@ -4,6 +4,70 @@ 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.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
+two shapes lived only in the planning reference and in what `epic-shape-cli` and `task-brief` refuse. The kit now
+ships `references/authoring/EPIC_TEMPLATE.md` and `references/authoring/TASK_TEMPLATE.md` in its skill home. Copy one
+from there into your project, replace every `{{KEY}}` placeholder with a value its checker admits and change no
+other byte: the epic, placed at `docs/ai/epics/<EPIC_ID>.md`, passes `epic-shape-cli --check`; the brief, placed at
+`docs/plans/TASK-<stem>-T<n>.md` beside a plan that carries the same Story line and the named row, with a checkpoint
+minted, is stamped by `task-brief stamp` and passes `task-brief check`. A template copied and left unedited is
+refused: the epic by the check, the brief by the stamp.
+Story S2 of the epic `KIT-USERS-LEARN-THE-TIER-AND-WALK-IT`; contract `docs/ai/specs/kit/tier/tier-templates.md`
+(new), with `docs/ai/specs/kit/tier/tier-walk.md` at revision 2.
+
+- **Two templates, one placeholder form, a closed key list each.** The epic template carries eleven keys (`DATE`,
+  `EPIC_TITLE`, `INTENT`, `VALUE`, `NON_GOALS`, `ACCEPTANCE`, `SPECS`, `STORY_NAME`, `OWNED_PATHS`, `EPIC_ID`,
+  `QUEUE_BUCKET`) and one story row; the brief template carries thirteen keys and one task with one test file and one
+  module. Neither carries guidance prose: a template is the shape and its placeholders only. Where a grammar leaves a
+  choice, the template makes it: the epic opens `state: open` with `S1` planned, `depends-on: none` and
+  `shared: none`; the brief groups `test, impl` and reads the plan alone. For more stories, files or cases, repeat
+  the line in the form its checker takes: the next story id, and a `## Budget` line for each added file.
+- **Not deployed into a project.** The directory sits outside `references/templates/`, so neither `bootstrap` nor
+  `upgrade` copies anything from it into `docs/ai/`; `init` places it in the kit's skill home only. Nothing in the
+  kit points at the templates yet; the guide that explains each key comes with a later story of the same epic.
+- **Internals.** The repository walk fixture `test/tier-walk-e2e.test.mjs` now renders its epic and brief from the
+  installed templates, pins each template's bytes to a literal text, and checks that an unedited copy is refused; its
+  ground helpers move to `test/tier-walk-harness.test.mjs`. The package-content pin names both files, and the tarball
+  holds 333 files. Neither test file ships.
+
 ## 14.7.0 — an epic closes in a project with no queue file, every task-brief refusal says what failed, and the missing-section offer is a command you can run (AD-153)
 
 **A project outside this repo can now walk one epic, one story and one task to the end, solo.** A walk through the

package/SKILL.md

@@ -3,7 +3,7 @@ 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".
 disable-model-invocation: true
 metadata:
-  version: '14.7.0'
+  version: '14.9.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/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.7.0",
+  "version": "14.9.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/authoring/EPIC_TEMPLATE.md

@@ -0,0 +1,32 @@
+---
+type: epic
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 60
+state: open
+---
+
+# Epic: {{EPIC_TITLE}}
+
+## Intent
+{{INTENT}}
+
+## Value
+{{VALUE}}
+
+## Non-goals
+{{NON_GOALS}}
+
+## Acceptance
+{{ACCEPTANCE}}
+
+## Specs
+{{SPECS}}
+
+## Stories ledger
+- S1 | {{STORY_NAME}} | depends-on: none | owns: {{OWNED_PATHS}} | shared: none | state: planned
+
+## Queue
+Row {{EPIC_ID}} in {{QUEUE_BUCKET}}

package/references/authoring/TASK_TEMPLATE.md

@@ -0,0 +1,23 @@
+# Task: {{TASK_NAME}}
+Story: {{STORY_ID}} of {{EPIC_ID}}
+
+## Slice
+Plan: {{PLAN_PATH}}
+Row: {{ROW_ID}}
+Grouping: test, impl
+Files:
+- {{TEST_PATH}} :: test
+- {{MODULE_PATH}} :: impl
+
+## Reads
+- {{PLAN_PATH}}
+
+## Acceptance
+- {{ACCEPTANCE_COMMAND}} :: {{EXPECTED_OUTCOME}}
+
+## Negative cases
+- {{NEGATIVE_CASE}} :: {{NEGATIVE_OUTCOME}}
+
+## Budget
+- {{TEST_PATH}} :: {{TEST_MAX_LINES}}
+- {{MODULE_PATH}} :: {{MODULE_MAX_LINES}}

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/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));