forge-orkes 0.77.0 → 0.80.0

package/template/.claude/skills/discussing/SKILL.md

@@ -18,55 +18,54 @@ Structured conversation: approach, trade-offs, decisions. Clarity, not artifacts
 ## Boundaries
 
 - No plans or code
-- Writes `context.md` progressively (after each confirmed decision, not just at handoff)
+- Writes `context/{id}.md` progressively (after each confirmed decision, not just at handoff) — `context-log.md` instead in advisory mode (no milestone yet)
 - No phase/plan required
 - Entered via a worktree already, for new work (R10, `forge/SKILL.md` Step 3) — if this skill is somehow invoked directly on the main checkout for new work, enter one now before writing anything.
 
 ## Progressive Persistence
 
 > **HARD GATE — NOT A GUIDELINE. NO EXCEPTIONS.**
-> Write to `.forge/context.md` after EVERY confirmed decision, before asking the next question.
+> Write to `.forge/context/{id}.md` after EVERY confirmed decision, before asking the next question ({id} = the milestone this discussion is scoped to).
 > If you reach convergence without having written each decision individually — you already violated this rule.
 
-> **Advisory mode (no milestone yet):** Storage still exists. Use `### M? — {topic} (drafting)` heading. Do NOT wait for milestone creation in Step A to start writing. First decision → create heading → append. Same protocol as milestone-bound discussions.
+> **Advisory mode (no milestone yet):** Storage still exists — write to `.forge/context-log.md` instead (there is no `{id}` to shard by yet). Use `### M? — {topic} (drafting)` heading. Do NOT wait for milestone creation in Step A to start writing. First decision → create heading → append. Once Step A creates the milestone, migrate that drafting block from `context-log.md` into the new `.forge/context/{id}.md`.
 
 After each user response that confirms a decision:
 
 1. **STOP** — do not continue the discussion
-2. **Write to disk** — append to `.forge/context.md` (create from template if missing)
-   - **Path is always `.forge/context.md`** — never `.forge/phases/*/context.md`, never inline memory
+2. **Write to disk** — append to `.forge/context/{id}.md` (create from `.forge/templates/context-milestone.md` if missing); `.forge/context-log.md` instead in advisory mode
+   - **Path is always `.forge/context/{id}.md`** (or `.forge/context-log.md` pre-milestone) — never `.forge/phases/*/context.md`, never inline memory, and never the rendered `.forge/context.md` index (derived — read for orientation, never write to it)
 3. **THEN** continue to the next question
 
 Never accumulate decisions in working memory. Never batch writes to convergence.
 
-**Common failure mode:** Agent says "decisions live in conversation; planning writes context.md." This is WRONG. Discussing writes context.md. Planning reads it.
+**Common failure mode:** Agent says "decisions live in conversation; planning writes context.md." This is WRONG. Discussing writes context/{id}.md. Planning reads it.
 
 ### Write Protocol
 
-`context.md` is **shared mutable** state per FORGE.md State Ownership — writes follow two structural rules:
-- **Scope to your milestone's block.** Different milestone blocks → git merges cleanly across worktrees.
-- **Append-only within a block.** When superseding an older decision, *strike through* (`~~old decision~~`) and append the new line below — never rewrite in place. Same-line concurrent edits become impossible by construction; reading the history of a decision becomes possible by inspection.
-- **Keep active context active.** Write current/open decisions to `.forge/context.md`. Do not rehydrate old milestone blocks from `.forge/context-archive.md` unless the user is amending that historical decision.
+`context/{id}.md` is **single-owner mutable, per milestone** (ADR-033) — sharding by milestone means different milestones already write different files, so the old shared-file merge-safety rules collapse to one:
+- **Append-only within your file.** When superseding an older decision, *strike through* (`~~old decision~~`) and append the new line below — never rewrite in place. Reading the history of a decision stays possible by inspection.
+- **Keep active context active.** Write current/open decisions to `.forge/context/{id}.md`. Do not rehydrate old milestone blocks from `.forge/context-archive.md` unless the user is amending that historical decision.
 
 **On first decision of the session:**
-- Check if `.forge/context.md` exists. If not → create it from `.forge/templates/context.md`
-- Add a milestone heading inside `## Locked Decisions`: `### M{id} — {name} (drafting)` (use "M?" if no milestone yet)
+- Check if `.forge/context/{id}.md` exists. If not → create it from `.forge/templates/context-milestone.md`
+- Heading: `### M{id} — {name} (drafting)` (use "M?" and write to `.forge/context-log.md` instead if no milestone yet — see Advisory mode above)
 - If the needed historical decision is archived, cite the archive in the new active decision instead of copying the whole block back.
