@openflowjs/cli 0.2.0

package/dist/core-artifacts/openflow/scripts/openflow-evidence-reminder.cjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// PostToolUse hook: remind AI to record validation evidence before clearing active task.
+// Triggers when product code is edited while an activeTask exists and evidence is still pending.
+const { existsSync, readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf8"));
+const filePath = input?.tool_input?.file_path ?? "";
+
+// Ignore edits to .openflow/ files (those are workflow artifacts, not product code)
+if (/(?:^|\/)\.openflow\//.test(filePath)) process.exit(0);
+
+// Read current project state
+const cwd = process.cwd();
+const currentPath = join(cwd, ".openflow", "current.json");
+if (!existsSync(currentPath)) process.exit(0);
+
+try {
+  const current = JSON.parse(readFileSync(currentPath, "utf8"));
+  if (!current.activeIteration) process.exit(0);
+
+  const iterPath = join(cwd, ".openflow", "iterations", current.activeIteration);
+  const flowPath = join(iterPath, "flow.json");
+  if (!existsSync(flowPath)) process.exit(0);
+
+  const flow = JSON.parse(readFileSync(flowPath, "utf8"));
+
+  // Only trigger if there's an active task during implement
+  if (flow.stage !== "implement" || !flow.activeTask) process.exit(0);
+
+  // Check if TASKS.md has pending evidence for the active task
+  const tasksPath = join(iterPath, "TASKS.md");
+  if (!existsSync(tasksPath)) process.exit(0);
+
+  const tasksContent = readFileSync(tasksPath, "utf8");
+  const taskId = flow.activeTask;
+
+  // Look for the task's evidence field — if it says "pending", remind
+  const taskSection = tasksContent.split(new RegExp(`\\b${taskId}\\b`))[1] ?? "";
+  const evidenceMatch = taskSection.match(/Evidence:\s*(.*)/i);
+  if (!evidenceMatch || evidenceMatch[1].trim().toLowerCase() !== "pending") process.exit(0);
+
+  const msg = [
+    `📋 Task ${taskId} is active with pending evidence.`,
+    "",
+    "Before running `openflow flow set-task -`, you must:",
+    "  1. Run your validation command",
+    "  2. Record BEFORE/AFTER results in TASKS.md Evidence field",
+    "",
+    "Do not clear the active task until evidence is recorded.",
+  ].join("\n");
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        additionalContext: msg,
+      },
+    })
+  );
+} catch {
+  // Silent exit on any error — don't block the workflow
+  process.exit(0);
+}

package/dist/core-artifacts/openflow/scripts/openflow-mcp-review.cjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+const { spawn } = require("node:child_process");
+
+const isWindows = process.platform === "win32";
+const command = isWindows ? (process.env.ComSpec || "cmd.exe") : "npx";
+const args = isWindows
+  ? ["/d", "/c", "npx", "-y", "@openflowjs/cli", "mcp", "review"]
+  : ["-y", "@openflowjs/cli", "mcp", "review"];
+
+const child = spawn(command, args, {
+  stdio: "inherit",
+  windowsHide: true
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exitCode = code ?? 1;
+});
+
+child.on("error", (error) => {
+  console.error(`[openflow] failed to start MCP server: ${error.message}`);
+  process.exitCode = 1;
+});

package/dist/core-artifacts/openflow/scripts/openflow-write-guard.cjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// PostToolUse hook: remind AI to use openflow CLI instead of directly writing state files.
+const input = JSON.parse(require("node:fs").readFileSync("/dev/stdin", "utf8"));
+const filePath = input?.tool_input?.file_path ?? "";
+
+const STATE_FILES = /(?:^|\/)\.openflow\/(?:current\.json|iterations\/[^/]+\/flow\.json)$/;
+if (!STATE_FILES.test(filePath)) process.exit(0);
+
+const msg = [
+  `Direct write detected: ${filePath}`,
+  "For future state changes, prefer the openflow CLI:",
+  "  openflow flow set-stage <stage>",
+  "  openflow flow set-gate <gate>",
+  "  openflow flow set-task <id|->",
+  "  openflow flow inc-revision",
+  "  openflow iteration create <YYYY-MM-DD-slug>",
+  "  openflow iteration close",
+].join("\n");
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: msg,
+    },
+  })
+);

