@jamie-tam/forge 6.0.0

package/templates/aiwiki/schemas/gotcha.md

@@ -0,0 +1,118 @@
+---
+schema_id: gotcha
+schema_version: 1
+applies_to: aiwiki/gotchas/**/*.md
+filename_pattern: "{YYYY-MM-DD}-{slug}.md"
+hard_cap_lines: 150
+soft_target_lines: [50, 100]
+required_frontmatter:
+  schema_id: { type: string, equals: gotcha }
+  schema_version: { type: integer }
+  severity: { type: enum, values: [low, medium, high, critical] }
+  date: { type: date }
+  occurrences: { type: integer, default: 1 }
+  status: { type: enum, values: [active, watch, promotion-pending, promoted-to-rule, rejected, retired] }
+  proposed_rule: { type: object, optional: true }
+required_sections:
+  - "## What broke"
+  - "## Reproducer"
+  - "## Root cause"
+  - "## Fix"
+  - "## Prevention"
+section_order: strict
+citation_rule: required
+---
+
+# Schema: gotcha (recurring failure)
+
+## Purpose
+
+A gotcha records a failure pattern that has occurred and might recur. The page answers "have we hit this before? what's the fix? how do we avoid it next time?" The point is fast recall during debugging or code review, not a debugging narrative.
+
+## When to write one
+
+- A debugging session resolves an unexpected failure
+- The same root cause has caused trouble before (search `aiwiki/gotchas/` first; bump `occurrences` if it matches)
+- A library/framework misuse pattern is identified that's not obvious from the docs
+
+Do NOT write a gotcha for: bugs in your own code that weren't framework- or pattern-related, one-off typos, problems already documented in `aiwiki/conventions/` (write the convention instead).
+
+## File location and naming
+
+- Path: `aiwiki/gotchas/{YYYY-MM-DD}-{slug}.md`
+- Date: ISO format (`YYYY-MM-DD`)
+- Slug: kebab-case, ≤8 words, describing the pattern (not the symptom)
+
+Example: `2026-05-10-stub-logger-silently-drops-events.md`
+
+## Required frontmatter
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_id` | string | Must equal `gotcha` |
+| `schema_version` | integer | — |
+| `severity` | enum | `low` / `medium` / `high` / `critical` (impact + likelihood) |
+| `date` | ISO date | First occurrence |
+| `occurrences` | integer | Bumped each time AI hits this. N=2 flips status to `watch`. N=3 flips status to `promotion-pending`, triggers `proposed_rule:` auto-draft, and surfaces a session-start prompt to promote the gotcha into a project rule. |
+| `status` | enum | Auto-promotion path: `active` (N=1) → `watch` (N=2) → `promotion-pending` (N=3, draft attached). Terminal states: `promoted-to-rule` (rule shipped), `rejected` (user declined promotion at session-start), `retired` (no longer applies — explain in body). See `support-gotcha` SKILL.md for state-transition rules. |
+| `proposed_rule` | object (optional) | Auto-drafted at N=3 alongside `status: promotion-pending`; `{ rule_path: <target>, draft: <text>, drafted_at: <date> }` |
+
+## Required sections
+
+| Section | Purpose | Format |
+|---|---|---|
+| `## What broke` | One sentence — what failed and where | Cite the failure point |
+| `## Reproducer` | Minimal steps or code link | Cite if linking to existing test |
+| `## Root cause` | What was actually wrong | Cite the responsible code with `file:line@<sha7>` |
+| `## Fix` | The resolution | Cite the fix code |
+| `## Prevention` | Rule, check, or pattern that prevents recurrence | Cite a convention or rule if one exists |
+
+## Line caps
+
+- Hard cap: 150 lines (LINT fails above)
+- Soft target: 50-100 lines
+
+A gotcha that needs more than 150 lines is probably two gotchas, or it's narrative debug logs that don't belong here.
+
+## Citation rules
+
+- Every section has at least one citation (this is a stricter rule than ADRs)
+- Code references use `file:line@<sha7>` or `symbol` form
+- LINT auto-fills missing `@<sha7>` on first save
+- If the cited code has been removed, `status: retired` and explain in body
+
+## Skeleton
+
+```markdown
+---
+schema_id: gotcha
+schema_version: 1
+severity: high
+date: 2026-04-28
+occurrences: 1
+status: active
+---
+
+## What broke
+
+Logger calls returned successfully but no events appeared in the log destination during integration tests. ([src/lib/logger.ts:14@a3f2bc1](src/lib/logger.ts:14))
+
+## Reproducer
+
+1. Initialize logger with default config
+2. Call `logger.info("event")`
+3. Inspect the configured destination — no events present
+
+## Root cause
+
+`createLogger()` returned a stub when no transport was configured ([src/lib/logger.ts:14@a3f2bc1](src/lib/logger.ts:14)). The stub silently dropped all events instead of failing or warning.
+
+## Fix
+
+Throw on missing transport configuration ([src/lib/logger.ts:14@b1c2d3e](src/lib/logger.ts:14)) — fail loud at boot rather than silently at runtime.
+
+## Prevention
+
+- Convention: every framework boundary that can no-op MUST throw or warn instead. See [aiwiki/conventions/no-silent-stubs.md](aiwiki/conventions/no-silent-stubs.md).
+- Test pattern: integration tests assert their log assertions actually fire (use a recording transport, not a fake stub).
+```

