# 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.

> Installed only when `project.aiwiki_enabled: true` in `.claude/CLAUDE.md` (set during `/setup` Step 4). If a project chose to skip the knowledge layer, this file is not present and downstream skills surface an upgrade hint instead of writing typed pages. Re-run `/setup` and pick Y to enable.

## 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

AI writes typed pages directly when the content meets the durability test for that page type. The user can edit or delete any page after the fact. `wiki-lint` (PostToolUse hook) validates schema on every save.

| Page type | Trigger | Skill that typically writes it | Adversarial review |
|---|---|---|---|
| ADR (`aiwiki/decisions/`) | Hard-to-reverse choice: architectural, public-surface naming (APIs / schemas / file paths users import), security or data-handling tradeoff, schema design, contracts other code depends on | `harden` (Phase 5, with inline adversarial review in each ADR's `review:` block per `aiwiki/schemas/decision.md`), `plan-brainstorm`, manual | Inline in the ADR `review:` block. When Codex is configured (`protocols/codex.md`), `harden` may dispatch Codex in verify mode; otherwise Claude performs the pass directly. |
| Gotcha (`aiwiki/gotchas/`) | Reproducible failure mode with a concrete fix | `support-gotcha`, `support-debug` (after closing a non-trivial bug) | None — gotchas are facts, not opinions. The `occurrences: 3+` auto-promotion path adds a `proposed_rule:` block and the next session-start hard-interrupts for user approval before the rule ships. |
| Convention (`aiwiki/conventions/`) | Pattern established across 2+ sites in this codebase | `iterate-prototype` (during Phase 4), `harden` (codify-time), manual | None — wiki-lint enforces schema; user reviews on read. |
| Architecture (`aiwiki/architecture/{topic}.md`) | System-shape change: new subsystem, new boundary, new contract between components. One file per topic — do NOT collapse multiple subsystems into a single mega-file. | `harden` (Phase 5), manual | None directly, but `harden` Step 2 runs adversarial review on any ADRs that drive the architecture write. |
| Oracle (`aiwiki/oracles/{slug}.md`) | Prototype behavior snapshot (setup → trigger → assertions) that Phase 6 production code must reproduce | `harden` Step 2.5 | None — oracles are observation of the prototype, not opinion. Tests in Phase 6 are written against the oracle. |
| Session (`aiwiki/sessions/{date}-{session_id_short}.md`) | First in-session writer creates the file lazily | `pre-compact.sh` (Checkpoints), `/wrap` (index sections), `harden` (codify-time session entry) | `/wrap` confirms content with user before setting `status: done`. |

**Raw (`aiwiki/raw/`) is user-gated.** Half-formed thoughts, research notes, deferred decisions, comparison sketches — these go to raw ONLY via `/note <text>`. The AI does not autonomously decide to write conversational content to raw; the user is the gate.

**`INDEX.md` files are dream-maintained.** Each folder's `INDEX.md` (and the top-level `aiwiki/INDEX.md`) is rewritten by `support-dream` whenever a dream touches that folder. Do not hand-edit between dream cycles — your changes will be overwritten on the next cycle. If an index looks stale, run `/dream` to refresh it.

When durability is uncertain (e.g. "is this a real gotcha or just a one-off?"), ask the user instead of speculating into a typed page. Speculation in `aiwiki/decisions/` poisons future retrieval more than the missing entry costs.

## 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/`.

**Dream triggers:**
- **Manual** — `/dream [scope]` slash command. User-driven cleanup.
- **PreCompact (~85% context)** — `hooks/scripts/pre-compact.sh` appends a `**Dream directive (unconsumed)**` block to the active session file's `## Checkpoints` section (`aiwiki/sessions/{date}-{session_id_short}.md`, created lazily on first fire). The post-compact agent reads the session file, finds the directive, and invokes `support-dream`. Skipped when `aiwiki/` has no recent (last 24h) activity.
- **Phase-close** — the phase-locking skills (`iterate-prototype` on prototype-lock, `harden` on codify-lock, `feature.md` Step 8.5 per-slice on slice gate-pass, `deliver-deploy` on deliver-lock) dispatch `support-dream` immediately after writing their `artifacts.{phase}.locked_at`.

When pending dreams exist:
- Run `forge wiki status` to see the queue
- Run `forge wiki ui` to open the local web review at 127.0.0.1:8765, OR
- Run `forge wiki review [dream_id]` to step through per-page diffs in the terminal
- Run `forge wiki accept [dream_id]` or `forge wiki reject [dream_id] --reason "..."` to resolve

**Phase-close dreams hard-block the next phase** (iterate→codify, codify→production-build, all-slices-pass→deliver close). Per-slice dreams do not block — they're reviewed in bulk before Phase 7. PreCompact dreams do not block compaction; the proposal is durable on disk and you review whenever convenient.

## Session handoff (`aiwiki/sessions/`)

Each Claude session can produce a handoff file at `aiwiki/sessions/{date}-{session_id_short}.md`. Two writers populate different parts:

| Section | Writer | Style |
|---|---|---|
| `## Checkpoints` | `hooks/scripts/pre-compact.sh`, `support-dream` skill | Append-only event log. PreCompact events with recovery directives. |
| `## Files touched` / `## Decisions made` / `## Gotchas surfaced` / `## Open questions` / `## Next steps` | `/wrap` command | Index of links. Curated by the agent, confirmed by the user. |

**Lazy creation.** The file is NOT created at SessionStart (that would produce empty noise for trivial 30-second sessions). The first writer in the session creates it.

**`/wrap` to finalize.** Run `/wrap` at the natural end of a working session to fill the index sections and set `status: done`. This is the single most useful thing for next-session continuity — the SessionStart hook surfaces the latest session's focus and any unconsumed checkpoints.

**Active dream directives.** If a `## Checkpoints` entry has a header `**Dream directive (unconsumed):**`, it's an action item for the current agent (typically: invoke `support-dream`). After acting, change the entry's header from `**Dream directive (unconsumed):**` to `**Dream directive (consumed at {ISO-timestamp}):**`. The `session-start.sh` hook counts active directives by matching `(unconsumed):` literally — flipping the header is what makes the count accurate.

## 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 ships 8 common rules in `.claude/rules/common/`. Seven auto-load every session; one (`testing.md`) is paths-conditional via frontmatter `paths:` and loads only when an editor touches test files or source code in `src/`.

| Rule | Loading | Purpose |
|---|---|---|
| `forge-system.md` | Always-on | This file. Forge directory layout, aiwiki layer, dream + session-handoff mechanics. |
| `security.md` | Always-on | Injection, secret handling, auth/data-handling — safety floor. |
| `guardrails.md` | Always-on | Destructive-action gates, force-push refusals, sandbox boundaries. |
| `verification.md` | Always-on | Don't claim "done" without proof; verify completion before reporting. |
| `skill-selection.md` | Always-on | Routing logic: which skill fits a request given phase/scope/manifest state. |
| `quality-gates.md` | Always-on | Gate-state vocabulary + the per-gate pass criteria summary. |
| `git-workflow.md` | Always-on | Conventional Commits, bisectable commits, branch naming, hook-respect. |
| `testing.md` | Paths-conditional | TDD discipline (RED-GREEN-REFACTOR), coverage targets, mocking strategy. Loads only when editing test files or `src/` code. |

**References load on demand**, not automatically. `.claude/references/common/coding-standards.md` and language-specific standards (`typescript/`, `python/`, `react/`) are read by the `harden` skill, the `prototype-codifier` agent, and `quality-code-review`'s craft pass — when those subagents/skills choose to consult them. During prototype iteration (Phases 1-4), references are unread by default.

**The original v6 design** floated a phase-conditional loading tier (testing/quality-gates/git-workflow load only from Phase 5 onward). That was rejected after second-opinion review: the safety-floor + paths-conditional model above is what actually ships. Prototype iteration speed comes from skill-level discipline (e.g. `iterate-prototype` doesn't dispatch full code-review chains) rather than from suppressing always-on rules.

## 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.