forge-orkes 0.30.0 → 0.32.0

package/template/.forge/migrations/0.32.0-chief-streams.md

@@ -0,0 +1,159 @@
+# Migration Guide: Chief/Streams (Forge 0.32.0)
+
+Adds Project Chief / Streams support to existing Forge projects. This migration
+installs framework-owned stream templates and adapter routing, and offers active
+context compaction. It must never overwrite user-owned runtime stream state in
+`.forge/streams/`.
+
+## Prerequisites
+
+1. Upgrade framework files first so this guide and the new templates are present.
+2. Commit or stash unrelated work.
+3. If `.forge/streams/` already exists, treat it as user state and preserve it.
+
+## Detection
+
+Prints `MIGRATE` when stream templates, Chief routing, active-context
+compaction support, or active M10 adoption appears missing. Silent + exit 0
+means no migration needed.
+
+```bash
+need=0
+
+for f in \
+  .forge/templates/streams/active.yml \
+  .forge/templates/streams/stream.yml \
+  .forge/templates/streams/brief.md \
+  .forge/templates/streams/work-package.yml
+do
+  [ -f "$f" ] || need=1
+done
+
+if [ -f .claude/skills/forge/SKILL.md ] && ! grep -q 'chief-of-staff' .claude/skills/forge/SKILL.md; then
+  need=1
+fi
+
+if [ -f .claude/skills/chief-of-staff/SKILL.md ]; then
+  :
+else
+  need=1
+fi
+
+if [ -f .forge/context.md ] && [ ! -f .forge/context-archive.md ]; then
+  bytes=$(wc -c < .forge/context.md | tr -d ' ')
+  [ "$bytes" -gt 12288 ] && need=1
+fi
+
+if [ ! -f .forge/streams/active.yml ] && grep -R "worktree_mode: \\(active\\|degraded\\)" .forge/state/milestone-*.yml >/dev/null 2>&1; then
+  need=1
+fi
+
+if [ "$need" -eq 1 ]; then
+  echo "MIGRATE - Chief/Streams templates, routing, context compaction, or M10 adoption missing"
+fi
+```
+
+## Migration Steps
+
+### 1. Add Stream Templates
+
+Copy the framework-owned templates from the upgraded Forge source into:
+
+- `.forge/templates/streams/active.yml`
+- `.forge/templates/streams/stream.yml`
+- `.forge/templates/streams/brief.md`
+- `.forge/templates/streams/work-package.yml`
+
+Create parent directories if needed. Do not copy anything into `.forge/streams/`
+unless the user explicitly asks to instantiate a real stream.
+
+### 2. Add Chief Skill And Routing
+
+Copy the Chief skill into the platform adapter used by the project:
+
+- Claude adapter: `.claude/skills/chief-of-staff/SKILL.md`
+- Codex/AGENTS adapter, if present in that project: `.agents/skills/chief-of-staff/SKILL.md`
+
+Update the Forge entry skill for the active adapter so stream intents route to
+Chief before tier detection. Required intent examples:
+
+- `show streams`
+- `start stream`
+- `pause stream`
+- `resume stream`
+- `delegate stream`
+- `sync streams`
+- `detect conflicts`
+- `merge safe`
+- `close stream`
+- `Chief of Staff`
+
+### 3. Preserve Runtime State
+
+If `.forge/streams/` already exists, inspect it but never overwrite it. Runtime
+stream files are user/project state, not framework templates. If a runtime file
+is missing a field, add it only after showing the diff to the user.
+
+### 4. Adopt Existing M10 Worktrees When Present
+
+If `.forge/state/milestone-*.yml` contains `lifecycle.worktree_mode: active` or
+`degraded`, adopt those M10 sessions as streams. Do not teardown, merge, rebase,
+remove, or rename existing worktrees as part of migration.
+
+For each active M10 worktree:
+
+1. Read the milestone state and `git worktree list --porcelain`.
+2. Create or update `.forge/streams/active.yml`.
+3. Create or update:
+   - `.forge/streams/{stream-id}.yml`
+   - `.forge/streams/{stream-id}/brief.md`
+   - `.forge/streams/{stream-id}/packages/`
+4. Map existing M10 fields into stream state:
+   - `lifecycle.worktree_path` -> `runtime.worktree`
+   - `lifecycle.worktree_branch` -> `runtime.branch`
+   - `lifecycle.session_id` / `claim_session_id` -> `runtime.worker_sessions`
+   - milestone id/name/status/phase -> stream goal, context, and brief
+5. Leave ownership surfaces empty if unknown and mark them as needing
+   declaration. Missing ownership should surface as a conflict to resolve after
+   adoption; it should not block adoption.
+6. Ask before setting `orchestration.auto: false` in `.forge/project.yml`.
+   Turning it off makes Chief/Streams the front door while keeping M10 available
+   as an optional backend.
+
+Adoption is idempotent: if a stream already references the same worktree path or
+branch, update that stream's summary/brief instead of creating a duplicate.
+
+### 5. Compact Active Context When Needed
+
+If `.forge/context.md` is over 12 KB and `.forge/context-archive.md` is missing:
+
+1. Copy the original `.forge/context.md` to `.forge/context-archive.md`.
+2. Keep current/open decisions, Deferred Ideas, Needs Resolution, and Amendment
+   Log in `.forge/context.md`.
+3. Move completed historical milestone decision blocks into the archive.
+4. Add a pointer in active context to `.forge/context-archive.md`.
+
+This step must preserve decision text losslessly.
+
+### 6. Confirm M10 Positioning
+
+If the project has M10 installed, keep worktree and merge safety instructions.
+Update wording so Chief/Streams is the user-facing orchestration model and M10
+is an optional backend for worktree isolation, merge queue support, and optional
+file claims.
+
+## Validation
+
+- Stream templates exist under `.forge/templates/streams/`.
+- Chief skill exists in the active platform adapter.
+- Forge routing mentions `chief-of-staff`, `show streams`, `start stream`, and
+  `merge safe`.
+- `.forge/streams/` runtime state is unchanged unless the user approved a
+  specific migration of a runtime stream file.
+- Existing active/degraded M10 worktrees, if any, are represented in
+  `.forge/streams/active.yml` and per-stream files without teardown.
+- If context compaction ran, `.forge/context-archive.md` contains historical
+  decisions and `.forge/context.md` is under 12 KB.
+- Running detection a second time is idempotent and prints no `MIGRATE` once the
+  project has templates, routing, Chief skill, compacted context, and adopted
+  active M10 worktrees.