-- **Cross-tree liveness check (informational).** If editing an existing block for milestone `{id}`, run `git worktree list --porcelain | awk '/^branch / && $2 ~ /refs\/heads\/forge\/m-'"$id"'(-|$)/ {print}'`. Any hit means m{id} is **live in another worktree** — surface one line: *"m{id} is live in worktree at `{path}`. Edits land cleanly on main but won't be visible to that worktree until it rebases or pulls."* Proceed with the write — main is often the canonical author of `context.md`, this is a heads-up, not a block.
+- **Cross-tree liveness check (informational).** If editing an existing `context/{id}.md` for milestone `{id}`, run `git worktree list --porcelain | awk '/^branch / && $2 ~ /refs\/heads\/forge\/m-'"$id"'(-|$)/ {print}'`. Any hit means m{id} is **live in another worktree** — surface one line: *"m{id} is live in worktree at `{path}`. Edits land cleanly on main but won't be visible to that worktree until it rebases or pulls."* Proceed with the write — main is often the canonical author of `context/{id}.md`, this is a heads-up, not a block.
 
 **On each confirmed decision:**
 - Append under the milestone heading: `- **[Topic]**: [Decision]. Reason: [Why]`
 
-**On superseding a prior decision (in your own milestone's block):**
+**On superseding a prior decision:**
 - Find the original line. Wrap it in `~~ ~~` (markdown strikethrough). DO NOT delete it.
 - Append the new decision on a new line below it: `- **[Topic]**: [Decision]. Reason: [Why]. Supersedes ~~prior on {date}~~.`
-- Why: shared-mutable append-only rule (FORGE.md State Ownership). Decisions stay readable as history; concurrent writes from another worktree on a different bullet can't conflict with this one.
+- Why: append-only rule. Decisions stay readable as history; concurrent writes from another worktree touching this same milestone's file on a different bullet can't conflict with this one.
 
 **On deferred ideas** (user says "not now" / "later" / "skip"):
-- Append to `## Deferred Ideas` immediately: `- [Idea] — Deferred because: [reason]`
+- Append to this milestone's `## Deferred` heading in `.forge/context/{id}.md` immediately: `- [Idea] — Deferred because: [reason]`. Genuinely cross-cutting (not owned by this milestone) → `.forge/context/_shared.md`'s `## Deferred Ideas` heading instead — never guess a milestone onto a cross-cutting idea.
 
 **On discretion areas** (left to agent judgment):
-- Append to `## Discretion Areas` immediately
+- Append to this milestone's `## Discretion` heading in `.forge/context/{id}.md` immediately. Cross-cutting → `.forge/context/_shared.md`'s `## Discretion Areas` heading instead.
 
 **At Phase Handoff:**
 - Rename `(drafting)` → `(locked {date})` — decisions are already written, just finalize the heading
@@ -113,11 +112,11 @@ If fresh (after `/clear`):
 ```
 Read: .forge/state/milestone-{id}.yml → current position, progress (skip if no milestone — advisory mode)
 Read: .forge/project.yml → tech stack, project description
-Read: .forge/context.md → existing locked decisions (if exists)
+Read: .forge/context/{id}.md → this milestone's existing locked decisions (if exists)
 Read: .forge/constitution.md → active gates (if exists)
 ```
 
-**Advisory mode (no milestone):** Skip milestone state load. Progressive persistence still applies — writes go to `.forge/context.md` under `### M? — {topic} (drafting)` heading from the first decision. Milestone gets created in Step A only if scope warrants it.
+**Advisory mode (no milestone):** Skip milestone state load. Progressive persistence still applies — writes go to `.forge/context-log.md` under `### M? — {topic} (drafting)` heading from the first decision. Milestone gets created in Step A only if scope warrants it.
 
 Check `.forge/phases/` for research. If inline-only: *"Summarize findings, or re-scan?"*
 
@@ -145,7 +144,7 @@ Brief context paragraph from research.
 
 Surface 3-5 decisions that matter.
 
-**After each user response:** write confirmed decisions to `context.md` immediately (see Progressive Persistence).
+**After each user response:** write confirmed decisions to `context/{id}.md` immediately (see Progressive Persistence).
 
 ### Step 2: Facilitate, Don't Dictate
 
@@ -176,17 +175,17 @@ AskUserQuestion:
 
 Open-ended via prose: *"Tried before?" / "Must-haves or must-nots?"* 1-2 at a time.
 
-**After each user response:** write confirmed decisions/constraints to `context.md` immediately.
+**After each user response:** write confirmed decisions/constraints to `context/{id}.md` immediately.
 
 ### Step 4: Functionality Distillation
 
 Apply Functionality Distillation (above), grounded in research findings.
 
-**After each user response:** write confirmed behavioral decisions to `context.md` immediately.
+**After each user response:** write confirmed behavioral decisions to `context/{id}.md` immediately.
 
 ### Step 5: Pre-Convergence Audit
 
-**Before summarizing, read `.forge/context.md` and verify all confirmed decisions are present.**
+**Before summarizing, read `.forge/context/{id}.md` (or `.forge/context-log.md` in advisory mode) and verify all confirmed decisions are present.**
 
 If any decision from the conversation is missing from the file → write it now. Do not proceed to the summary until the file matches the conversation. This is a hard gate.
 
@@ -213,7 +212,7 @@ options:
 ```
 Read: .forge/phases/milestone-{id}/{phase}-{name}/plan-{NN}.md → the plan
 Read: .forge/requirements/m{N}.yml → source requirements (current milestone)
-Read: .forge/context.md → locked decisions
+Read: .forge/context/{id}.md → this milestone's locked decisions
 Read: .forge/constitution.md → active gates
 ```
 
@@ -315,9 +314,9 @@ If no milestone exists (advisory discussion — forge routed here without tier/m
      - `current.tier` = detected tier
      - `current.status` = `planning` (Standard) / `architecting` (Full) / `not_started` (Quick)
      - `current.last_updated` = now
-     - `decisions[]` = locked decisions from `context.md`
+     - `decisions[]` = locked decisions from the `context-log.md` drafting block
    - Regenerate `.forge/state/index.yml` via the `forge` **Rollup** (read all `milestone-*.yml` → rewrite registry). Do not hand-add the entry. (Create `index.yml` from `.forge/templates/state/index.yml` first if missing.)
-4. **Update `context.md`** — scope decisions under `### M{id} — {name} (locked {date})`
+4. **Migrate the drafting block** — move the `### M? — {topic} (drafting)` block from `.forge/context-log.md` into `.forge/context/{id}.md` (create from `.forge/templates/context-milestone.md` if missing), renaming the heading to `### M{id} — {name} (drafting)`
 5. **Quick tier?** → *"Scope is Quick. `/clear` then `/forge {id}` for quick-tasking."* End.
 6. Proceed to Step B with new milestone.
 
@@ -326,17 +325,17 @@ If milestone exists → skip to Step B.
 ### Step B: Standard Handoff
 
 > **HARD GATE — VERIFY BEFORE HANDOFF.**
-> Read `.forge/context.md` now. Count decisions under the active milestone heading. Compare against decisions confirmed in this conversation.
+> Read `.forge/context/{id}.md` now. Count decisions under `## Locked Decisions`. Compare against decisions confirmed in this conversation.
 > - **If counts match** → proceed to handoff steps below.
 > - **If file is missing, heading absent, or decisions undercount** → progressive persistence failed. STOP. Do NOT recommend `/clear`. Write the missing decisions now from conversation memory, then re-verify. Only then proceed.
 > - **Never claim "state written" without having just read the file.** The recommendation `/clear` is destructive to working memory — earn it.
 
-1. **Promote decisions in `context.md`** -- Rename milestone heading from `(drafting)` → `(locked {date})`. Decisions already written progressively — just finalize:
+1. **Promote decisions in `context/{id}.md`** -- Rename milestone heading from `(drafting)` → `(locked {date})`. Decisions already written progressively — just finalize:
    - Verify all confirmed decisions present under `## Locked Decisions`
    - Verify deferred items under `## Deferred Ideas`
    - Verify discretion areas under `## Discretion Areas`
-   - Add any unresolved items to `## Needs Resolution`
-   - If `context.md` already exists (post-planning discussion), update relevant sections + log amendments
+   - Add any unresolved items to `.forge/context-log.md`'s `## Needs Resolution`
+   - If `context/{id}.md` already exists (post-planning discussion), update relevant sections + log amendments in `context-log.md`'s `## Amendment Log`
 2. **Update state** -- `current.status` = `planning` (`architecting` for Full) in milestone yml
 3. **State-sync commit** (State Commit Protocol): `git -C {worktree_path} add .forge/` then `git -C {worktree_path} commit -m "chore(forge): sync state after discussing — m{N} {name}"` (worktree form — recorded `lifecycle.worktree_path` is authoritative over cwd; see FORGE.md State Commit Protocol. Scoped; never `git add .`).
-4. **Recommend clear:** *"State synced and verified ({N} decisions in context.md). `/clear` then `/forge` for {planning/architecting}."*
+4. **Recommend clear:** *"State synced and verified ({N} decisions in context/{id}.md). `/clear` then `/forge` for {planning/architecting}."*

package/template/.claude/skills/executing/SKILL.md

@@ -127,7 +127,7 @@ For each task in the plan:
 
 1. **Read** task XML (name, files, action, verify, done)
 2. **Mark in-progress** — `TaskUpdate` to `in_progress`
-3. **Check** context.md — honor locked decisions exactly
+3. **Check** context/{id}.md — honor locked decisions exactly
 4. **Implement** per action instructions
 5. **Verify** using the verify step
 6. **Confirm** done criteria met
@@ -317,7 +317,7 @@ Once a task's verification bookkeeping settles (3-Strike result known, declared-
 | Task carries a `complexity` tag whose resolved model **differs from the live session model** (COST, M24) | Spawn a fresh executor on that resolved model — even under 40% context (real routing). |
 | Task carries a `complexity` tag but resolves to the **live session model** (e.g. no `models:` block) | Spawn changes nothing — treat the tag as a context signal only: spawn **iff** a row above fires. Otherwise run inline. |
 
-**Spawn via Agent tool** with: relevant plan details, specific files, locked decisions from context.md, clear success criteria. **Resolve the model PER TASK**, not once per skill run: `models.by_complexity.{task.complexity}` → `models.skills.executing` → `models.default` → parent (complexity overrides skill — FORGE.md → Model Routing). **Then compare the resolved model to the live session model** (the model this session is actually running on): differ → spawn (mandatory routing); equal → the tag is a context signal, not a routing obligation. Display per spawn: *"Spawning executor with model: {model} (from {source})"*
+**Spawn via Agent tool** with: relevant plan details, specific files, locked decisions from context/{id}.md, clear success criteria. **Resolve the model PER TASK**, not once per skill run: `models.by_complexity.{task.complexity}` → `models.skills.executing` → `models.default` → parent (complexity overrides skill — FORGE.md → Model Routing). **Then compare the resolved model to the live session model** (the model this session is actually running on): differ → spawn (mandatory routing); equal → the tag is a context signal, not a routing obligation. Display per spawn: *"Spawning executor with model: {model} (from {source})"*
 
 **Why the tag gates the spawn (predicate A — the spawn must change the model).** Routing only *does* something when a task's resolved model differs from the **live session model**; a same-model spawn is pure briefing overhead — m-30 burned ~315k subagent tokens spawning tasks that resolved straight back to the parent model for zero routing benefit. So the mandatory spawn fires only when resolving actually swaps the model (which requires a `models:` block whose resolution lands on a different tier than the one this session runs on). With **no `models:` block** every resolved model equals the parent == the live session model, so tagged tasks run inline unless a context trigger (20+ files / deep subsystem / >40%) independently calls for a fresh agent. The tag still marks work "worth routing," and an inline task genuinely cannot be re-routed — but that leak only matters when a different model was actually available, which is exactly the resolved-≠-live case the gate keeps mandatory. (A full parent-as-orchestrator model — spawn everything, parent never implements — remains a deferred follow-up, justified by M24 outcome-log evidence, not implemented here.)
 
@@ -360,7 +360,7 @@ Append **one file per observation** to `.forge/state/desire-paths/` — copy `.f
 - **User corrections**: Repeated correction matching a prior one → `type: user_correction`
 - **Agent struggles**: Multiple attempts or user guidance needed → `type: agent_struggle`
 
-**Set `scope` at capture** (see ADR-012): `framework` when the fix this signal implies targets Forge's own skills/templates (a skill's check, a plan/tier heuristic, a template); `project` when it targets user-owned files (`constitution.md`, `design-system.md`, `context.md`, project setup). Record `suggestion_target` when you know the file/skill it touches. `scope: framework` is what later lets `forge` review route the signal upstream instead of trapping it in this project.
+**Set `scope` at capture** (see ADR-012): `framework` when the fix this signal implies targets Forge's own skills/templates (a skill's check, a plan/tier heuristic, a template); `project` when it targets user-owned files (`constitution.md`, `design-system.md`, `context/{id}.md`, project setup). Record `suggestion_target` when you know the file/skill it touches. `scope: framework` is what later lets `forge` review route the signal upstream instead of trapping it in this project.
 
 ## Cross-Layer Seam Check