package/templates/aiwiki/schemas/oracle.md

@@ -0,0 +1,105 @@
+---
+schema_id: oracle
+schema_version: 1
+applies_to: aiwiki/oracles/**/*.md
+filename_pattern: "{slug}.md"
+hard_cap_lines: 100
+soft_target_lines: [20, 60]
+required_frontmatter:
+  schema_id: { type: string, equals: oracle }
+  schema_version: { type: integer }
+  slug: { type: string }
+  prototype_path: { type: string }
+  captured_at: { type: date }
+  oracle_type: { type: enum, values: [route, render, interaction, snapshot, golden-trace] }
+required_sections:
+  - "## Setup"
+  - "## Trigger"
+  - "## Assertions"
+section_order: strict
+citation_rule: required
+---
+
+# Schema: oracle (prototype behavior snapshot)
+
+## Purpose
+
+An oracle captures observable behavior from the locked prototype so production code in Phase 6 has a concrete acceptance target. Tests in production are written *against* the oracle — if the production implementation doesn't reproduce the oracle's setup → trigger → assertions, it's not done.
+
+The page answers "what specifically did the prototype do that production code must also do?"
+
+## When to write one
+
+- During harden (Phase 5), per slice or subsystem
+- For every page/endpoint the prototype exposes (route oracle)
+- For every demoed click-through (interaction oracle)
+- For data shapes the prototype's frontend renders (snapshot oracle)
+
+Do NOT write an oracle for: pure styling that's already captured in design tokens, throwaway prototype scaffolding the user never touched, error states that aren't part of the click-through demo.
+
+## File location and naming
+
+- Path: `aiwiki/oracles/{slug}.md`
+- Slug: kebab-case, ≤8 words, identifies the oracle (e.g. `auth-login-success`, `dashboard-renders-empty-state`)
+
+Example: `aiwiki/oracles/checkout-applies-discount-code.md`
+
+## Required frontmatter
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_id` | string | Must equal `oracle` |
+| `schema_version` | integer | — |
+| `slug` | string | Matches the filename slug |
+| `prototype_path` | string | Path to the prototype file or directory the oracle was captured from |
+| `captured_at` | ISO date | When the oracle was recorded |
+| `oracle_type` | enum | `route` / `render` / `interaction` / `snapshot` / `golden-trace` |
+
+## Required sections
+
+| Section | Purpose | Citation requirement |
+|---|---|---|
+| `## Setup` | What state the system is in before the trigger fires | Cite the prototype seed/fixture, store init, or starting URL |
+| `## Trigger` | The input or action that exercises the behavior | Cite the prototype handler / event |
+| `## Assertions` | The observable outputs that must hold (DOM nodes, JSON body, HTTP status, transition sequence) | Cite the prototype's observed output |
+
+## Line caps
+
+- Hard cap: 100 lines (LINT fails above)
+- Soft target: 20-60 lines
+
+An oracle that needs more than 100 lines is probably two oracles, or is mixing setup details that belong in a fixture.
+
+## Citation rules
+
+- Every section cites the prototype source (`file:line@<sha7>` or `symbol` form)
+- LINT auto-fills missing `@<sha7>` on first save
+- Stale citations (prototype changed after oracle capture) fail LINT — resolve by re-capturing the oracle or annotating `// ack-stale: <reason>` if the production target intentionally deviates
+
+## Skeleton
+
+```markdown
+---
+schema_id: oracle
+schema_version: 1
+slug: auth-login-success
+prototype_path: pocs/myapp-prototype/src/auth/Login.tsx
+captured_at: 2026-05-10
+oracle_type: interaction
+---
+
+## Setup
+
+User is anonymous; auth store empty ([pocs/myapp-prototype/src/auth/store.ts:8@a3f2bc1](pocs/myapp-prototype/src/auth/store.ts:8)).
+
+## Trigger
+
+POST `/api/login` with body `{ email, password }` ([pocs/myapp-prototype/src/auth/Login.tsx:42@a3f2bc1](pocs/myapp-prototype/src/auth/Login.tsx:42)).
+
+## Assertions
+
+- HTTP 200 with body `{ token: <jwt>, user: { id, email } }`
+- Auth store transitions `anonymous → authenticated` ([pocs/myapp-prototype/src/auth/store.ts:24@a3f2bc1](pocs/myapp-prototype/src/auth/store.ts:24))
+- DOM redirects to `/dashboard` within 200ms
+- Subsequent `GET /api/me` returns the same user payload
+```