package/dist/core-artifacts/openflow/scripts/session-start.cjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+const { execSync } = require("node:child_process");
+
+try {
+  const output = execSync("pnpm exec openflow state --context", {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+  if (output) console.log(output);
+} catch {
+  // openflow not available or no active state — silent exit
+}

package/dist/core-artifacts/openflow/skills/brainstorm/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: openflow-brainstorm
+description: Guide requirement discussions and progressively write PRD drafts.
+depends_on: []
+---
+
+# OpenFlow Brainstorm
+
+Guide the user through structured discussion to progressively fill a PRD draft. Ask only the single most valuable question at a time, choosing the next discussion direction based on which sections have already been filled. Discussions can be interrupted and resumed.
+
+## Prerequisites
+
+1. Check whether a PRD ID parameter was passed at invocation:
+   - **With parameter**: treat as resuming an existing discussion. Jump to the "Resume" flow.
+   - **Without parameter**: use `AskUserQuestion` to prompt the user for a PRD ID in the format `YYYY-MM-DD-short-slug` (e.g., `2025-05-12-user-auth`).
+
+2. Read `.openflow/config.json` and extract the `language` field. Use this language for all generated content and user-facing questions. If absent, default to `en-US`.
+
+## Draft Creation
+
+Once a new PRD ID is determined, execute the following steps:
+
+1. Create the directory `.openflow/prds/<id>/`.
+
+2. Use the Write tool to create `prd.json`:
+
+   ```json
+   {
+     "id": "<id>",
+     "status": "draft",
+     "revision": 0,
+     "linkedIteration": null,
+     "assets": [],
+     "createdAt": "<now>",
+     "updatedAt": "<now>"
+   }
+   ```
+
+   Use ISO 8601 format for `<now>`, e.g., `2025-05-12T10:30:00+08:00`.
+
+3. Use the Write tool to create `draft.md` with a template containing 5 empty sections:
+
+   ```markdown
+   # PRD Draft: <title>
+
+   ## Background & Motivation
+   _(To be filled through discussion)_
+
+   ## Target Users
+   _(Brief sketches of who will use this — role, context, key pain point)_
+
+   ## Core Scenarios
+   _(To be filled through discussion)_
+
+   ## Key Constraints
+   _(To be filled through discussion)_
+
+   ## Initial Solution Ideas
+   _(To be filled through discussion)_
+
+   ## Decisions
+   _(Key product decisions made during discussion. Format: each entry has "Topic / Options Considered / Chosen / Rationale". Capture decisions as they're made, not at the end.)_
+   ```
+
+   Derive `<title>` from the slug portion of the PRD ID (e.g., `user-auth` becomes `User Auth`), or let the user specify it during the first discussion round.
+
+4. After creation, enter the "Discussion Loop".
+
+## Discussion Loop
+
+Each discussion round follows this flow:
+
+1. Read `draft.md` and analyze the fill status of the sections (Background & Motivation, Target Users, Core Scenarios, Key Constraints, Initial Solution Ideas).
+
+2. Select the next section to discuss by priority. Priority order:
+   - Background & Motivation
+   - Target Users
+   - Core Scenarios
+   - Key Constraints
+   - Initial Solution Ideas
+
+3. Use `AskUserQuestion` to ask one high-value question related to that section. The question should guide the user toward specific, actionable information rather than vague descriptions.
+
+4. After receiving the user's answer, use the Edit tool to update the corresponding section in `draft.md`. Organize the user's answer into clear, structured text, replacing the `_(To be filled through discussion)_` placeholder or appending to existing content.
+
+5. **Capture decisions**: whenever the discussion settles a choice between options (e.g., "use VitePress vs Docusaurus", "support 2 languages vs 1"), append an entry to the `## Decisions` section in this format:
+
+   ```markdown
+   - **<Topic>**
+     - Options Considered: <A / B / C>
+     - Chosen: <option>
+     - Rationale: <why>
+   ```
+
+   Do this immediately after a decision is made, not at the end. The Decisions section becomes the input for the PRD's Decision Log.
+
+6. Update the `updatedAt` field in `prd.json` to the current time.
+
+7. When all 5 main sections (excluding Decisions, which grows incrementally) have substantive content (not placeholders, not single-sentence vague descriptions), proactively suggest ending the discussion. Use `AskUserQuestion` with the following options:
+   - "Continue discussing the next section"
+   - "End discussion and generate PRD"
+
+   If the user chooses to continue, return to step 1 to re-evaluate each section's status and dig deeper into sections that need more content.
+
+   If the user chooses to end, proceed to the "Completion Handoff".
+
+## Resume
+
+When the user resumes an existing PRD discussion:
+
+1. Read the contents of `.openflow/prds/<id>/draft.md`.
+
+2. Analyze the fill status of each section:
+   - Whether it still contains the `_(To be filled through discussion)_` placeholder
+   - Whether the content is substantive enough (not single-sentence vague descriptions)
+
+3. Report the current status to the user: which sections are filled and which still need discussion.
+
+4. Continue the "Discussion Loop" starting from the first section with insufficient content.
+
+## Completion Handoff
+
+After the discussion is complete, inform the user:
+
+"PRD draft is complete. Run `/openflow-prd <id>` to generate the formal PRD document."
+
+Do not automatically execute subsequent commands. Only provide clear next-step instructions.
+
+## Subagent Dispatch
+
+None. Brainstorm is a purely interactive skill executed directly by the main agent. No subagent dispatch.

package/dist/core-artifacts/openflow/skills/cli-reference/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: openflow-cli-reference
+description: Reference for all openflow shell commands. Use when you need to call the CLI during spec, implement, or finalize phases, or when diagnosing state and validation errors.
+---
+
+# OpenFlow CLI Reference
+
+The `openflow` binary is a **supporting tool** for the AI workflow. The actual workflow phases live in `/openflow-spec`, `/openflow-implement`, and `/openflow-finalize`. The CLI handles infrastructure: installation, state inspection, artifact mutation, validation, and the review UI server.
+
+Never call `openflow spec`, `openflow implement`, or `openflow finalize` from the shell — they are not shell commands and will throw.
+
+---
+
+## Installation
+
+```
+openflow init
+openflow init --adapter claude-code [--target <path>] [--language zh-CN|en-US] [--force]
+openflow init --adapter claude-code --global [--force]
+```
+
+- No `--target`: installs into the current directory (`.claude/` + `.openflow/`).
+- `--global`: installs only adapter files into `~/.claude/`. Does not create `.openflow/` or `.mcp.json`.
+- `--force`: overwrites existing files. Without it, existing files are skipped.
+- `--language`: sets `.openflow/config.json` language on first install. Prompts interactively if omitted on TTY.
+
+```
+openflow update [--target <path>] [--dry-run] [--force]
+```
+
+Refreshes managed `.claude/` adapter files (commands, skills, agents, hooks) and merges missing defaults into `config.json`. Files the user has edited since install are flagged `conflict` and skipped unless `--force` is passed. Use `--dry-run` to preview without writing.
+
+---
+
+## Configuration
+
+Language is set during `openflow init` (interactive prompt or `--language` flag). Config is stored in `.openflow/config.json`.
+
+---
+
+## Project State
+
+```
+openflow state [--context]
+```
+
+- Default (no flag): prints the full project state as JSON. Fields: `language`, `defaultLevel`, `activeIteration`, `iterationPath`, `stage`, `level`, `gate`, `revision`, `activeTask`.
+- `--context`: prints `STATE.md` of the active iteration as plain text with a hint about which slash command to use next. This is what the `session-start` hook injects into the AI context window at startup.
+
+```
+openflow preflight --command spec|implement|finalize
+```
+
+Validates whether a phase can proceed. Returns JSON with:
+- `action`: `"create"` | `"continue"` | `"ok"`
+- `valid`: `true` | `false`
+- `error`: reason when `valid` is `false`
+
+Exits with code 1 when `valid` is `false`. Always call this at the start of each slash command before doing any work.
+
+---
+
+## Flow Artifact Mutations
+
+```
+openflow flow set-stage <stage>
+openflow flow set-gate <gate>
+openflow flow set-task <T-###|->
+openflow flow inc-revision
+openflow flow restart-spec
+```
+
+All four base commands mutate `flow.json` of the active iteration atomically and update `updatedAt`.
+
+| Command | When to use |
+|---------|-------------|
+| `set-stage <stage>` | Transition the iteration through its lifecycle: `spec` → `implement` → `finalize` → `archived` |
+| `set-gate <gate>` | Mark workflow gate status: `draft`, `review_required`, `changes_requested`, `approved`, `skipped`, `blocked` |
+| `set-task <T-###>` | Record which task is actively being worked on |
+| `set-task -` | Clear the active task after a task slice is complete |
+| `inc-revision` | Bump revision counter and reset gate to `draft` when reworking a rejected spec |
+| `restart-spec` | Atomic rollback to spec stage for drift recovery |
+
+Valid stages: `spec`, `blocked`, `implement`, `finalize`, `archived`
+Valid gates: `draft`, `review_required`, `changes_requested`, `approved`, `skipped`, `blocked`
+
+### `openflow flow restart-spec`
+
+Atomic rollback to Spec stage for drift recovery.
+
+**Usage:**
+```bash
+openflow flow restart-spec --reason "<drift reason>" --task <T-###>
+```
+
+**Parameters:**
+- `--reason` (required): Description of the spec drift reason
+- `--task` (required): Task ID that triggered the drift
+
+**Behavior:**
+1. Increment flow.json revision
+2. Set stage to "spec"
+3. Set gate to "draft"
+4. Clear activeTask
+5. Append Drift Log entry to STATE.md (with date, reason, source task ID)
+
+---
+
+## Iteration Lifecycle
+
+```
+openflow iteration create <YYYY-MM-DD-slug>
+openflow iteration close
+```
+
+- `create`: makes the directory `.openflow/iterations/<id>/` and writes `current.json` with `activeIteration` pointing to it.
+- `close`: writes `current.json` with `activeIteration: null`. Call this at the end of finalize after moving the folder.
+
+---
+
+## Validation
+
+```
+openflow validate [--flow <path>] [--json]
+```
+
+Reads all required artifacts (`flow.json`, `STATE.md`, `SPEC.md`, `CONTEXT.md`, `TASKS.md`) and optional artifacts (`config.json`, reviews, `SUMMARY.md`, extension results), then runs schema validation. Exits with code 1 on any error-severity issue.
+
+- `--flow .openflow`: resolves the active iteration from `current.json` automatically.
+- `--flow .openflow/iterations/<id>`: validates a specific iteration directory directly.
+- `--json`: outputs `{ valid, issues }` as JSON instead of human-readable output.
+
+Run `openflow validate` after writing artifacts and before triggering review.
+
+---
+
+## Review UI
+
+```
+openflow review [--flow .openflow] [--mode spec|prd] [--port 3456] [--wait] [--json] [--no-open]
+```
+
+Starts the HTTP Review UI (React SPA). This is the **fallback** path when MCP is not available. Prefer the MCP tools (`openflow_review_start` / `openflow_review_wait`) when running inside an AI tool.
+
+- `--wait`: block until a review is submitted, then exit. Without it, the server runs until Ctrl+C.
+- `--no-open`: suppress automatic browser launch.
+- `--json`: emit `{ url, flow, mode }` as JSON to stdout (suppresses browser launch by default).
+
+```
+openflow mcp review
+```
+
+Starts the MCP stdio server. This is wired up automatically via `.mcp.json` so AI tools can call review tools without launching a shell command. Do not call this manually.
+
+---
+
+## Common Patterns
+
+**Start of every slash command:**
+```
+openflow preflight --command <spec|implement|finalize>
+```
+Parse the JSON. Stop immediately if `valid` is `false`.
+
+**After creating a new iteration (spec phase):**
+```
+openflow iteration create YYYY-MM-DD-slug
+openflow state   # get iterationPath for subsequent commands
+```
+
+**After writing artifacts:**
+```
+openflow validate --flow .openflow/iterations/<id>
+```
+
+**During implement — task lifecycle:**
+```
+openflow flow set-task T-001
+# ... implement ...
+openflow flow set-task -
+openflow validate --flow .openflow/iterations/<id>
+```
+
+**Triggering review (when MCP is available, prefer this):**
+```
+openflow_review_start  →  openflow_review_wait  →  openflow_review_close
+```
+
+**Completing finalize:**
+```
+openflow flow set-stage archived
+openflow flow set-gate approved
+openflow validate --flow <iterationPath>
+# mv iterationPath to .openflow/archive/<id>
+openflow iteration close
+```

package/dist/core-artifacts/openflow/skills/finalize/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: openflow-finalize
+description: Use for the OpenFlow finalize phase: final validation, knowledge capture, review, commit support, and archival.
+---
+
+# OpenFlow Finalize
+
+Close the flow so `.openflow/` explains what shipped, how it was validated, what remains, and what knowledge should persist.
+
+This skill depends on:
+
+- `openflow-workflow-governance` for level, stage, and gate rules.
+- `openflow-cli-reference` for exact CLI command syntax and options.
+
+## Inputs
+
+- `.openflow/current.json`
+- active iteration `flow.json`
+- active iteration `STATE.md`
+- active iteration `SPEC.md`
+- active iteration `TASKS.md`
+- active iteration `CONTEXT.md`
+- active iteration `PLAN.md` when present
+- active iteration `reviews/spec-review.json`
+- active iteration `extensions/**/result.json`
+- Repository diff and validation output
+
+## Archive Gate
+
+Before finalize:
+
+- Run `openflow validate --flow .openflow/iterations/<iteration-id>`.
+- Confirm all completed tasks have evidence.
+- Confirm incomplete tasks are explicitly marked `deferred:`, `blocked:`, or `waived:` with rationale.
+- Confirm required extension results passed or have explicit accepted deferral.
+- Run final relevant project validation.
+- For code changes with behavior impact, use `code-reviewer` (mode: compliance) followed by `code-reviewer` (mode: quality) for complex reviews. Use `artifact-reviewer` (mode: docs) when documentation impact warrants it.
+- Use `artifact-reviewer` (mode: validation) when evidence quality is uncertain.
+
+## Flow
+
+1. Run `openflow preflight --command finalize` and parse the JSON output. If `valid` is `false`, stop and tell the user what went wrong in plain language — do not show the raw preflight error.
+2. Use `language` and `iterationPath` from the output for all subsequent steps.
+3. Read `flow.json`, `STATE.md`, `SPEC.md`, `TASKS.md`, `CONTEXT.md`, optional `PLAN.md`, `reviews/spec-review.json`, extension results, and current repository status from `iterationPath`.
+4. Run `openflow validate --flow .openflow/iterations/<iteration-id>`.
+5. Confirm every completed task has evidence and every required extension passed or has an accepted deferral.
+6. Confirm every incomplete task is explicitly deferred, blocked, or waived with rationale before final finalize.
+7. Run final project validation relevant to the diff.
+8. Write `SUMMARY.md` with shipped changes, validation evidence, deferred items, and durable knowledge. Use the template in `references/summary-template.md`.
+9. Use `artifact-reviewer` (mode: validation) when task evidence or extension results need a final readiness check.
+10. **Extract structured knowledge** to `.openflow/knowledge/`, using `WORKING_MEMORY.md` as the primary source:
+    - **Primary source — WORKING_MEMORY.md** (located at `.openflow/iterations/<iteration-id>/WORKING_MEMORY.md`):
+      - Read the three append-only sections:
+        - `## Execution Observations` → extract potential `decision` and `guideline` knowledge from execution observations.
+        - `## Knowledge Candidates` → use directly as candidate input for knowledge extraction.
+        - `## Blockers and Resolutions` → extract `pitfall` knowledge from blocker descriptions and their resolutions.
+    - **Fallback source — SUMMARY.md**: use `SUMMARY.md` only when `WORKING_MEMORY.md` does not exist or all three append-only sections are empty.
+    - **Call `knowledge-curator` Agent** for each candidate knowledge entry to perform:
+      - **Dedup check** (`dedup` operation): compare summary + tags with existing entries in `.openflow/knowledge/` of the same type. Skip if a duplicate is found, or merge into the existing entry.
+      - **Schema validation** (`validate` operation): ensure frontmatter conforms to the schema defined in `workflow-governance` `references/knowledge-schema.md`.
+    - **Create knowledge files by type** (follow file format in `workflow-governance` `references/knowledge-schema.md`):
+      - `decision` → `.openflow/knowledge/decisions/NNN-<slug>.md`
+      - `guideline` → `.openflow/knowledge/guidelines/NNN-<slug>.md`
+      - `pitfall` → `.openflow/knowledge/pitfalls/NNN-<slug>.md`
+      - `process` → `.openflow/knowledge/processes/NNN-<slug>.md`
+    - **Update indexes** after creating knowledge files:
+      - Regenerate `.openflow/knowledge/catalog.json` from all knowledge files.
+      - Update the per-type `index.json` in each affected type directory.
+      - Regenerate `.openflow/knowledge/CATALOG.md` from the updated catalog data.
+    - Only extract when the extraction criteria in `workflow-governance` are met.
+    - If no durable knowledge meets extraction criteria, skip this step.
+11. Verify knowledge files were created correctly by checking the format follows the `workflow-governance` `references/knowledge-schema.md` specification.
+12. Run `openflow flow set-stage archived` and `openflow flow set-gate approved`, then run `openflow validate --flow <iterationPath>`.
+13. Move the iteration folder to the archive:
+  ```bash
+  mv .openflow/iterations/<iteration-id> .openflow/archive/<iteration-id>
+  ```
+14. Run `openflow iteration close` to clear `activeIteration`.
+15. Produce commit support according to the project policy.
+
+Do not finalize if validation is failing.
+Write generated OpenFlow documents in the resolved language; default to `en-US` if not configured.
+Do not use OpenFlow MCP for workflow state management. MCP is only for Review UI interaction; write `.openflow` artifacts directly and validate them with `openflow validate`.
+
+## Summary Rules
+
+Write active iteration `SUMMARY.md` with:
+
+- Shipped Changes
+- Validation Evidence
+- Deferred Items
+- Durable Knowledge
+
+Durable knowledge should include project conventions, decisions, domain language, and recurring failure modes worth preserving.
+
+Extract knowledge files only when there is durable knowledge with future reuse value. Do not create long-term knowledge for ordinary task logs.
+
+## Commit Support
+
+Follow the host repository policy. If committing is not appropriate, produce a commit message draft and list the files that changed.
+
+## User-Facing Output
+
+When communicating with the user:
+
+- Do not show raw `openflow validate` or `openflow preflight` error codes, field names, or schema rules. Translate errors into plain language (e.g. "There is a formatting issue in SUMMARY.md").
+- Do not explain internal OpenFlow state machine concepts (gates, stages, revisions, level routing rationale) unless the user asks.
+- Do not output "Insight" blocks about OpenFlow's internal mechanics, validation rules, or artifact schemas.
+- Keep status updates short: what was archived and what the user should do next.

package/dist/core-artifacts/openflow/skills/finalize/references/summary-template.md

@@ -0,0 +1,39 @@
+# SUMMARY.md
+
+`SUMMARY.md` is the final human-readable closeout for `/openflow-finalize`.
+
+Location:
+
+```text
+.openflow/iterations/<iteration-id>/SUMMARY.md
+```
+
+Template:
+
+```markdown
+# Summary
+
+## Shipped Changes
+
+- <what changed, grouped by user-visible or system outcome>
+
+## Validation Evidence
+
+- <commands, test results, screenshots, review signals, or extension results>
+
+## Deferred Items
+
+- <deferred, blocked, or waived work with rationale>
+
+## Durable Knowledge
+
+- <project conventions, decisions, domain language, or recurring failure modes worth preserving>
+```
+
+Rules:
+
+- Write the summary before final archive validation.
+- Do not repeat every implementation detail; summarize outcomes and evidence.
+- Every completed task in `TASKS.md` should be represented by validation evidence here.
+- Deferred items must match unchecked tasks or known follow-ups.
+- Durable knowledge is optional in substance but the heading is required. Use `None identified.` when there is nothing worth preserving.