@jamie-tam/forge 6.0.0

package/skills/support-wiki-lint/scripts/lint.test.mjs

@@ -0,0 +1,196 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { lint, parseYaml } from './lint.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, '../../..');
+const templateSchemasDir = path.join(repoRoot, 'templates/aiwiki/schemas');
+
+function mkTempRoot() {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-lint-test-'));
+	// Copy schemas the lint script reads.
+	const schemasDir = path.join(root, 'schemas');
+	fs.mkdirSync(schemasDir, { recursive: true });
+	for (const entry of fs.readdirSync(templateSchemasDir)) {
+		fs.copyFileSync(path.join(templateSchemasDir, entry), path.join(schemasDir, entry));
+	}
+	return { root, schemasDir };
+}
+
+function writeFile(root, rel, content) {
+	const full = path.join(root, rel);
+	fs.mkdirSync(path.dirname(full), { recursive: true });
+	fs.writeFileSync(full, content);
+}
+
+const GOOD_GOTCHA = `---
+schema_id: gotcha
+schema_version: 1
+severity: medium
+date: 2026-05-12
+occurrences: 1
+status: active
+---
+
+# Stub logger throws under server-rendered hydration
+
+## What broke
+
+The logger stub threw \`NotImplemented\` when rendered twice (server + client).
+
+## Reproducer
+
+Run a Next.js page that imports the stub logger; observe the throw on client mount.
+
+## Root cause
+
+Logger was initialized twice but only one stub path was instrumented to throw.
+
+## Fix
+
+Throw on both stub paths so the call site is forced to inject a real logger.
+
+## Prevention
+
+When stubbing module-level singletons, throw on every code path that could fire.
+`;
+
+test('parseYaml handles a minimal mapping', () => {
+	const parsed = parseYaml('schema_id: gotcha\nseverity: medium\n');
+	assert.equal(parsed.schema_id, 'gotcha');
+	assert.equal(parsed.severity, 'medium');
+});
+
+test('parseYaml handles inline mapping values', () => {
+	const parsed = parseYaml('field: { type: enum, values: [low, high] }\n');
+	assert.deepEqual(parsed.field, { type: 'enum', values: ['low', 'high'] });
+});
+
+test('valid gotcha page passes lint', () => {
+	const { root, schemasDir } = mkTempRoot();
+	writeFile(root, 'aiwiki/gotchas/2026-05-12-stub-logger.md', GOOD_GOTCHA);
+	const result = lint({ file: 'aiwiki/gotchas/2026-05-12-stub-logger.md', schemasDir, root });
+	assert.equal(result.ok, true, `lint errors: ${JSON.stringify(result.errors)}`);
+	assert.equal(result.errors.length, 0);
+});
+
+test('missing required frontmatter field is flagged', () => {
+	const { root, schemasDir } = mkTempRoot();
+	const badFrontmatter = GOOD_GOTCHA.replace('severity: medium\n', '');
+	writeFile(root, 'aiwiki/gotchas/bad.md', badFrontmatter);
+	const result = lint({ file: 'aiwiki/gotchas/bad.md', schemasDir, root });
+	assert.equal(result.ok, false);
+	assert.ok(
+		result.errors.some((e) => e.kind === 'frontmatter_invalid' && e.field === 'severity'),
+		`expected severity field error, got: ${JSON.stringify(result.errors)}`,
+	);
+});
+
+test('bad enum value is flagged', () => {
+	const { root, schemasDir } = mkTempRoot();
+	const badEnum = GOOD_GOTCHA.replace('severity: medium', 'severity: lukewarm');
+	writeFile(root, 'aiwiki/gotchas/bad.md', badEnum);
+	const result = lint({ file: 'aiwiki/gotchas/bad.md', schemasDir, root });
+	assert.equal(result.ok, false);
+	assert.ok(
+		result.errors.some((e) => e.kind === 'frontmatter_invalid' && e.field === 'severity'),
+		`expected severity enum error, got: ${JSON.stringify(result.errors)}`,
+	);
+});
+
+test('missing required H2 section is flagged', () => {
+	const { root, schemasDir } = mkTempRoot();
+	const noSection = GOOD_GOTCHA.replace(/## Root cause[\s\S]*?## Fix/, '## Fix');
+	writeFile(root, 'aiwiki/gotchas/bad.md', noSection);
+	const result = lint({ file: 'aiwiki/gotchas/bad.md', schemasDir, root });
+	assert.equal(result.ok, false);
+	assert.ok(
+		result.errors.some((e) => e.kind === 'missing_section' && e.section === '## Root cause'),
+		`expected missing-section error, got: ${JSON.stringify(result.errors)}`,
+	);
+});
+
+test('out-of-order sections trip section_order_violation', () => {
+	const { root, schemasDir } = mkTempRoot();
+	const swapped = GOOD_GOTCHA
+		.replace(/## What broke[\s\S]*?(?=## Reproducer)/, (m) => m)
+		// Move ## Fix before ## Root cause
+		.replace(/## Root cause([\s\S]*?)## Fix([\s\S]*?)## Prevention/, '## Fix$2## Root cause$1## Prevention');
+	writeFile(root, 'aiwiki/gotchas/bad.md', swapped);
+	const result = lint({ file: 'aiwiki/gotchas/bad.md', schemasDir, root });
+	assert.equal(result.ok, false);
+	assert.ok(
+		result.errors.some((e) => e.kind === 'section_order_violation'),
+		`expected section_order_violation, got: ${JSON.stringify(result.errors)}`,
+	);
+});
+
+test('hard_cap_lines exceeded is flagged', () => {
+	const { root, schemasDir } = mkTempRoot();
+	// gotcha schema's hard_cap_lines is 150. Pad with bullet lines.
+	const padding = Array.from({ length: 200 }, (_, i) => `- padding line ${i}`).join('\n');
+	const tooLong = GOOD_GOTCHA.replace('## Prevention', `## Prevention\n\n${padding}\n\n## Other`);
+	writeFile(root, 'aiwiki/gotchas/bad.md', tooLong);
+	const result = lint({ file: 'aiwiki/gotchas/bad.md', schemasDir, root });
+	assert.equal(result.ok, false);
+	assert.ok(
+		result.errors.some((e) => e.kind === 'hard_cap_exceeded'),
+		`expected hard_cap_exceeded, got: ${JSON.stringify(result.errors)}`,
+	);
+});
+
+test('missing schema_id is rejected', () => {
+	const { root, schemasDir } = mkTempRoot();
+	const noSchemaId = GOOD_GOTCHA.replace('schema_id: gotcha\n', '');
+	writeFile(root, 'aiwiki/gotchas/bad.md', noSchemaId);
+	const result = lint({ file: 'aiwiki/gotchas/bad.md', schemasDir, root });
+	assert.equal(result.ok, false);
+	assert.ok(
+		result.errors.some((e) => e.kind === 'frontmatter_invalid' && /schema_id/.test(e.message)),
+		`expected schema_id error, got: ${JSON.stringify(result.errors)}`,
+	);
+});
+
+test('unknown schema_id is rejected', () => {
+	const { root, schemasDir } = mkTempRoot();
+	const wrongSchema = GOOD_GOTCHA.replace('schema_id: gotcha', 'schema_id: nonexistent');
+	writeFile(root, 'aiwiki/gotchas/bad.md', wrongSchema);
+	const result = lint({ file: 'aiwiki/gotchas/bad.md', schemasDir, root });
+	assert.equal(result.ok, false);
+	assert.ok(
+		result.errors.some((e) => e.kind === 'missing_schema'),
+		`expected missing_schema error, got: ${JSON.stringify(result.errors)}`,
+	);
+});
+
+test('bare citation auto-backfills @<sha7>', () => {
+	const { root, schemasDir } = mkTempRoot();
+	// Create a real source file inside a git repo so the lint script can compute its hash.
+	execSync('git init -q', { cwd: root });
+	execSync('git config user.email test@example.com', { cwd: root });
+	execSync('git config user.name Test', { cwd: root });
+	writeFile(root, 'src/handler.ts', 'export function handler() {\n  return 1;\n}\n');
+	execSync('git add . && git commit -q -m init', { cwd: root });
+
+	const pageWithBareCite = GOOD_GOTCHA.replace(
+		'## Reproducer',
+		'## Reproducer\n\nSee src/handler.ts:1 for the broken path.',
+	);
+	writeFile(root, 'aiwiki/gotchas/cite.md', pageWithBareCite);
+
+	const result = lint({ file: 'aiwiki/gotchas/cite.md', schemasDir, root });
+	// Either backfilled (auto-fix) or flagged — both are valid lint outcomes
+	// depending on whether updates[] auto-applies. Check that the lint at least
+	// processed the citation rather than crashing.
+	assert.ok(result.errors !== undefined, 'lint should return an errors array');
+	// If an update was emitted, the file should now contain an @<sha7> citation.
+	if (result.updates && result.updates.length > 0) {
+		const updated = fs.readFileSync(path.join(root, 'aiwiki/gotchas/cite.md'), 'utf8');
+		assert.match(updated, /src\/handler\.ts:1@[0-9a-f]{7}/, 'expected backfilled citation hash');
+	}
+});

package/templates/README.md

@@ -0,0 +1,23 @@
+# templates/
+
+Templates copied into user projects by `npx @jamie-tam/forge init`, plus schema docs used internally by forge maintainers.
+
+## User-installed templates
+
+Installed into the target project by `npx @jamie-tam/forge init` (or kept in-sync by subsequent updates). These are the files real users of forge see.
+
+- **`manifests/`** — Canonical work-manifest templates, one per work type (`feature.yaml`, `greenfield.yaml`, `bugfix.yaml`, `hotfix.yaml`, `refactor.yaml`). Written to `.forge/work/{type}/{name}/manifest.yaml` when a work command starts. Each manifest is the source of truth for its schema shape — do not duplicate schema documentation elsewhere.
+- **`aiwiki/`** — Seed contents for the project's `aiwiki/` directory: the `CLAUDE.md.template` that auto-loads wiki usage rules, plus the `schemas/` folder defining the file shape for conventions, gotchas, architecture, decisions, and sessions.
+- **`wiki-html/`** — Single-file HTML pages (e.g. `dreams-list.html`, `dream-detail.html`) used by the wiki review UI surfaced via the forge CLI.
+
+## Legacy
+
+Kept on-disk so older manifests still parse and so `/evolve` can migrate them forward. Not installed into new projects.
+
+- **`manifests/v5/`** — v5 schema (`SCHEMA.md` plus a `feature.yaml` reference). v5 manifests still parse against the v6 reader (see `manifests/v6/SCHEMA.md` §4). v4 manifests also still parse but no template is retained — the reader synthesizes the missing fields.
+
+## Internal
+
+Used by forge maintainers writing the parser/verifier and the migration logic. Not consumed at user runtime.
+
+- **`manifests/v6/SCHEMA.md`** — Source of truth for v6 manifest validation rules. The reader and verifier in `src/work-manifest.ts` implement against this document. v6's delta over v5 is the additive `phase_plan:` block (see §3). Update this file alongside any change to manifest shape or allowed plan-status values.

package/templates/aiwiki/CLAUDE.md.template

@@ -0,0 +1,78 @@
+# Wiki usage rules (auto-loaded every session)
+
+This file is loaded automatically by Claude Code at session start. It tells you (the AI) how to use the `aiwiki/` directory in this project.
+
+## Reading
+
+Before answering any non-trivial question, check the wiki:
+
+- `aiwiki/conventions/` — for "how does this codebase do X?"
+- `aiwiki/gotchas/` — for "have we hit this before?"
+- `aiwiki/architecture/` — for "what is the system shape?"
+- `aiwiki/decisions/` — for "why was this chosen?"
+- `aiwiki/oracles/` — for "what behavior must the production code reproduce from the prototype?"
+
+The wiki is curated to answer recurring questions. **Use it before asking the user.**
+
+## Writing
+
+When you make a decision that's hard to reverse — architectural choice, public-surface naming (APIs / schemas / file paths users import), security or data-handling tradeoff, schema design, or a contract that other parts of the codebase depend on:
+- Write an ADR in `aiwiki/decisions/`. Format per `aiwiki/schemas/decision.md`. Invoke `/second-opinion` to get adversarial review before marking `status: accepted`.
+
+When you encounter a recurring failure:
+- Write a gotcha in `aiwiki/gotchas/`. Format per `aiwiki/schemas/gotcha.md`.
+- If the gotcha file's `occurrences` reaches 3+, the gotcha is auto-drafted as a `proposed_rule:` block; the next session-start hard-interrupts to require user approval before promoting the rule.
+
+When you discover a codebase convention:
+- Write to `aiwiki/conventions/`. Format per `aiwiki/schemas/convention.md`.
+
+When you make a system-shape change:
+- Write to `aiwiki/architecture/{topic}.md`. Format per `aiwiki/schemas/architecture.md`.
+- One file per topic — do NOT collapse multiple subsystems into a single mega-file.
+
+When unsure where something belongs:
+- Write to `aiwiki/raw/{YYYY-MM-DD}-{slug}.md`. Phase-close dream consolidates raw entries into typed pages.
+
+## Citations
+
+Cite code with `file:line@<sha7>` (e.g. `src/auth.ts:42@a3f2bc1`) or `symbol` form (e.g. `src/auth.ts#login`). The `@<sha7>` part is auto-filled by LINT on first save.
+
+When the cited code moves, LINT flags the citation as stale on the next wiki write. Resolve by:
+- Updating the citation to the new location, OR
+- Removing the claim that depended on it, OR
+- Annotating `// ack-stale: <reason>` on the citing line if the staleness is acceptable for now.
+
+## Reviewing dream output
+
+The wiki is consolidated periodically by **dream** (forge's wiki-consolidation mechanism — see `support-dream` skill). Dream output goes to `aiwiki/proposed/{dream_id}/` and is **never auto-applied** to `aiwiki/`.
+
+When pending dreams exist:
+- Run `forge wiki status` to see the queue
+- Run `forge wiki review [dream_id]` to review per-page diffs
+- Run `forge wiki accept [dream_id]` or `forge wiki reject [dream_id] --reason "..."` to resolve
+
+You will be notified at session start (soft) and at phase-close (hard interrupt if a phase-close dream is pending).
+
+## Phase vocabulary
+
+When a skill or agent states its phase context, the canonical numbering and names are defined in `.claude/references/common/phases.md`. Load it when in doubt — different files reusing the wrong phase numbers is the dominant source of operational confusion. Phases are defaults, not requirements; manifest tracks deviations.
+
+## Rules and references — what applies when
+
+Forge tiers code-standards content by phase to match its prototype-driven SDLC. The thesis: prototype iteration should be fast and unconstrained by style/convention rules; production-grade standards take effect when the prototype is codified.
+
+| Tier | Files | Active during |
+|---|---|---|
+| Always-on (safety floor) | `.claude/rules/common/security.md`, `guardrails.md`, `verification.md` | Every phase. Prevents classes of issues that are expensive to retrofit (injection, missing input validation, unverified completion claims). |
+| Phase-conditional | `.claude/rules/common/testing.md`, `quality-gates.md`, `git-workflow.md` | Phase 5 (codify) onward. Headers in those files mark the transition explicitly. |
+| References (load on demand) | `.claude/references/common/coding-standards.md`, `.claude/references/{language}/standards.md` (typescript, react, python) | Loaded by the `harden` skill / `prototype-codifier` agent at codify time. Not active during prototype iteration. |
+
+**Implication for AI agents:** during Phases 1–4 (concept → wireframe → prototype → iterate), follow the safety floor only — do not preemptively apply style/convention/testing standards. During Phase 5 (codify/harden) onward, load the references and phase-conditional rules listed above.
+
+## Forbidden
+
+- **Never edit `aiwiki/proposed/` directly** — that's dream output for review. Edit `aiwiki/` if you need to change something; dream re-runs on the new state next cycle.
+- **Never duplicate code in wiki entries** — cite instead. The code is the truth; the wiki points at it.
+- **Never write speculation, conversation history, or "we might want to revisit this" notes** — those don't answer recurring questions. They're noise.
+- **Never write to `.forge/work/manifest.yaml` from a wiki context** — the manifest is operational state for hooks/gates, not knowledge. Wiki and manifest are separate.
+- **Every section in a wiki page must answer a recurring AI question.** If a section doesn't get re-read, it doesn't belong. When in doubt, omit.

package/templates/aiwiki/schemas/architecture.md

@@ -0,0 +1,118 @@
+---
+schema_id: architecture
+schema_version: 1
+applies_to: aiwiki/architecture/**/*.md
+filename_pattern: "{topic}.md"
+hard_cap_lines: 400
+soft_target_lines: [100, 250]
+required_frontmatter:
+  schema_id: { type: string, equals: architecture }
+  schema_version: { type: integer }
+  scope: { type: string, pattern: "^(project|subsystem:.+)$" }
+  date: { type: date }
+  status: { type: enum, values: [active, proposed, superseded] }
+required_sections:
+  - "## The shape"
+  - "## Components"
+  - "## Boundaries"
+  - "## Tradeoffs"
+section_order: strict
+citation_rule: required-in-components
+---
+
+# Schema: architecture (system-shape doc)
+
+## Purpose
+
+An architecture file describes the shape of a subsystem — what its parts are, what's in and out of scope, what tradeoffs were taken. The page answers "what is this system? what does each piece do? where does it stop?" so future contributors don't have to reverse-engineer.
+
+**One file per topic.** Multiple focused files (`data-layer.md`, `auth-flow.md`, `event-bus.md`) — NOT one giant `architecture.md`. A 400-line file forced into existence by combining unrelated subsystems is unreadable.
+
+## When to write one
+
+- During Phase 5 codification (`harden`) — extract architecture from the locked prototype
+- When a subsystem grows past ~3 files and a "what does this do" overview becomes valuable
+- After a refactor that meaningfully reshapes a subsystem (write the new shape; mark the old one `superseded`)
+
+Do NOT write an architecture file for: a single function or class (write a comment in the code), a feature you haven't built yet (write a plan in `.forge/work/`), an entire codebase summary (split by subsystem).
+
+## File location and naming
+
+- Path: `aiwiki/architecture/{topic}.md`
+- Topic: kebab-case, names the subsystem or concern (not the document type)
+
+Examples: `data-layer.md`, `auth-flow.md`, `event-bus.md`, `frontend-state-model.md`.
+
+## Required frontmatter
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_id` | string | Must equal `architecture` |
+| `schema_version` | integer | — |
+| `scope` | string | `project` / `subsystem:<name>` |
+| `date` | ISO date | When this shape was codified or last refreshed |
+| `status` | enum | `active` (current) / `proposed` (not yet implemented) / `superseded` (old shape; link successor) |
+
+## Required sections
+
+| Section | Purpose | Format |
+|---|---|---|
+| `## The shape` | What it looks like at a glance | Mermaid diagram OR ≤5-sentence prose summary |
+| `## Components` | What each part does | Bulleted list with citations to the actual code |
+| `## Boundaries` | What's in scope, what's out, and where the seams are | Bullets — explicit "in" and "out" |
+| `## Tradeoffs` | What was rejected and why | Link to ADRs in `aiwiki/decisions/` |
+
+## Line caps
+
+- Hard cap: 400 lines (LINT fails above)
+- Soft target: 100-250 lines
+
+If a subsystem genuinely needs >400 lines to describe, split it: `auth-flow.md` + `auth-token-storage.md` + `auth-session-lifecycle.md` rather than one mega-file.
+
+## Citation rules
+
+- `## Components` MUST cite the responsible files/symbols with `file:line@<sha7>` or `symbol` form
+- `## The shape` may use Mermaid (no citations needed) or prose (cite if making code claims)
+- `## Tradeoffs` should link to ADRs that capture the decisions
+- LINT auto-fills missing `@<sha7>` on first save
+
+## Skeleton
+
+```markdown
+---
+schema_id: architecture
+schema_version: 1
+scope: subsystem:auth
+date: 2026-05-10
+status: active
+---
+
+## The shape
+
+```mermaid
+flowchart LR
+  Client -->|credentials| AuthHandler
+  AuthHandler -->|verified| TokenIssuer
+  TokenIssuer -->|signed token| Client
+  Client -->|token| ProtectedRoute
+  ProtectedRoute -->|verify| TokenValidator
+```
+
+## Components
+
+- `AuthHandler` ([src/auth/handler.ts#authHandler](src/auth/handler.ts)) — accepts credentials, dispatches to credential validator
+- `TokenIssuer` ([src/auth/token.ts#issueToken](src/auth/token.ts)) — signs JWT with HS256; lifetime 24h
+- `TokenValidator` ([src/auth/middleware.ts#validateToken](src/auth/middleware.ts)) — verifies signature + expiry on every protected request
+
+## Boundaries
+
+**In scope**: credential validation, token issuance, token verification middleware.
+
+**Out of scope**: user CRUD (lives in [aiwiki/architecture/users.md](aiwiki/architecture/users.md)), password reset flow (lives in [aiwiki/architecture/password-reset.md](aiwiki/architecture/password-reset.md)), MFA (deferred — see [aiwiki/decisions/0023-mfa-deferral.md](aiwiki/decisions/0023-mfa-deferral.md)).
+
+## Tradeoffs
+
+- HS256 over RS256: chosen for single-service deployment ([aiwiki/decisions/0008-jwt-algorithm.md](aiwiki/decisions/0008-jwt-algorithm.md))
+- 24h token lifetime over refresh-token pair: chosen for simplicity at MVP scale ([aiwiki/decisions/0009-token-lifetime.md](aiwiki/decisions/0009-token-lifetime.md))
+- Stateless JWT over session-store pattern: chosen for horizontal scalability ([aiwiki/decisions/0007-stateless-auth.md](aiwiki/decisions/0007-stateless-auth.md))
+```

package/templates/aiwiki/schemas/convention.md

@@ -0,0 +1,112 @@
+---
+schema_id: convention
+schema_version: 1
+applies_to: aiwiki/conventions/**/*.md
+filename_pattern: "{slug}.md"
+hard_cap_lines: 100
+soft_target_lines: [30, 60]
+required_frontmatter:
+  schema_id: { type: string, equals: convention }
+  schema_version: { type: integer }
+  scope: { type: string, pattern: "^(project|folder:.+|module:.+)$" }
+  date: { type: date }
+  status: { type: enum, values: [active, superseded, retired] }
+required_sections:
+  - "## The convention"
+  - "## Rationale"
+  - "## Example"
+  - "## Counter-example"
+section_order: strict
+citation_rule: required-in-example-and-counter-example
+---
+
+# Schema: convention (codebase pattern)
+
+## Purpose
+
+A convention records a "how this codebase does X" pattern. The page answers "what's the rule? show me what right looks like, and what wrong looks like." Conventions are short by nature; if you need more than a paragraph to state the rule, it's probably an ADR or an architecture doc.
+
+## When to write one
+
+- A pattern emerges across multiple files during prototype iteration or production build (e.g. how route handlers are named, where shared types live, how errors are formatted)
+- A code reviewer flags "this doesn't match how we usually do X" — write the convention so the next contributor knows
+- A gotcha cluster signals a missing convention — the convention prevents future occurrences
+
+Do NOT write a convention for: language-level idioms (use a linter or formatter instead), things that are obvious from a reasonable read of the codebase, one-off patterns that exist in a single file.
+
+## File location and naming
+
+- Path: `aiwiki/conventions/{slug}.md`
+- Slug: kebab-case, ≤6 words, naming the pattern (not the rationale)
+
+Examples: `route-handler-naming.md`, `error-shape.md`, `shared-types-location.md`.
+
+## Required frontmatter
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_id` | string | Must equal `convention` |
+| `schema_version` | integer | — |
+| `scope` | string | `project` / `folder:<path>` / `module:<name>` — what this convention applies to |
+| `date` | ISO date | When the convention was codified |
+| `status` | enum | `active` / `superseded` (newer convention takes priority — link it) / `retired` |
+
+## Required sections
+
+| Section | Purpose | Format |
+|---|---|---|
+| `## The convention` | One paragraph in imperative mood — the rule itself | No fluff, no rationale |
+| `## Rationale` | Why this convention exists | Brief; link to ADR or gotcha if one motivates it |
+| `## Example` | Code that follows the convention | Cite the example code with `file:line@<sha7>` |
+| `## Counter-example` | Code that violates the convention (or what it would look like) | Cite if real, or write a synthetic counter-example |
+
+## Line caps
+
+- Hard cap: 100 lines (LINT fails above)
+- Soft target: 30-60 lines
+
+A convention that needs more than 100 lines is probably an architecture doc or a tutorial — write it as one of those instead.
+
+## Citation rules
+
+- `## Example` and `## Counter-example` MUST cite real code (or be marked synthetic explicitly)
+- Code references use `file:line@<sha7>` or `symbol` form
+- LINT auto-fills missing `@<sha7>` on first save
+
+## Skeleton
+
+```markdown
+---
+schema_id: convention
+schema_version: 1
+scope: folder:src/routes
+date: 2026-05-10
+status: active
+---
+
+## The convention
+
+Route handlers live in `src/routes/{resource}.ts` and export a `{resource}Router` constant. Each handler function is exported separately for testing; the router is the wiring layer that mounts them.
+
+## Rationale
+
+Separates handler logic (testable in isolation) from routing (testable as integration). See [aiwiki/decisions/0017-handler-router-split.md](aiwiki/decisions/0017-handler-router-split.md).
+
+## Example
+
+[src/routes/users.ts:1-24@e5f6789](src/routes/users.ts) — `usersRouter` mounts three handlers (`listUsers`, `getUser`, `createUser`) that are individually exported.
+
+## Counter-example
+
+<!-- synthetic example; replace with real counter-example before publishing -->
+
+```ts
+// DO NOT do this — handler logic and routing collapsed into a single anonymous function
+app.get('/users', async (req, res) => {
+  const users = await db.users.findAll();
+  res.json(users);
+});
+```
+
+The closure can't be unit-tested without spinning up the router; the route registration and the handler are entangled.
+```

package/templates/aiwiki/schemas/decision.md

@@ -0,0 +1,144 @@
+---
+schema_id: decision
+schema_version: 1
+applies_to: aiwiki/decisions/**/*.md
+filename_pattern: "{nnnn}-{slug}.md"
+hard_cap_lines: 400
+soft_target_lines: [100, 200]
+required_frontmatter:
+  schema_id: { type: string, equals: decision }
+  schema_version: { type: integer }
+  status: { type: enum, values: [proposed, accepted, superseded, deprecated] }
+  date: { type: date }
+  supersedes: { type: string, optional: true }
+  superseded_by: { type: string, optional: true }
+required_sections:
+  - "## Context"
+  - "## Decision"
+  - "## Consequences"
+  - "## Review"
+optional_sections:
+  - "## Alternatives"
+section_order: strict
+citation_rule: required-where-claims-about-code
+---
+
+# Schema: decision (ADR)
+
+## Purpose
+
+An ADR records a decision that is hard to reverse — architectural choice, public-surface naming, security/data tradeoff, schema design, cross-slice contract. The page answers "why was this chosen?" so future sessions don't relitigate it.
+
+## When to write one
+
+Write an ADR for any decision that's hard to reverse. Specifically:
+
+- Architectural choice (system shape, data flow, technology selection)
+- Public-surface naming (APIs, schemas, file paths users will import)
+- Security or data-handling tradeoff
+- Schema design (DB, API, file format) — anything other code will depend on
+- Cross-module contract — what one module exposes that other modules depend on
+- Any other irreversible design choice that survives prototype iteration into production
+
+Do NOT write an ADR for: variable naming, inline-vs-extract refactors, choosing between known-good libraries with no real tradeoff. Agent judgment is sufficient there.
+
+## File location and naming
+
+- Path: `aiwiki/decisions/{nnnn}-{slug}.md`
+- Numbering: zero-padded sequential, project-wide (e.g. `0042-token-storage.md`)
+- Slug: kebab-case, ≤6 words, descriptive
+
+## Required frontmatter
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_id` | string | Must equal `decision` |
+| `schema_version` | integer | Bumped only when schema itself changes |
+| `status` | enum | `proposed` / `accepted` / `superseded` / `deprecated` |
+| `date` | ISO date | When the decision was accepted (not when drafted) |
+| `supersedes` | string (optional) | Path to ADR this replaces |
+| `superseded_by` | string (optional) | Set when this ADR is itself replaced |
+
+## Required sections
+
+| Section | Purpose | Citation requirement |
+|---|---|---|
+| `## Context` | What's the situation that demands a decision | Cite code if context is grounded in specific code |
+| `## Decision` | What we chose (one paragraph, imperative mood) | Cite the prototype file or convention this comes from |
+| `## Alternatives` (optional) | What we rejected and why | Omit if the alternatives are obvious |
+| `## Consequences` | What changes downstream | Cite affected files where known |
+| `## Review` | `review:` block — reviewers, raised objections, how each was resolved, final verdict | — |
+
+The `## Review` block is required for `accepted` status. Format:
+
+```yaml
+review:
+  reviewers: [critic, codex]
+  claims: |
+    <what the decision claims to be true/best>
+  objections:
+    - reviewer: critic
+      objection: "..."
+      resolution: "..."
+  verdict: approved | escalate | reject
+  reviewed_at: 2026-05-10T11:42:00Z
+```
+
+## Line caps
+
+- Hard cap: 400 lines (LINT fails above)
+- Soft target: 100-200 lines
+
+## Citation rules
+
+- Code references use `file:line@<sha7>` (e.g. `src/auth.ts:42@a3f2bc1`) or `symbol` form (e.g. `src/auth.ts#login`)
+- LINT auto-fills missing `@<sha7>` on first save
+- Stale citations (hash mismatch) fail LINT — resolve by updating the citation, removing the claim, or annotating `// ack-stale: <reason>`
+
+## Skeleton
+
+```markdown
+---
+schema_id: decision
+schema_version: 1
+status: accepted
+date: 2026-05-10
+---
+
+## Context
+
+The cache layer needs durable storage. Read-heavy workload (~95% reads); single writer pattern; ≤1M entries projected.
+
+## Decision
+
+Use SQLite for the cache layer.
+
+## Alternatives
+
+- **Postgres**: rejected — overkill for single-writer cache; operational burden of a separate service.
+- **In-memory only**: rejected — process restart loses cache; eviction strategy adds complexity not warranted at projected size.
+
+## Consequences
+
+- One additional dependency (`better-sqlite3`)
+- WAL mode enabled for concurrent reader safety
+- Migration path documented at [src/cache/migrations/README.md](src/cache/migrations/README.md)
+
+## Review
+
+```yaml
+review:
+  reviewers: [critic, codex]
+  claims: |
+    SQLite is sufficient for the cache layer at projected scale and read pattern.
+  objections:
+    - reviewer: critic
+      objection: "Concurrent write throughput at scale"
+      resolution: "Cache is read-heavy; single-writer pattern documented; WAL mode handles reader concurrency"
+    - reviewer: codex
+      objection: "No atomic multi-row updates"
+      resolution: "Acknowledged; not needed for cache semantics (per-key invalidation only)"
+  verdict: approved
+  reviewed_at: 2026-05-10T11:42:00Z
+```
+```