package/templates/aiwiki/schemas/session.md

@@ -0,0 +1,125 @@
+---
+schema_id: session
+schema_version: 1
+applies_to: aiwiki/sessions/**/*.md
+filename_pattern: "{date}-{slug}.md"
+hard_cap_lines: 200
+soft_target_lines: [40, 100]
+required_frontmatter:
+  schema_id: { type: string, equals: session }
+  schema_version: { type: integer }
+  status: { type: enum, values: [active, done, abandoned] }
+  date_start: { type: date }
+  date_end: { type: date, optional: true }
+  focus: { type: string }
+  last_commit: { type: string, optional: true }
+required_sections:
+  - "## Files touched"
+  - "## Decisions made"
+  - "## Gotchas surfaced"
+  - "## Open questions"
+  - "## Next steps"
+section_order: strict
+citation_rule: required-in-files-touched
+maintained_by: hooks-and-dream
+---
+
+# Schema: session (per-session handoff)
+
+## Purpose
+
+A session file is an **index of links** for one work session — what files were touched, what decisions landed, what gotchas surfaced, what's still open, what comes next. The page answers "what happened in session X?" for a future session that needs to resume or audit.
+
+**Index of links, not distilled summary.** No prose paragraphs. No narrative. No screenshots-from-the-moment. Future sessions follow the links to actual artifacts (ADRs, gotchas, raw notes); the session file is just the routing layer.
+
+## How it's maintained (NOT by hand)
+
+This page type is unusual: it's maintained by **hooks and dream**, not by humans typing.
+
+- `SessionStart` hook creates the file from this schema's skeleton (frontmatter + empty sections)
+- `PostToolUse` hooks append event lines to the appropriate sections (commit / gotcha / decision / raw)
+- `PreCompact` dream consolidates the event log into the schema sections (deduplicates, summarises bullet sequences, prunes noise)
+- `SessionEnd` (manual `/handoff` or detected) marks `status: done`
+
+Do NOT manually edit a session file unless correcting a hook misfire. Manual edits should be rare.
+
+## File location and naming
+
+- Path: `aiwiki/sessions/{date}-{slug}.md`
+- Date: ISO format (`YYYY-MM-DD`)
+- Slug: kebab-case, ≤6 words, naming the focus
+
+Examples: `2026-05-10-auth-refactor.md`, `2026-05-11-bugfix-session-race.md`.
+
+The companion file `aiwiki/sessions/INDEX.md` is a sortable table of all sessions; SessionStart appends a row.
+
+## Required frontmatter
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_id` | string | Must equal `session` |
+| `schema_version` | integer | — |
+| `status` | enum | `active` (in progress) / `done` (handed off) / `abandoned` (orphaned) |
+| `date_start` | ISO date | When SessionStart fired |
+| `date_end` | ISO date (optional) | When SessionEnd fired; null while active |
+| `focus` | string | What this session is about (e.g. `feature/auth-refactor`, `bugfix/session-race`) |
+| `last_commit` | string (optional) | SHA of the last commit during this session |
+
+## Required sections
+
+| Section | Purpose | Maintained by |
+|---|---|---|
+| `## Files touched` | Bullet list of files modified, with citations | PostToolUse hooks (append-only) |
+| `## Decisions made` | Links to ADRs in `aiwiki/decisions/` written this session | PostToolUse hook on `aiwiki/decisions/` write |
+| `## Gotchas surfaced` | Links to gotchas captured this session | PostToolUse hook on `aiwiki/gotchas/` write |
+| `## Open questions` | Links to raw context in `aiwiki/raw/` for unresolved items | PostToolUse hook on `aiwiki/raw/` write |
+| `## Next steps` | What the next session should do | Dream at PreCompact / SessionEnd |
+
+## Line caps
+
+- Hard cap: 200 lines (LINT fails above; if hit, dream is overdue or session is unusually long)
+- Soft target: 40-100 lines
+
+A session file that grows past 100 lines without dream consolidation usually means PreCompact hasn't fired (short session) — that's fine; SessionEnd dream will compact it. If it grows past 200 with no compact, run `/dream` manually.
+
+## Citation rules
+
+- `## Files touched` MUST cite each file with `file:line@<sha7>` (or `path` if file-level)
+- Other sections link to typed wiki pages (no `@<sha7>` needed for wiki-internal links)
+- LINT auto-fills missing code citations on first save
+
+## Skeleton
+
+```markdown
+---
+schema_id: session
+schema_version: 1
+status: active
+date_start: 2026-05-10
+focus: feature/auth-refactor
+last_commit: ~
+---
+
+## Files touched
+
+- [src/auth/handler.ts](src/auth/handler.ts)
+- [src/auth/token.ts](src/auth/token.ts)
+- [src/auth/middleware.ts:1-42@a3f2bc1](src/auth/middleware.ts)
+
+## Decisions made
+
+- [aiwiki/decisions/0042-token-storage.md](aiwiki/decisions/0042-token-storage.md)
+
+## Gotchas surfaced
+
+- [aiwiki/gotchas/2026-05-10-cookie-samesite-defaults.md](aiwiki/gotchas/2026-05-10-cookie-samesite-defaults.md)
+
+## Open questions
+
+- Token rotation policy ([aiwiki/raw/2026-05-10-rotation-question.md](aiwiki/raw/2026-05-10-rotation-question.md))
+
+## Next steps
+
+- Implement refresh token rotation per the open question
+- Update [aiwiki/architecture/auth-flow.md](aiwiki/architecture/auth-flow.md) once rotation lands
+```

