forge-orkes 0.31.0 → 0.33.0

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

@@ -45,6 +45,37 @@ its version runs it once, and after the version is stamped it falls out of range
 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.)
 
+### Experimental-skill guard (read if your change lives in an experimental skill)
+
+If the behavior your guide migrates is implemented **only inside an experimental,
+opt-in skill** (e.g. `.claude/skills/orchestrating/` from `experimental/m10/`),
+a version-stamp check is **not enough**. `upgrading` never overwrites an
+experimental skill in its base sync (it offers a re-sync in Step 3b, which the
+user may decline), so the skill can stay pinned at install-time content while the
+version stamp advances — and a stamp-only Detection block would report "nothing
+to migrate" while the behavior is silently absent. This is exactly how the 0.28.0
+repo-scoped worktree root became a no-op (issue #5).
+
+So when your change touches experimental-skill behavior, the Detection block MUST
+inspect the **skill's content on disk**, not the version, and emit `MIGRATE` when
+the skill is stale:
+
+```bash
+# The behavior lives in an experimental skill — check its CONTENT, not the version.
+S=.claude/skills/orchestrating/SKILL.md
+[ -f "$S" ] || exit 0                       # skill not installed → nothing to do
+if grep -q 'forge-worktrees' "$S" \
+   && ! grep -q '<repo>-worktrees' "$S"; then
+  echo "MIGRATE — experimental orchestrating skill is pinned to the pre-0.28.0 worktree root; re-sync it"
+fi
+```
+
+Better still, **also promote the load-bearing convention into base** (`FORGE.md`
+or a base skill) so it is upgrade-synced regardless of the experimental skill's
+state — then the base workflow no longer depends on experimental internals at all
+(issue #6). The content-check Detection above is the floor; base promotion is the
+durable fix.
+
 ### Detection block skeleton (applies)
 
 ```bash
@@ -106,5 +137,7 @@ must be confirmed with the user.>
 - [ ] 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).
+- [ ] If the change lives in an experimental skill, Detection checks the skill's **content** (not just the version stamp) — see the Experimental-skill guard above.
+- [ ] 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"