@jamie-tam/forge 6.1.0 → 6.2.0

package/README.md

@@ -28,7 +28,7 @@ The v6 schema (`templates/manifests/v6/SCHEMA.md`) adds `phase_plan:` at the top
 ## Key Features
 
 - **31 skills** spanning the prototype-driven pipeline plus production-grade quality gates
-- **13 commands** for discovery, setup, workflows, knowledge capture, evolution, and validation
+- **15 commands** for discovery, setup, workflows, knowledge capture, evolution, and validation
 - **17 specialized agents** with explicit phase-context (prototype-builder for Phase 3-4, builder for Phase 6, plus architects, reviewers, hunters, dreamers)
 - **8 common rules** auto-loaded every session (one — `testing.md` — is paths-conditional, loading only on test files and source code) + **8 common references** for skill authoring, agent coordination, and workflow protocol
 - **Work manifests** with `phase_plan` (preflight intent), `phases` (gate state), `slice_graph` (build decomposition), and `artifacts` (phase outputs + lock signals)
@@ -47,7 +47,7 @@ npx @jamie-tam/forge init
 This installs everything into your project's `.claude/` directory:
 - **Rules** — 8 common rules auto-loaded every session (one is paths-conditional) + language-specific rules layered per detected stack
 - **Skills** — 31 atomic skills covering the prototype-driven pipeline + production gates
-- **Commands** — 13 slash commands for discovery, setup, workflows, knowledge capture, evolution, and validation
+- **Commands** — 15 slash commands for discovery, setup, workflows, knowledge capture, evolution, and validation
 - **Agents** — 17 specialized subagents with MCP server access (context7, playwright)
 - **Hooks** — gate-enforcer, wiki-lint, telemetry, state preservation, session checkpoints
 - **CLAUDE.md** — project configuration template