package/templates/manifests/bugfix.yaml

@@ -0,0 +1,41 @@
+# Canonical manifest template for /bugfix command.
+# Source of truth for manifest schema — do not duplicate elsewhere.
+# Placeholders: {name}, {description}, {date}
+# Written to: .forge/work/bugfix/{name}/manifest.yaml
+#
+# v6 adds phase_plan: the planned status of each workflow step. The preflight
+# step MUST replace `active` defaults below with the actual plan agreed with
+# the user. See templates/manifests/v6/SCHEMA.md §3.
+
+schema_version: "6"
+name: {name}
+type: bugfix
+description: "{description}"
+status: in-progress  # in-progress | paused | completed | escalated | abandoned
+created: "{date}"
+command: bugfix
+escalated_from: null
+successor_path: null
+
+# Plan-status per workflow milestone. Bugfix workflow is compressed compared
+# to /feature — no concept/wireframe/prototype/codify by default. Allowed
+# values: active | active-light | active-commit-only | skipped | as-discovered
+# | complete-inline.
+phase_plan:
+  debug-root-cause: active
+  production-build: active
+  code-review: active
+  deliver: active
+  gotchas: as-discovered
+
+# Gate state per phase. slice_graph is added at production-build if the fix
+# is non-trivial; small fixes ship without one.
+phases:
+  debug:
+    root-cause: { status: pending, gate-passed: false }
+  quality:
+    code-review: { status: pending, gate-passed: false }
+  deliver:
+    pr-created: false
+  support:
+    gotchas-recorded: false