package/template/.forge/releases.yml

@@ -1,29 +1,99 @@
 # Forge Release Registry — version reservations across concurrent milestones
 #
 # PURPOSE: remove the version number + CHANGELOG slot from per-milestone scope so
-# two milestones running in parallel sessions never collide on your project's
+# two milestones running in parallel sessions never collide on `package.json`
 # version or pick the same number. This is the coordination point both sessions
 # read and append to.
 #
 # COMMITTED + APPEND-ONLY. Each milestone appends exactly ONE entry when it
 # reserves its version (at planning, or at delivery if planning predates this
 # file). Appending — never editing prior entries — is what keeps two sessions
-# from conflicting: distinct lines, no contention. Commit and push the
-# reservation so a parallel session pulls and sees numbers already taken.
+# from conflicting: distinct lines, no contention. The registry is committed and
+# pushed so a parallel session pulls and sees reservations already taken.
 #
 # RULE: the next free version = highest `version:` in this file, bumped by the
-# change's semver level (capability = minor; fix/doc = patch). Delivery NEVER
-# writes a project version that is not reserved here first.
+# change's semver level (capability = minor 0.x.0; fix/doc = patch 0.x.y; see the
+# version-bump criteria in FORGE.md / project memory). Delivery NEVER writes a
+# `package.json` version that is not reserved here first.
 #
 # RACE NOTE: reserve EARLY (at planning), commit + push the reservation BEFORE