@@ -157,33 +157,35 @@ Commands (workflows)          Skills (prefix-grouped)              Rules (auto-l
 /refactor                     build-scaffold                       common/quality-gates
 /hotfix                       build-tdd          [Phase 6]         common/git-workflow
 /note       (capture)         build-pr-workflow                    common/testing (paths-conditional)
-/parallel   (parallel)        quality-code-review
-/status                       quality-test-plan
-/resume                       quality-test-execution               References (load on demand)
-/forge-evolve                 quality-security-audit               ----------------------------
-/validate                     quality-uiux                         common/
-                              deliver-deploy     [Phase 7]           agent-coordination
-                              deliver-db-migration                   io-protocol
-Work Manifests (v6)           deliver-onboarding                     skill-authoring
--------------------           discover-requirements                  skill-compliance
-.forge/work/                  discover-codebase-analysis             phases (canonical vocab)
-  {type}/                     plan-brainstorm                        coding-standards
-    {name}/                   plan-architecture                      quality-gates
-      manifest.yaml           plan-design-system                     feature-tracking
-        schema_version: "6"   plan-task-decompose                  typescript/  python/  react/
-        phase_plan: {…}       support-system-guide                   [extensible]
-        phases: {…}           support-debug
-        slice_graph: {…}      support-gotcha                       Protocols (read on demand)
-        artifacts: {…}        support-wiki-lint                    --------------------------
-                              support-wiki-bootstrap               protocols/codex.md
-aiwiki/ (knowledge layer)     support-dream                        protocols/graphify.md
--------------------------     support-parallel
-  decisions/                  support-runtime-reachability         Hooks
-  gotchas/                    support-skill-validator              ------
-  conventions/                                                     gate-enforcer
-  architecture/                                                    wiki-lint
-  sessions/                                                        session-start / pre-compact
-  raw/                                                             telemetry
+/dream      (capture)         quality-code-review
+/wrap       (capture)         quality-test-plan
+/parallel   (parallel)        quality-test-execution               References (load on demand)
+/status                       quality-security-audit               ----------------------------
+/resume                       quality-uiux                         common/
+/forge-evolve                 deliver-deploy     [Phase 7]             agent-coordination
+/validate                     deliver-db-migration                     io-protocol
+                              deliver-onboarding                       skill-authoring
+Work Manifests (v6)           discover-requirements                    skill-compliance
+-------------------           discover-codebase-analysis               phases (canonical vocab)
+.forge/work/                  plan-brainstorm                          coding-standards
+  {type}/                     plan-architecture                        quality-gates
+    {name}/                   plan-design-system                       feature-tracking
+      manifest.yaml           plan-task-decompose                    typescript/  python/  react/
+        schema_version: "6"   support-system-guide                     [extensible]
+        phase_plan: {…}       support-debug
+        phases: {…}           support-gotcha                         Protocols (read on demand)
+        slice_graph: {…}      support-wiki-lint                      --------------------------
+        artifacts: {…}        support-wiki-bootstrap                   protocols/codex.md
+                              support-dream                            protocols/graphify.md
+aiwiki/ (knowledge layer)     support-parallel
+-------------------------     support-runtime-reachability           Hooks
+  decisions/                  support-skill-validator                ------
+  gotchas/                                                             gate-enforcer
+  conventions/                                                         wiki-lint
+  architecture/                                                        session-start / pre-compact
+  sessions/  (per-session)                                             telemetry
+  raw/  (free-form notes)
+  oracles/ (prototype contracts)
   proposed/  (dream queue)
   schemas/
   CLAUDE.md  (usage rules)
@@ -203,6 +205,8 @@ aiwiki/ (knowledge layer)     support-dream                        protocols/gra
 | `/refactor` | Analyze, plan approach, restructure with tests, PR | Code needs cleanup without new functionality |
 | `/hotfix` | Emergency compressed flow -- debug, minimal test, deploy | Production is down, need a fix now |
 | `/note` | Append an ad-hoc research note or brainstorm to `aiwiki/raw/{date}.md` | Phase 1-2 research, half-formed thoughts, anything that doesn't yet fit a typed page |
+| `/dream` | Manually trigger aiwiki consolidation (merge duplicates, promote raw → typed, prune stale) | After a refactor, branch merge, or whenever `aiwiki/` feels noisy. Auto-fires at phase-close + PreCompact too. |
+| `/wrap` | Capture & finalize the current Claude session — fills `aiwiki/sessions/{date}-{id}.md` with Files touched / Decisions / Gotchas / Open questions / Next steps | At the natural end of a working session, before a long break, or before switching focus mid-day. Next session-start hook reads it. |
 | `/parallel` | Dispatch parallel agents for a punch list of ad-hoc tasks; phase-aware sizing | Multiple independent small tasks to crunch in one pass |
 | `/status` | List in-flight `.forge/work` items and their current phase | Check what's open before starting new work |
 | `/resume` | Continue a paused work item from its current phase | Pick up a `.forge/work` item left mid-flow |

package/agents/dreamer.md

@@ -61,10 +61,14 @@ Apply operations in this order:
 3. **Prune stale** — for each entry whose cited code no longer exists OR whose decision is superseded:
    - Mark for deletion in the manifest's `operations` (`op: prune`)
    - Do NOT write a "tombstone" file; absence in proposed/ means delete on accept
-4. **Refresh session file (PreCompact only, conditional)** — for `aiwiki/sessions/{current}.md`:
-   - **Check first**: does `aiwiki/sessions/{current}.md` exist? Session-checkpoint hooks (SessionStart create + PostToolUse append) are currently **deferred** per `templates/aiwiki/schemas/session.md`. If the file does NOT exist, SKIP this step entirely — no failure, no fresh-write. Proceed with raw + typed page consolidation only.
-   - If it DOES exist: read it (the hook-maintained event log), consolidate the event log into the schema sections (Files touched, Decisions made, Gotchas surfaced, Open questions, Next steps), and write the refined version to `aiwiki/proposed/{dream_id}/sessions/{current}.md`.
-   - DO NOT recreate the file if missing — that would generate speculation (`templates/aiwiki/CLAUDE.md.template:76` forbids it). The skip-if-missing branch handles the deferred-hooks state cleanly.
+4. **Refine the active session file (PreCompact and phase-close triggers)** — locate `aiwiki/sessions/{date}-{session_id_short}.md`:
+   - **The file is expected to be present.** `hooks/scripts/pre-compact.sh` creates it lazily on first PreCompact fire; `/wrap`, `/dream`, and `harden` also create it lazily if absent. By the time you run, one of those has fired during this session — so the file exists.
+   - **If it is truly missing** (no in-session writer fired before you, no `aiwiki/sessions/{today}-*.md` matches), this is a non-fatal anomaly: log it in the dream manifest's `lint_warnings` as `session_file_missing: true` and proceed with raw + typed page consolidation only. Do NOT fabricate a session file — let the next writer (pre-compact, /wrap, harden) create it cleanly.
+   - **If it exists**: read it. The `## Checkpoints` section is append-only event log written by pre-compact and dream itself. Your refinement work targets:
+     - **Trim `## Checkpoints`**: if more than 10 entries, summarize older ones into a single "## Checkpoint summary {date-range}" entry. Preserve any `Status: unconsumed` entries as-is.
+     - **Pre-populate index sections** (`## Files touched`, `## Decisions made`, `## Gotchas surfaced`, `## Open questions`, `## Next steps`) from git diff + aiwiki writes during this session. Mark each line with a `<!-- dream-suggested -->` HTML comment so `/wrap` knows what dream proposed vs what the user wrote.
+     - **Do NOT set `status: done`** — that's `/wrap`'s responsibility. Leave `status: active`.
+   - Write the refined version to `aiwiki/proposed/{dream_id}/sessions/{date}-{session_id_short}.md`.
 
 ### Phase 4: Prune & index
 
@@ -93,7 +97,7 @@ Apply operations in this order:
 - ANY file in `aiwiki/` (input store untouched)
 - ANY file in `.forge/work/` (operational state, not knowledge)
 - Tombstone files for prunes (manifest's `operations` log records the prune; absence in proposed/ means delete on accept)
-- A fresh `aiwiki/sessions/{current}.md` if it doesn't exist — session-checkpoint hooks are currently deferred per `templates/aiwiki/schemas/session.md`; SKIP session-file refinement instead (no failure, no speculation-write)
+- A fresh `aiwiki/sessions/{date}-{session_id_short}.md` if it doesn't exist — let the next pre-compact / /wrap / harden writer create it cleanly. If it's truly missing when you run, log `session_file_missing: true` in the dream manifest's `lint_warnings` and skip session-file refinement (no failure, no speculation-write)
 - Any file outside `aiwiki/proposed/{dream_id}/`
 
 ## Provider Mode (for `anthropic-managed` only)
@@ -110,7 +114,7 @@ If dispatched with `provider: anthropic-managed`:
 
 | Mistake | Fix |
 |---|---|
-| Recreating `aiwiki/sessions/{current}.md` instead of refining the existing one | The session file MUST exist (hook created it). If absent, FAIL — don't paper over an upstream bug. |
+| Recreating `aiwiki/sessions/{date}-{session_id_short}.md` instead of refining the existing one | The session file is expected to exist (pre-compact / /wrap / harden creates it lazily). If absent when you run, log `session_file_missing: true` in the manifest and skip session refinement — don't fabricate a session file. The next writer will create it cleanly. |
 | Promoting a raw entry that doesn't satisfy the target schema | Validate against schema first; failures go into `lint_warnings`, not into `aiwiki/proposed/{type}/` |
 | Merging unrelated typed pages because they share a keyword | Merge requires shared root cause / topic, not surface-level term overlap |
 | Pruning an entry without checking if the citation still resolves | Re-check the cited file/symbol before marking prune; LINT staleness != prune trigger |

package/commands/discover.md

@@ -70,6 +70,8 @@ State commands
 
 Knowledge commands
   /note <text>        append a research note / brainstorm to aiwiki/raw/{date}.md
+  /dream [scope]      consolidate aiwiki — merge duplicates, promote raw → typed, prune stale
+  /wrap [focus]       capture & finalize current session into aiwiki/sessions/{date}-{id}.md
 
 System commands
   /setup              detect stack, fill project profile, scaffold .forge/ + aiwiki/

package/commands/dream.md

@@ -0,0 +1,71 @@
+---
+name: dream
+description: "Manually trigger aiwiki consolidation. Merges duplicate notes, promotes raw → typed pages, prunes stale entries. Output is written to aiwiki/proposed/{dream_id}/ for review — input store is never modified. Use after a major refactor, a long session, or whenever aiwiki/ feels noisy. Optional argument: scope (default = full aiwiki/; alternatives = aiwiki/raw/, aiwiki/gotchas/, etc.)."
+---
+
+# /dream — Consolidate aiwiki
+
+Manual trigger for `support-dream`. Produces a reviewable consolidation proposal in `aiwiki/proposed/{dream_id}/`; you accept or reject via the web view (`forge wiki ui`) or CLI (`forge wiki review {dream_id}`).
+
+This is the user-driven trigger. Dream also fires automatically:
+- **PreCompact** — `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). The post-compact agent reads the session file, finds the directive, and invokes `support-dream`.
+- **Phase-close** — `iterate-prototype`, `harden`, `build-pr-workflow`, and `deliver-deploy` dispatch `support-dream` after writing their respective `artifacts.{phase}.locked_at` lock signal.
+
+The manual `/dream` invocation is the escape hatch for between-trigger consolidation.
+
+## Steps
+
+1. **Parse scope** from the user's argument:
+   - No argument → scope is the full `aiwiki/` tree.
+   - One token (`raw`, `gotchas`, `decisions`, `conventions`, `architecture`, `sessions`) → scope is `aiwiki/{token}/`.
+   - Multiple tokens or explicit path → scope is the union of those paths.
+2. **Verify aiwiki exists.** If `aiwiki/` is missing, dispatch `support-wiki-bootstrap` first.
+3. **Check for pending dreams.** If `aiwiki/proposed/{dream_id}/` directories already exist with `review_status: pending` in their manifest, surface them to the user and ask whether to queue a new dream or review the pending ones first. Do not silently overwrite.
+4. **Invoke `support-dream` skill** with the parsed scope and `trigger: manual`. The skill dispatches the `dreamer` subagent and writes the proposed output.
+5. **Report to the user**: new `dream_id`, list of `changed_pages` / `new_pages` / `deleted_pages` counts, lint status, and the path to review:
+   ```
+   Dream complete: 2026-05-18-1742-manual
+     Proposals: aiwiki/proposed/2026-05-18-1742-manual/
+     Changed: 3   New: 1   Deleted: 0   Lint: passed
+     Review: `forge wiki review 2026-05-18-1742-manual` or open `forge wiki ui`
+   ```
+
+## Example
+
+User: `/dream`
+→ Full aiwiki consolidation, dispatched as `trigger: manual`.
+
+User: `/dream raw gotchas`
+→ Scope limited to `aiwiki/raw/` + `aiwiki/gotchas/`.
+
+User: `/dream after the auth refactor`
+→ Free-form description folded into `trigger_detail`; scope defaults to full aiwiki.
+
+## When to use
+
+- After a **major refactor** or **branch merge** brought in lots of new wiki entries.
+- When `aiwiki/raw/` has accumulated unclassified notes from `/note` invocations.
+- When you suspect **duplicate gotchas** across recent debugging sessions.
+- Before **handoff** to a new contributor — get the wiki into curated shape first.
+- When `forge wiki status` shows no pending dreams but the aiwiki feels noisy.
+
+## When NOT to use
+
+- A dream is already pending review (`forge wiki status` lists it). Review the existing one first; queueing a new dream against the same source state produces overlapping proposals.
+- `aiwiki/` has no recent activity — there's nothing to consolidate; the cycle would no-op.
+- You want to **edit a single page**. Edit it directly. Dream is for *merging / promoting / pruning across pages*, not per-page revision.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `aiwiki/` (scaffolded by `/setup`), `aiwiki/schemas/` |
+| **Produces** | `aiwiki/proposed/{dream_id}/` (mirror structure) + `.dream-manifest.json` |
+| **Dispatches** | `support-dream` skill → `dreamer` subagent |
+| **Review surface** | `forge wiki ui` (web view at 127.0.0.1:8765) or `forge wiki review/accept/reject` CLI |
+
+## Do NOT
+
+- Do NOT modify `aiwiki/` directly inside this flow — that is `support-dream`'s invariant.
+- Do NOT queue a new dream while one is pending review against the same source state.
+- Do NOT skip the lint pass — `support-dream` runs lint on the proposed output before marking the dream complete.

package/commands/feature.md

@@ -206,7 +206,12 @@ Execute the slice graph from Phase 5. Per slice:
 2. REQUIRED SUB-SKILL: Use **quality-code-review**
 3. Fix any Critical or Important findings
 4. Per-slice user-confirm
-5. Per-slice dream consolidates slice-scoped wiki updates
+5. **Per-slice dream (auto-fire on slice close).** After the slice's gates pass (`gate-passed: true` on the slice's `code-review` + `runtime-reach`), invoke the **support-dream** skill with:
+   - **scope:** `aiwiki/gotchas/`, `aiwiki/conventions/` (any subfolders the slice's builder + reviewer subagents wrote to; check git diff on `aiwiki/` since the slice started for a precise list)
+   - **trigger:** `phase-close`
+   - **trigger_detail:** `"Phase 6 per-slice — {slice_id}"`
+   Dream output goes to `aiwiki/proposed/{dream_id}/`. Surface the id + review path to the user. The next slice can start while the proposal is pending review (per-slice dreams do NOT block forward motion — only phase-close gates do).
+   **Skip when:** the slice's build wrote nothing to `aiwiki/` (pure code change with no new gotcha or convention). No-op dreams add noise.
 
 For `--size major` features: also escalate to `quality-security-audit` on slices that touch auth/payments/PII.
 
@@ -214,7 +219,7 @@ Optional: `/autopilot production` for Ralph-loop hands-off slice execution *(pla
 
 ### GATE: All Slices Complete
 
-All slices `gate-passed: true`. Update manifest: `artifacts.production-build.locked_at` (the slice terminal state + the production code ARE the production-build artifacts).
+All slices `gate-passed: true`. Update manifest: `artifacts.production-build.locked_at` (the slice terminal state + the production code ARE the production-build artifacts). Any pending per-slice dream proposals from Step 8.5 must be reviewed before Phase 7 (deliver) starts — Phase 7's retrospective dream depends on a consolidated wiki state.
 
 ## Step 9: Test Plan + Execution
 

package/commands/wrap.md

@@ -0,0 +1,130 @@
+---
+name: wrap
+description: "Capture and finalize the current Claude session. Writes ## Files touched / ## Decisions made / ## Gotchas surfaced / ## Open questions / ## Next steps into aiwiki/sessions/{date}-{session_id_short}.md, then sets status: done. Use at the natural end of a working session so the next session-start hook can surface a meaningful handoff. Optional argument: a one-line focus statement (otherwise inferred from the active manifest)."
+---
+
+# /wrap — Capture and finalize the current session
+
+Finalize this Claude session's handoff artifact. Writes the index sections (Files touched / Decisions / Gotchas / Open questions / Next steps) into `aiwiki/sessions/{date}-{session_id_short}.md` so the next session-start hook can surface a meaningful handoff.
+
+**Distinct from `/dream`:** `/wrap` captures *this session's* knowledge (what was worked on, what was decided). `/dream` consolidates *the whole aiwiki* (merges duplicates, promotes raw → typed). The two can be run sequentially at session end (`/wrap` first, then `/dream`) but they answer different questions.
+
+## Steps
+
+1. **Determine session file path.**
+   - Read `session_id` from the most recent SessionStart context (Claude Code provides this in the hook payload; if running standalone, ask the user or read from `aiwiki/sessions/*.md` mtime).
+   - Path: `aiwiki/sessions/{ISO-date}-{session_id_short7}.md` (the same path pre-compact would have used). If the file already exists (created by pre-compact), append to it. If not, create it lazily here.
+
+2. **Determine focus.**
+   - If `/wrap <focus statement>` was supplied, use that.
+   - Else: read the active work item from `.forge/work/*/*/manifest.yaml` where `status: in-progress`. Focus = `{type}/{name}` (e.g. `feature/wire-dream`).
+   - Else: ask the user "What was this session about?" — one-line answer.
+
+3. **Read the session file** (if it already has content from pre-compact).
+   - The `## Checkpoints` section stays as-is — that's event log, not user-facing summary.
+   - The index sections (`## Files touched`, etc.) are what you fill.
+
+4. **Capture `## Files touched`.**
+   - Run `git diff --name-only $(git merge-base HEAD main)..HEAD` (or `HEAD~10..HEAD` for non-branch work) to find files changed during the session.
+   - For each: cite as `[path](path:line)` if a specific line range was the focus; else `[path](path)`.
+   - LINT will auto-fill `@<sha7>` on save.
+   - Skip generated files, dependency lockfiles, build artifacts.
+
+5. **Capture `## Decisions made`.**
+   - List ADRs in `aiwiki/decisions/` written or modified during this session.
+   - Format: `- [decision-NNNN: short title](aiwiki/decisions/NNNN-slug.md)`.
+   - If none were written but a decision-worthy choice was made conversationally, note: "DEFERRED: {one-line description} — should become an ADR but wasn't written this session."
+
+6. **Capture `## Gotchas surfaced`.**
+   - List gotchas in `aiwiki/gotchas/` created or updated this session.
+   - Same link format.
+   - If a gotcha was hit but not captured, note it as DEFERRED.
+
+7. **Capture `## Open questions`.**
+   - List raw notes in `aiwiki/raw/{today}.md` that represent unresolved questions (entries starting with "TBD", "open", "?", or that were /note'd as questions).
+   - Format: `- [HH:MM question title](aiwiki/raw/{date}.md#anchor)`.
+   - If no /note questions were captured but threads are open, list them as bare bullets.
+
+8. **Capture `## Next steps`.**
+   - 2-5 bullets: what the next session should do.
+   - Each bullet should reference a file/manifest/issue. No vague "continue working on X."
+   - Examples:
+     - "Resume `feature/wire-dream` at Phase 6 (slice graph in manifest) — first slice: `wire-pre-compact-hook`."
+     - "Review pending dream `aiwiki/proposed/2026-05-18-1742-manual/` before next phase."
+     - "Address open question on token rotation policy — see `aiwiki/raw/2026-05-18.md#14-23`."
+
+9. **Update frontmatter.**
+   - Set `focus: {focus}` (from Step 2).
+   - Set `status: done`.
+   - Set `date_end: {today ISO date}`.
+   - Set `last_commit: {git rev-parse --short HEAD}` if in a git repo with commits.
+
+10. **Confirm with the user.**
+    - Surface the drafted session file content.
+    - Ask: "Save this as your session handoff?" — yes / edit / skip.
+    - If edit: take inline edits, re-render, ask again.
+    - If skip: leave the file's `status: active` (next session-start will surface it as unfinalized).
+
+11. **Save and lint.**
+    - Write the file.
+    - `wiki-lint` runs automatically on save (PostToolUse hook).
+    - If lint surfaces warnings (missing citations, stale `@<sha7>`, etc.), address before considering /wrap complete.
+
+12. **Suggest follow-ups.**
+    - If `aiwiki/raw/{today}.md` has unconsolidated entries, suggest: "You have N raw notes from this session — consider `/dream raw` to consolidate before next session."
+    - If a pending dream proposal exists in `aiwiki/proposed/`, surface: "N pending dream proposals — review via `forge wiki ui` before next session."
+
+## Example
+
+```
+User: /wrap
+
+Agent: Session 2026-05-18-7e8a3f2 (focus: feature/wire-dream).
+       Drafted handoff with:
+         - 11 files touched (skills/, hooks/, commands/, templates/)
+         - 1 decision (consolidate notepad → sessions/)
+         - 0 new gotchas this session
+         - 2 open questions
+         - 4 next-step bullets
+
+       [Renders the proposed file content]
+
+       Save?
+
+User: yes
+
+Agent: Saved aiwiki/sessions/2026-05-18-7e8a3f2.md (status: done).
+       Suggestion: 3 raw notes from /note today — consider /dream raw to
+       consolidate before next session.
+```
+
+## When to use
+
+- **At the natural end of a working session** before exiting Claude Code. Even a 30-second wrap-up preserves the handoff signal.
+- **Before a long break** (overnight, end of day). The next session-start surfaces this file so you don't lose context.
+- **Before a major context shift** (switching to a different feature mid-day). Wrap the current focus, then start fresh.
+- **After a phase locks** if the natural pause is also a session end. (Phase-close already triggers a dream — `/wrap` is the complementary capture for what *you* did, while dream consolidates the *wiki state*.)
+
+## When NOT to use
+
+- **Trivial sessions** (a single read, a one-line edit). No handoff signal — skip /wrap and let the next session-start surface "no recent session" (silence is fine).
+- **Mid-task interruptions** where you'll be right back. /wrap is for genuine session boundaries.
+- **As a substitute for typed-page writes.** Decisions belong in `aiwiki/decisions/` directly; gotchas in `aiwiki/gotchas/`. /wrap is the *index* of what was written elsewhere — it doesn't replace writing the artifacts themselves.
+- **As a substitute for `/dream`.** /wrap captures this session's work; /dream consolidates the whole aiwiki. Use both at the right times.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `aiwiki/sessions/` (scaffolded by `/setup`), Claude Code's hook context for `session_id` (or interactive fallback) |
+| **Produces** | `aiwiki/sessions/{date}-{session_id_short}.md` with index sections filled and `status: done` |
+| **Triggers** | `wiki-lint` PostToolUse hook on save |
+| **Feeds into** | `session-start.sh` (next session reads it), `support-dream` (refines on next dream cycle) |
+
+## Do NOT
+
+- Do NOT auto-fire `/dream` from inside `/wrap`. The two are separate concerns; user decides which to run. /wrap can SUGGEST /dream when raw notes accumulated, but does not invoke it.
+- Do NOT overwrite the `## Checkpoints` section if pre-compact wrote to it during the session — that's append-only event log, preserved as-is.
+- Do NOT write vague prose. Index of links, not narrative. Future sessions follow the links to actual artifacts.
+- Do NOT capture every file diff. Skip dependency lockfiles, build artifacts, anything ≤2 lines of cosmetic change. Index the meaningful work.
+- Do NOT set `status: done` if the user said "skip" at Step 10 — leave `status: active` so the next session-start surfaces it.

package/dist/init.js

@@ -12,7 +12,7 @@ import { hasForgeMarkers, mergeForgeBlock } from "./merge.js";
  * entries the user does not already have. Creates .gitignore if absent.
  *
  * Entries:
- *   .forge/state/      — operational state (notepad, telemetry, dream history)
+ *   .forge/state/      — operational state (telemetry, dream history; session handoff lives in aiwiki/sessions/)
  *   .forge/local.yaml  — per-user preferences (Codex/Graphify consent, etc.)
  *
  * Why at install time: pre-compact.sh used to add `.forge/state/` from the

package/hooks/config/gate-requirements.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Maps manifest gate names to required skill and agent invocations. Used by gate-enforcer.sh to verify prerequisites before allowing gate-passed: true. Agents are dispatched by skills internally — listed here so the enforcer can verify they were invoked via telemetry.",
+  "_comment": "Maps manifest gate names to required skill and agent invocations. Used by gate-enforcer.sh to verify prerequisites before allowing gate-passed: true. Enforcement is work_id-scoped (v6.2+): the enforcer filters .forge/state/telemetry.jsonl to records whose work_id matches the manifest being edited (extracted from .forge/work/{type}/{name}/manifest.yaml). A stale invocation from another work item, or a legacy record written before work_id was added, does NOT satisfy a fresh gate. Agents are dispatched by skills internally — listed here so the enforcer can verify they were invoked via telemetry.",
   "requirements": {
     "skill": "discover-requirements",
     "agent": null

package/hooks/scripts/gate-enforcer.sh

@@ -83,6 +83,14 @@ if [ ! -f "$CONFIG" ]; then
   exit 0
 fi
 
+# Extract work_id from the manifest path: .forge/work/{type}/{name}/manifest.yaml
+# Used to filter telemetry by work item so a stale invocation from another work
+# item cannot satisfy this gate (closes P0-5 from v6.1-beta audit).
+WORK_ID=""
+if [[ "$FILE_PATH" =~ \.forge/work/([^/]+)/([^/]+)/manifest\.yaml$ ]]; then
+  WORK_ID="${BASH_REMATCH[1]}/${BASH_REMATCH[2]}"
+fi
+
 # Check each gate being passed against requirements
 BLOCKED_REASONS=""
 
@@ -126,18 +134,55 @@ for GATE in $(jq -r 'keys[] | select(. != "_comment")' "$CONFIG"); do
     # Resolve required agents: agents array first, then single agent field
     REQUIRED_AGENTS=$(jq -r "if .\"$GATE\".agents then .\"$GATE\".agents[] else .\"$GATE\".agent // empty end" "$CONFIG" 2>/dev/null)
 
-    # Check skill invocation in telemetry
+    # Telemetry check is work_id-scoped (closes P0-5 cross-work-item bypass).
+    # Records without work_id (legacy or no-active-work) are NOT counted —
+    # an untagged invocation can't satisfy a gate on a specific work item.
+    # Records lacking jq-parsable shape are also ignored (jq returns null per line;
+    # `select(...)` filters them out).
+    check_invocation() {
+      local NAME="$1"
+      if [ ! -f "$TELEMETRY" ]; then
+        return 1
+      fi
+      if [ -z "$WORK_ID" ]; then
+        # No work_id resolved from path — should be rare; fall back to bare-name
+        # check so we don't accidentally hard-block manifest edits made outside
+        # the .forge/work/{type}/{name}/ tree (unlikely given the path filter
+        # at line ~43 already excluded non-manifest paths, but defensive).
+        grep -q "\"name\":\"$NAME\"" "$TELEMETRY" 2>/dev/null
+      else
+        # jq -s collects all JSONL lines into an array. select() narrows to the
+        # exact work_id + name pair. length > 0 means at least one invocation
+        # in this work item. The 2>/dev/null swallows parse errors on
+        # malformed records (treated as no match — correct behavior).
+        local COUNT
+        COUNT=$(jq -s --arg work_id "$WORK_ID" --arg name "$NAME" \
+          'map(select(.work_id == $work_id and .name == $name)) | length' \
+          "$TELEMETRY" 2>/dev/null || echo 0)
+        [ "$COUNT" != "0" ] && [ -n "$COUNT" ]
+      fi
+    }
+
+    # Check skill invocation in telemetry (work_id-scoped)
     if [ -n "$REQUIRED_SKILL" ]; then
-      if [ ! -f "$TELEMETRY" ] || ! grep -q "\"name\":\"$REQUIRED_SKILL\"" "$TELEMETRY"; then
-        BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires skill '$REQUIRED_SKILL' (not found in telemetry). "
+      if ! check_invocation "$REQUIRED_SKILL"; then
+        if [ -n "$WORK_ID" ]; then
+          BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires skill '$REQUIRED_SKILL' (not invoked for work_id '$WORK_ID'). "
+        else
+          BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires skill '$REQUIRED_SKILL' (not found in telemetry). "
+        fi
       fi
     fi
 
-    # Check agent dispatch in telemetry
+    # Check agent dispatch in telemetry (work_id-scoped)
     for AGENT in $REQUIRED_AGENTS; do
       if [ -n "$AGENT" ] && [ "$AGENT" != "null" ]; then
-        if [ ! -f "$TELEMETRY" ] || ! grep -q "\"name\":\"$AGENT\"" "$TELEMETRY"; then
-          BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires agent '$AGENT' (not found in telemetry). "
+        if ! check_invocation "$AGENT"; then
+          if [ -n "$WORK_ID" ]; then
+            BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires agent '$AGENT' (not dispatched for work_id '$WORK_ID'). "
+          else
+            BLOCKED_REASONS="${BLOCKED_REASONS}Gate '$GATE' requires agent '$AGENT' (not found in telemetry). "
+          fi
         fi
       fi
     done