package/templates/manifests/feature.yaml

@@ -0,0 +1,69 @@
+# Canonical manifest template for /feature command.
+# Source of truth for manifest schema — do not duplicate elsewhere.
+# Placeholders: {name}, {description}, {date}
+# Written to: .forge/work/feature/{name}/manifest.yaml
+#
+# v6 adds phase_plan: the planned status of each workflow step. The preflight
+# step (/feature Step 1) MUST replace `active` defaults below with the actual
+# plan agreed with the user (skipped / active-light / active-commit-only /
+# as-discovered / complete-inline). See templates/manifests/v6/SCHEMA.md §3.
+#
+# *** PREFLIGHT IS NOT OPTIONAL ***
+# Most features skip 1-2 phases (e.g. a UI tweak on an existing prototype skips
+# concept + wireframe + prototype). Shipping a manifest with all phases `active`
+# trains downstream gates to lie about what actually ran. If you skip preflight,
+# go back and run it before any phase work starts.
+
+schema_version: "6"
+name: {name}
+type: feature
+description: "{description}"
+status: in-progress  # in-progress | paused | completed | escalated | abandoned
+created: "{date}"
+command: feature
+complexity: standard  # trivial | standard | major
+escalated_from: null
+successor_path: null
+
+# Plan-status per workflow milestone. Set during preflight; stable through
+# execution. Allowed values: active | active-light | active-commit-only |
+# skipped | as-discovered | complete-inline.
+phase_plan:
+  discover-codebase: active
+  concept: active
+  wireframe: active
+  plan-design-system: as-discovered  # frontend features set to `active`; backend/CLI leave `as-discovered` or `skipped`
+  prototype: active
+  iterate: active
+  codify: active
+  worktree: active
+  production-build: active
+  test-plan: active
+  uiux-review: active
+  code-review-final: active
+  deliver: active
+  onboarding: active
+  gotchas: as-discovered
+
+# Gate state per phase. Skills update these as they run; gate-passed: true
+# requires a matching Skill tool invocation (gate-enforcer.sh enforces).
+# slice_graph is added at codify phase, when work is decomposed into slices.
+phases:
+  discover:
+    codebase-analysis: { status: pending, gate-passed: false }
+  plan:
+    brainstorm: { status: pending, gate-passed: false }
+    design-system: { status: pending, gate-passed: false }
+    architecture: { status: pending, gate-passed: false }
+    task-decompose: { status: pending, gate-passed: false }
+  quality:
+    code-review-final: { status: pending, gate-passed: false }
+    test-plan: { status: pending, gate-passed: false }
+    test-execution: { status: pending, gate-passed: false }
+    uiux-review: { status: pending, gate-passed: false }
+  deliver:
+    pr-created: false
+    deployed: false
+    onboarding: false
+  support:
+    gotchas-recorded: false

package/templates/manifests/greenfield.yaml

@@ -0,0 +1,61 @@
+# Canonical manifest template for /greenfield command.
+# Source of truth for manifest schema — do not duplicate elsewhere.
+# Placeholders: {name}, {description}, {date}
+# Written to: .forge/work/greenfield/{name}/manifest.yaml
+#
+# v6 adds phase_plan: the planned status of each workflow step. The preflight
+# step MUST replace `active` defaults below with the actual plan agreed with
+# the user (greenfield commonly skips no phases — the whole pipeline runs).
+# See templates/manifests/v6/SCHEMA.md §3.
+
+schema_version: "6"
+name: {name}
+type: greenfield
+description: "{description}"
+status: in-progress  # in-progress | paused | completed | escalated | abandoned
+created: "{date}"
+command: greenfield
+complexity: standard  # trivial | standard | major
+escalated_from: null
+successor_path: null
+
+# Greenfield runs the full prototype-driven pipeline by default. Skipping
+# phases here is rare — a greenfield project without a concept or wireframe
+# usually means it should have been scoped as /feature against an existing
+# codebase instead.
+phase_plan:
+  discover-requirements: active
+  concept: active
+  wireframe: active
+  plan-design-system: active  # greenfield is frontend-led by default; preflight may downgrade for CLI-only / backend-only projects
+  prototype: active
+  iterate: active
+  codify: active
+  scaffold: active
+  production-build: active
+  test-plan: active
+  uiux-review: active
+  code-review-final: active
+  deliver: active
+  onboarding: active
+  gotchas: as-discovered
+
+# Gate state per phase. slice_graph is added at codify.
+phases:
+  discover:
+    requirements: { status: pending, gate-passed: false }
+  plan:
+    brainstorm: { status: pending, gate-passed: false }
+    design-system: { status: pending, gate-passed: false }
+    architecture: { status: pending, gate-passed: false }
+    task-decompose: { status: pending, gate-passed: false }
+  quality:
+    code-review-final: { status: pending, gate-passed: false }
+    test-plan: { status: pending, gate-passed: false }
+    test-execution: { status: pending, gate-passed: false }
+    uiux-review: { status: pending, gate-passed: false }
+  deliver:
+    deployed: false
+    onboarding: false
+  support:
+    gotchas-recorded: false