-# editing the version. If two sessions reserve near-simultaneously, the second
-# push rebases onto the first (append-only → no conflict) and re-reads max() to
-# take the next number.
+# editing package.json. If two sessions reserve near-simultaneously, the second
+# push rebases onto the first (append-only → no conflict) and must re-read max()
+# and take the next number.
 
-releases: []
-# Example entry shape (delete this comment once you add a real one):
-#   - milestone: 1
-#     version: "0.2.0"
-#     bump: minor
-#     reserved_at: "YYYY-MM-DD"
-#     summary: "one-line description of the milestone"
+releases:
+  - milestone: 12
+    version: "0.21.0"
+    bump: minor
+    reserved_at: "2026-06-12"
+    summary: "CLAUDE.md @import extraction (framework prose → .forge/FORGE.md)"
+  - milestone: 13
+    version: "0.20.0"
+    bump: minor
+    reserved_at: "2026-06-12"
+    summary: "Nested phase layout (phases/milestone-{id}/{phase}-{name}/)"
+  - milestone: 14
+    version: "0.22.0"
+    bump: minor
+    reserved_at: "2026-06-13"
+    summary: "Refactor-backlog compaction migration + lifecycle (archive terminal items, size gate, status-vocab enforcement)"
+  - milestone: 10
+    version: "0.23.0"
+    bump: minor
+    reserved_at: "2026-06-14"
+    summary: "M10 auto-routing — forge routes Standard/Full through orchestrating when installed (install = consent); orchestration.auto opt-out"
+  - milestone: 15
+    version: "0.24.0"
+    bump: minor
+    reserved_at: "2026-06-14"
+    summary: "Disconfirm-before-commit rigor: debugging Confirmation Gate (blind-spot check), architecting Platform & Goal Validation + option-space framing, discussing widen-before-narrowing, CLAUDE.md principle 8"
+  - milestone: 16
+    version: "0.25.0"
+    bump: minor
+    reserved_at: "2026-06-14"
+    summary: "Worktree branch anchor in forge milestone selection — git branch deterministically selects the milestone (exact lifecycle.worktree_branch match, or milestone-id token in branch name) before the timestamp default; deferred/complete matches surface instead of auto-resuming"
+  - milestone: 16
+    version: "0.26.0"
+    bump: minor
+    reserved_at: "2026-06-14"
+    summary: "Milestone-anchored worktree naming in orchestrating — worktree dir + branch become forge/m-{id}-{session_id} (was forge/{uuid}), adds lifecycle.worktree_anchor. Makes the 0.25.0 branch-anchor id-token fallback work for orch worktrees so a moved/stale-state worktree still resolves to its milestone off the branch name alone; uuid suffix keeps collision-resistance, forge/ prefix keeps GC sweep"
+  - milestone: 17
+    version: "0.27.0"
+    bump: minor
+    reserved_at: "2026-06-15"
+    summary: "Human Verification Gate — hard block on milestone close + orchestration teardown until an explicit human sign-off is recorded as current.human_verified in milestone state. Code-level PASS is necessary but never sufficient to close. Captured by verifying (post-verdict prompt), enforced at reviewing-complete + orchestrating Step 5.0; recorded-override (method: override) is the only bypass and is surfaced. New current.human_verified state field — lazy migration: absent = prompt on next close, already-complete milestones never re-gated."
+  - milestone: 18
+    version: "0.28.0"
+    bump: minor
+    reserved_at: "2026-06-15"
+    summary: "Configurable repo-scoped worktree root — orchestration.worktree_root defaults to ../<repo-name>-worktrees/ (was shared ../forge-worktrees/). Fixes cross-repo worktree mixing when multiple repos share a parent dir, fixes cwd-sensitive resolution (relative roots now resolve against repo root, not shell cwd), and folds a gitignore-guard for repos with fully-ignored .claude/ trees (initializing writes correct carve-out for greenfield; upgrading detects + warns for brownfield)"
+  - milestone: 19
+    version: "0.29.0"
+    bump: minor
+    reserved_at: "2026-06-15"
+    summary: "Shared-state taxonomy for multi-worktree Forge — FORGE.md State Ownership expanded to enumerate all 5 file-sharing classes (single-owner mutable, derived, append-only shared, shared mutable, stable shared) with the rule each follows. Promotes 'do not touch another worktree's state files' to explicit rule. Adds structural rule for context.md + refactor-backlog.yml (write only to your milestone block, within-block append-only). New `forge` boot worktree-liveness view (lists live Forge worktrees + their owning milestones in main). Cross-tree write warnings in discussing (context.md) + reviewing (refactor-backlog.yml). Opt-in worktree-side rebase check at boot (gated by forge.worktree_rebase_check). Triggered by the canvaz 2026-06-15 case: main-session edits to m9's context block were invisible to the m9 worktree."
+  - milestone: 20
+    version: "0.30.0"
+    bump: minor
+    reserved_at: "2026-06-16"
+    summary: "Upstream desire-path feedback channel (ADR-012) — closes the capture→act loop in Principle 7. (1) Plan-anchor re-derivation guard already landed (commit 5ddf3a1): executing re-derives plan literals against HEAD before the first task; planning makes anchors drift-resistant. (2) `scope: project|framework` field added to the desire-path schema, set at capture by verifying/executing/planning (lazy migration: absent⇒project). (3) Single review owner = forge boot — retires verifying's duplicate 'Surface Recommendations', co-locates the type→evolution suggestion table, adds a decline-ledger (declined/) so declines stop re-nagging, adds a Quick-tier review trigger in quick-tasking. (4) Tiered upstream transport for scope:framework signals: always write a portable block to state/desire-paths/upstream/; offer `gh issue create` against forge.upstream_repo (default github.com/zayneupton/forge) when gh present; upgrading harvests upstream/ into {source}/docs/desire-paths-inbox/. Optional forge.upstream_repo added to project.yml. Triggered by the canvaz plan-anchor-drift signal that could only reach the framework via manual chat copy-paste."
+  - milestone: 15
+    version: "0.31.0"
+    bump: minor
+    reserved_at: "2026-06-17"
+    summary: "Data-driven migration detection — replaces hardcoded per-version detection blocks (SKILL Step 7 + bin detectLegacyLayouts) with a single loop over synced .forge/migrations/{v}-*.md guides, ranged (installed, source]. New uniform Detection-block contract: echo `MIGRATE` on stdout when the migration applies, silent/exit-0 for no-op. All 7 guides normalized to it (0.28.0 consolidated to one `## Detection`; 0.29.0 stays an explicit in-range no-op). Removes the staleness class entirely — a new guide is auto-covered the moment it ships in the template, zero per-version code, and the install-run blind spot is fixed (detection keys off freshly-synced guides + pre-bump installed version). Triggered by ptnrkit 0.19.2→0.30.0 upgrade where bin was 4 versions behind and 2 real on-disk migrations (0.20.0, 0.22.0) reported 'needs manual review: 0'."
+  - milestone: 16
+    version: "0.32.0"
+    bump: minor
+    reserved_at: "2026-06-18"
+    summary: "Project Chief / Streams orchestration — adds Project/Stream/Work Package runtime layers, Chief of Staff routing, stream/work-package templates, active context compaction, framework-wide size audit, and an idempotent migration guide. M10 is repositioned as an optional backend for worktree isolation, merge queue support, and experimental file claims."
+
+# Note on the 15 / 0.24.0 ordering: reserved as max(0.23.0)+minor. origin/main was
+# already at 0.23.0 when this shipped (M10/M12/M13/M14 all merged), so 0.24.0 is a
+# clean increment — no publish-order coordination needed. (Earlier draft of this
+# release was built on a stale 0.19.2 base before a fetch corrected it.)
+
+# Note on the 12/13 ordering: both reserved 2026-06-12. M13 holds the lower number
+# (0.20.0) and M12 the higher (0.21.0) by explicit user decision — they ship in the
+# same package release, M12 topping the version. max() here is 0.21.0, so the next
+# milestone reserves 0.22.0 (minor) regardless of which milestone id is higher.

package/template/.forge/templates/context.md

@@ -2,6 +2,10 @@
 
 Created during the discuss phase. This document is a contract between the user and all downstream agents.
 
+Active context target: <= 12 KB. When completed historical milestone decision
+blocks accumulate, copy them to `.forge/context-archive.md` and keep only
+current/open decisions here.
+
 **Rules:**
 - **Locked Decisions** → MUST be implemented exactly as stated. No alternatives. No "better" solutions.
 - **Deferred Ideas** → MUST NOT appear in plans, tasks, or code. Not even as TODOs.

package/template/.forge/templates/migration-guide.md

@@ -0,0 +1,111 @@
+# Migration Guide Template
+
+Copy to `.forge/migrations/{version}-{slug}.md` (e.g. `0.31.0-foo.md`) when a Forge
+version changes an on-disk layout, a config field, or a state shape that older
+projects need to migrate. Also mirror the file to `docs/migrations/{version}-{slug}.md`
+(canonical) — the two copies must be byte-identical.
+
+A guide written to this contract is **auto-covered** by the post-upgrade migration
+check in BOTH routes (`upgrading` SKILL Step 7 and `npx forge-orkes upgrade`) the
+moment it ships in the template. **You do not edit `upgrading/SKILL.md` or
+`create-forge.js`** — they loop over the guides, so a conformant new guide just works.
+
+---
+
+## The Detection-block contract (load-bearing — read before writing the guide)
+
+The data-driven migration loop in both routes finds each guide, decides whether it is
+in range, and runs its Detection block. For that to work, every guide MUST follow this
+contract:
+
+1. **Exactly one `## Detection` heading per guide.** Not `### Detection`, not two of
+   them. If a guide has informational sub-checks (e.g. an inventory the user should see
+   but that does NOT trigger a migration), give them a different heading — only the one
+   `## Detection` block is run.
+2. **Under it, exactly one fenced ` ```bash ` block.** It is run from the project root,
+   must tolerate absent files (`[ -f … ] || exit 0`, `2>/dev/null`), and must not depend
+   on the user's shell config. The loop runs it under `bash` explicitly — do not rely on
+   zsh-only or interactive features. (The Bash tool runs zsh; `$BASH_REMATCH` / `=~`
+   capture groups silently fail — avoid them.)
+3. **Sentinel = `MIGRATE`.** The block echoes the literal token `MIGRATE` on stdout when
+   the migration applies. A trailing `— reason` after it is encouraged — it surfaces in
+   the prompt the user sees. When there is nothing to migrate (no-op guides included),
+   the block prints **no** `MIGRATE` token and exits 0.
+4. **No-op guides still get the heading.** A documentation/skill-behavior-only change
+   (nothing on disk to migrate) keeps a `## Detection` heading with a bash block that
+   simply `exit 0`s, so the loop's heading-find stays uniform across all guides.
+
+### Range gating (why you never touch the loop code)
+
+The loop reads the project's **installed** version (`settings.json forge.version`, captured
+BEFORE the upgrade stamps the new value) and the **source** version
+(`packages/create-forge/package.json`). It runs only the guides where
+`installed < {guide version} <= source`. So a guide ships, the next upgrade that crosses
+its version runs it once, and after the version is stamped it falls out of range — no
+ledger, no per-version code, no staleness. (It also closes the install-run blind spot:
+detection keys off the freshly-synced guides on disk, not the skill's own pre-sync code.)
+
+### Detection block skeleton (applies)
+
+```bash
+# Detect the legacy shape; tolerate absent files; emit MIGRATE iff it applies.
+F=.forge/some-file.yml
+[ -f "$F" ] || exit 0
+if grep -q 'legacy-marker' "$F"; then
+  echo "MIGRATE — <one-line reason the user will see>"
+fi
+```
+
+### Detection block skeleton (no-op guide)
+
+```bash
+# Documentation / skill-behavior change only — nothing on disk to migrate.
+exit 0
+```
+
+---
+
+## Guide skeleton
+
+```markdown
+# Migration Guide: <Title> (Forge <version>)
+
+Applies to <which projects>. <One-paragraph what-changed-and-why.>
+
+## Prerequisites
+
+1. <e.g. on the new version's framework files (run `npx forge-orkes upgrade` first)>
+2. <e.g. working tree clean or changes committed — migration touches N files>
+
+## Detection
+
+<One sentence: prints `MIGRATE` when it applies; silent + exit 0 otherwise.>
+
+​```bash
+<the single detection block per the contract above>
+​```
+
+## Migration steps
+
+### 1. <step>
+### 2. <step>
+...
+<The migration is NEVER auto-applied. In Claude Code it runs via the `quick-tasking`
+skill, which the `upgrading` Step-7 prompt hands the guide to on "yes". Lossy steps
+must be confirmed with the user.>
+
+## Validation
+
+<How to confirm the migration succeeded — greps, counts, conservation checks.>
+```
+
+---
+
+## Acceptance self-check before you ship the guide
+
+- [ ] Exactly one `## Detection` heading; exactly one ` ```bash ` block under it.
+- [ ] Block emits `MIGRATE` on stdout iff the migration applies; silent + exit 0 otherwise.
+- [ ] Block is safe on a clean/empty project (no errors, exit 0).
+- [ ] Any new accumulating artifact declares owner, size gate, archive/compaction rule, derived vs source-of-truth status, and future migration behavior.
+- [ ] Mirrored byte-identical to `docs/migrations/{same-name}.md`.
+- [ ] No edit to `upgrading/SKILL.md` or `create-forge.js` was needed (the loop covers it).

package/template/.forge/templates/streams/active.yml

@@ -0,0 +1,34 @@
+# Forge Streams — Active Project Map
+# Size gate: keep this file <= 20 KB. It is the Project Chief's default context.
+# Store summaries only. Deep stream history belongs in streams/{stream}/.
+
+version: 1
+updated_at: null
+
+project_chief:
+  current_stream: null
+  merge_policy: "chief-owned"
+  notes: ""
+
+streams:
+  # - id: "billing-retries"
+  #   status: active              # draft | active | paused | delegated | blocked | ready | merged | closed
+  #   goal: "Fix checkout retry handling"
+  #   branch: "forge/stream-billing-retries"
+  #   worktree: "../app-worktrees/billing-retries"
+  #   owner: ""                   # session/thread/user label
+  #   owned_surfaces:
+  #     - "src/billing/**"
+  #   shared_surfaces:
+  #     - "src/lib/events.ts"
+  #   risk: medium                # low | medium | high | unknown
+  #   blocked_by: []
+  #   next_action: "Review event contract before editing shared surface"
+  #   last_sync: null
+  []
+
+merge_queue:
+  # - stream: "billing-retries"
+  #   status: waiting             # waiting | merging | blocked | merged
+  #   reason: "shared event contract pending"
+  []

package/template/.forge/templates/streams/brief.md

@@ -0,0 +1,47 @@
+# Stream Brief: {stream}
+
+Size gate: keep this brief <= 8 KB. It is the first file loaded when resuming a stream.
+
+## Goal
+
+{One sentence describing the line of work.}
+
+## Current State
+
+Status: draft | active | paused | delegated | blocked | ready | merged | closed
+
+{What is true right now? Include whether code has changed, whether workers are active, and whether merge is safe.}
+
+## Ownership
+
+Owned surfaces:
+- {paths/modules this stream may edit}
+
+Shared surfaces:
+- {paths/modules requiring contract or Project Chief approval}
+
+Read-only surfaces:
+- {paths/modules this stream may inspect but not edit}
+
+Forbidden surfaces:
+- {paths/modules this stream must not touch}
+
+## Decisions
+
+- {Locked decisions that apply to this stream}
+
+## Findings
+
+- {Recent findings needed to resume without chat history}
+
+## Work Packages
+
+- {WP-id}: {status} — {short goal}
+
+## Blockers
+
+- {blocker or "none"}
+
+## Next Action
+
+{The next concrete action for the stream chief or worker.}

package/template/.forge/templates/streams/stream.yml

@@ -0,0 +1,56 @@
+# Forge Stream State
+# Copy to .forge/streams/{stream}.yml.
+# Size gate: keep per-stream state <= 15 KB. Put narrative in brief.md or findings.md.
+
+version: 1
+
+stream:
+  id: ""
+  goal: ""
+  status: draft                    # draft | active | paused | delegated | blocked | ready | merged | closed
+  tier: null                       # quick | standard | full | null until known
+  created_at: null
+  updated_at: null
+  owner: ""
+
+runtime:
+  branch: ""
+  worktree: ""
+  chief_session: ""
+  worker_sessions: []
+
+ownership:
+  owned_surfaces: []
+  shared_surfaces: []
+  read_only_surfaces: []
+  forbidden_surfaces: []
+  reservations:
+    # - surface: "src/lib/events.ts"
+    #   reason: "Event contract update"
+    #   status: proposed          # proposed | approved | blocked | released
+    []
+
+dependencies:
+  blocked_by_streams: []
+  blocks_streams: []
+  contracts: []
+
+context:
+  brief: ".forge/streams/{stream}/brief.md"
+  findings: ".forge/streams/{stream}/findings.md"
+  packages_dir: ".forge/streams/{stream}/packages"
+
+blockers:
+  # - type: decision | conflict | external | human-action
+  #   summary: ""
+  #   since: null
+  #   resolution: ""
+  []
+
+merge:
+  readiness: not_ready              # not_ready | ready | blocked | merged
+  risk: unknown                     # low | medium | high | unknown
+  required_checks: []
+  notes: ""
+
+next_action: ""

package/template/.forge/templates/streams/work-package.yml

@@ -0,0 +1,70 @@
+# Forge Work Package Template
+# Bounded delegated work for a single stream.
+# Copy to: .forge/streams/{stream}/packages/{id}.yml
+
+package:
+  id: "{package-id}"
+  stream: "{stream-id}"
+  title: ""
+  status: draft                  # draft | assigned | active | blocked | ready | returned | closed
+  created_at: "{ISO-8601}"
+  updated_at: "{ISO-8601}"
+  owner: ""                      # worker session, person, or agent label
+  reports_to: "chief-of-staff"   # Project Chief or stream chief
+
+goal:
+  summary: ""
+  observable_outcome: ""
+  non_goals: []
+
+scope:
+  owns:
+    # Files, dirs, modules, routes, or contracts this worker may edit.
+    - ""
+  may_read:
+    # Context surfaces the worker may inspect but should not edit.
+    - ""
+  shared_surfaces:
+    # APIs, schemas, data contracts, docs, or config shared with other streams.
+    - surface: ""
+      contract_owner: ""
+      rule: "report changes before editing"
+  must_not_touch:
+    # Explicit exclusions. Any need to edit these returns to the Chief.
+    - ""
+
+dependencies:
+  blocked_by: []
+  provides_to: []
+  contracts_required: []
+
+verify:
+  commands:
+    # - cmd: "npm test -- ..."
+    #   advisory: false
+  manual_checks: []
+  evidence_required: []
+
+stop_conditions:
+  - "Need to edit must_not_touch or undeclared shared surface"
+  - "Find conflicting ownership with another stream"
+  - "Contract is missing, ambiguous, or contradicted by implementation"
+  - "Task scope expands beyond the package goal"
+  - "Verification cannot be run or fails for reasons outside package scope"
+
+deliverables:
+  - "Changed files or commits"
+  - "Verification evidence"
+  - "Decision notes or conflicts found"
+  - "Recommended next action"
+
+handoff:
+  instructions: ""
+  report_back:
+    to: "chief-of-staff"
+    include:
+      - "what changed"
+      - "what was verified"
+      - "conflicts or scope expansion"
+      - "open risks"
+      - "next action"