package/templates/manifests/hotfix.yaml

@@ -0,0 +1,45 @@
+# Canonical manifest template for /hotfix command.
+# Source of truth for manifest schema — do not duplicate elsewhere.
+# Placeholders: {name}, {description}, {date}
+# Written to: .forge/work/hotfix/{name}/manifest.yaml
+#
+# Hotfix uses a compressed phase set — see quality-gates.md "Hotfix Gate
+# Exemptions" for rationale. Follow-up work is tracked in an associated
+# gotcha file with the `hotfix-workaround` tag.
+
+schema_version: "6"
+name: {name}
+type: hotfix
+description: "{description}"
+status: in-progress  # in-progress | paused | completed | escalated | abandoned
+created: "{date}"
+command: hotfix
+escalated_from: null
+successor_path: null  # filled when follow-up /bugfix or /feature is created
+
+# Hotfix workflow is intentionally compressed — full /bugfix scrutiny happens
+# in the follow-up ticket. active-light values are common here. Allowed
+# values: active | active-light | active-commit-only | skipped | as-discovered
+# | complete-inline.
+phase_plan:
+  debug-root-cause: active
+  production-build: active
+  smoke-tests: active
+  code-review-critical: active
+  deliver: active
+  gotchas: as-discovered
+  followup-ticket: as-discovered
+
+# Gate state. No slice_graph — hotfixes are by definition too urgent to plan
+# a decomposition.
+phases:
+  debug:
+    root-cause: { status: pending, gate-passed: false }
+  quality:
+    smoke-tests: { status: pending, gate-passed: false }
+    code-review-critical: { status: pending, gate-passed: false }
+  deliver:
+    deployed: false
+  support:
+    gotchas-recorded: false
+    followup-ticket: null  # e.g. work/bugfix/payment-null-check-proper-fix

package/templates/manifests/refactor.yaml

@@ -0,0 +1,44 @@
+# Canonical manifest template for /refactor command.
+# Source of truth for manifest schema — do not duplicate elsewhere.
+# Placeholders: {name}, {description}, {date}
+# Written to: .forge/work/refactor/{name}/manifest.yaml
+
+schema_version: "6"
+name: {name}
+type: refactor
+description: "{description}"
+status: in-progress  # in-progress | paused | completed | escalated | abandoned
+created: "{date}"
+command: refactor
+coverage-baseline: null  # recorded in Step 0
+escalated_from: null
+successor_path: null
+
+# Refactors skip the prototype-driven phases by default — they operate on an
+# existing codified system. The plan covers discover/plan/build/quality steps.
+# Allowed values: active | active-light | active-commit-only | skipped |
+# as-discovered | complete-inline.
+phase_plan:
+  discover-codebase: active
+  brainstorm: active
+  task-decompose: active
+  production-build: active
+  test-execution: active
+  assessment: active
+  deliver: active
+  gotchas: as-discovered
+
+# Gate state. slice_graph is added at task-decompose when work is sliced.
+phases:
+  discover:
+    codebase-analysis: { status: pending, gate-passed: false }
+  plan:
+    brainstorm: { status: pending, gate-passed: false }
+    task-decompose: { status: pending, gate-passed: false }
+  quality:
+    test-execution: { status: pending, gate-passed: false }
+    assessment: { status: pending, gate-passed: false }
+  deliver:
+    pr-created: false
+  support:
+    gotchas-recorded: false