forge-orkes 0.17.0 → 0.18.1

package/bin/create-forge.js

@@ -318,28 +318,70 @@ function detectLegacyRequirementsLayout() {
 }
 
 /**
- * After upgrade, surface any detected legacy file layouts that the new framework
- * version no longer writes. Non-interactive — prints a warning with a pointer to
- * the migration guide. Add new detection blocks here as future versions change layout.
+ * Detect a pre-0.17.0 project.yml that has no `layers:` field. Cross-layer
+ * contract detection (planning Step 6.1) reads `layers:`; without it the planner
+ * falls back to a coarse top-level-directory heuristic. Returns true if the field
+ * is absent and no contract index has been seeded. False if project.yml is missing
+ * (not yet initialized) or already migrated.
+ */
+function detectMissingLayersConfig() {
+  const projectYml = path.join(targetDir, '.forge', 'project.yml');
+  if (!fs.existsSync(projectYml)) return false;
+
+  let content;
+  try {
+    content = fs.readFileSync(projectYml, 'utf-8');
+  } catch {
+    return false;
+  }
+
+  // Already declared a layers: key (any value, including []) → migrated.
+  if (/^layers:/m.test(content)) return false;
+  // A seeded contract index implies layers were declared at init → migrated.
+  if (fs.existsSync(path.join(targetDir, '.forge', 'contracts', 'index.yml'))) return false;
+
+  return true;
+}
+
+/**
+ * After upgrade, surface any detected legacy file layouts the new framework
+ * version no longer writes, or new config fields older projects lack.
+ * Non-interactive — prints a warning with a pointer to the migration guide.
+ * Add new detection blocks here as future versions change layout.
  */
 function runPostUpgradeMigrationChecks() {
   const legacyReqs = detectLegacyRequirementsLayout();
-  if (legacyReqs.length === 0) return;
+  if (legacyReqs.length > 0) {
+    console.log('  ⚠  Pre-0.10.0 requirements layout detected');
+    console.log('  ─────────────────────────────────────────');
+    console.log('  Found:');
+    for (const p of legacyReqs) {
+      console.log(`    ${p}`);
+    }
+    console.log();
+    console.log('  Forge 0.10.0+ uses per-milestone files at .forge/requirements/m{N}.yml.');
+    console.log('  Migration guide: .forge/migrations/0.10.0-per-milestone-requirements.md');
+    console.log();
+    console.log('  Run the migration before your next planning cycle. In Claude Code:');
+    console.log('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
+    console.log('    with the guide path as the task definition.');
+    console.log();
+  }
 
-  console.log('  ⚠  Pre-0.10.0 requirements layout detected');
-  console.log('  ─────────────────────────────────────────');
-  console.log('  Found:');
-  for (const p of legacyReqs) {
-    console.log(`    ${p}`);
+  if (detectMissingLayersConfig()) {
+    console.log('  ⚠  Cross-layer contracts: project.yml has no `layers:` field (Forge 0.17.0)');
+    console.log('  ──────────────────────────────────────────────────────────────────────');
+    console.log('  Forge 0.17.0 added cross-layer contract detection (planning Step 6.1),');
+    console.log('  which reads `layers:` from .forge/project.yml. Your project.yml predates');
+    console.log('  this field, so planning falls back to a coarse top-level-directory heuristic.');
+    console.log();
+    console.log('  Migration guide: .forge/migrations/0.17.0-cross-layer-contracts.md');
+    console.log();
+    console.log('  Quick fix: add a `layers:` list to .forge/project.yml — or `layers: []`');
+    console.log('  for a single-layer project to silence this notice. In Claude Code:');
+    console.log('    /forge then hand the guide to quick-tasking.');
+    console.log();
   }
-  console.log();
-  console.log('  Forge 0.10.0+ uses per-milestone files at .forge/requirements/m{N}.yml.');
-  console.log('  Migration guide: .forge/migrations/0.10.0-per-milestone-requirements.md');
-  console.log();
-  console.log('  Run the migration before your next planning cycle. In Claude Code:');
-  console.log('    /forge then hand the guide to quick-tasking, or invoke Skill(quick-tasking)');
-  console.log('    with the guide path as the task definition.');
-  console.log();
 }
 
 async function upgrade() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

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

@@ -241,7 +241,7 @@ Do NOT list test failures here — pre-existing failures belong in deferred-issu
 ```
 
 ## State Updates
-1. Update `.forge/state/milestone-{id}.yml` — advance plan counter, update progress
+1. Update `.forge/state/milestone-{id}.yml` — advance `current` cursor (`current.plan`/`current.task`, and `current.phase` when a phase completes). Do **not** write a progress percent — it is derived on read by the `forge` skill from `current.phase` vs the roadmap phase count.
 2. Record deviations in milestone state
 3. Update `.forge/state/index.yml` — set `last_updated` timestamp
 4. All plans in phase complete → transition to `verifying`

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

@@ -20,14 +20,21 @@ Check state files:
 1. Read for active milestones
 2. **Check arg first.** `/forge 2` or `/forge "Auth system"`:
    - Match IDs (exact) or names (case-insensitive substring)
-   - Found → auto-select: *"Resuming {id}: [{name}] -- {current.status}, {overall_percent}%"*
+   - Found → auto-select: *"Resuming {id}: [{name}] -- {current.status}, {percent}%"*
    - No match → *"No match for '{arg}'. Active:"*
 3. **Multiple (no arg):** Show active + not_started milestones with status + `last_updated`. Default most recent. After main list, show **Deferred:** section (id, name, frozen status `was: {current.status}`, defer date, reason). *"{N} active. Most recent: [{name}] ({current.status}, {date}). This one, or switch?"*
-4. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {overall_percent}%"*
+4. **One:** Auto-select. *"Resuming: [{name}] -- {current.status}, {percent}%"*
 5. **None active:** If deferred exist, mention them: *"No active milestones. {N} deferred — 'resume milestone {id}' to reactivate."* Else → init or create.
 6. Load `milestone-{id}.yml`
-7. **Route on `current.status`, NOT `overall_percent`.** Complete only at `complete`. 100% tasks ≠ done -- verifying + reviewing must run.
-8. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `overall_percent`. **No menus.** Position → action → invoke.
+7. **Route on `current.status`, NOT `{percent}`.** Complete only at `complete`. 100% phases ≠ done -- verifying + reviewing must run.
+8. Report + **immediately route** (Step 3). Show: `current.status`, phase labels (Executed/Verified/Pending/In progress -- **never "Complete" for unverified**), `{percent}`. **No menus.** Position → action → invoke.
+
+**`{percent}` is derived on read — never stored.** Compute it, don't look it up:
+- `total` = number of phases listed for this milestone in `.forge/roadmap.yml` (the milestone's `phases:` list length).
+- `done` = `current.status == complete` → `total`; else `max(0, current.phase - 1)` (phases before the active one count as done).
+- `{percent}` = `total > 0` → `round(done / total * 100)`; `total` unknown/0 → omit the percent from the line.
+
+Uses only signals that stay current (`current.phase`, `current.status`, the roadmap phase list). Old milestone files may still carry a vestigial `progress:` block — ignore it; derive anyway.
 
 Beads enabled (`forge.beads_integration: true`) → `bd prime`. Optional.
 
@@ -50,7 +57,6 @@ Check `.forge/refactor-backlog.yml`:
    - `milestone.name: "Promoted from {R-id}: {backlog item title}"`
    - `milestone.origin: {R-id}`
    - `current.tier: standard`, `current.status: researching`
-   - `progress.last_update: {ISO date}`
 3. Append to `.forge/state/index.yml` `milestones:`:
    ```yaml
    - id: m-{R-id}
@@ -196,7 +202,7 @@ Tier + state → invoke via `Skill` tool. All phases use `Skill()`.
 
 1. Read `milestone-{id}.yml` → 2. Check advancement → 3. `current.status` → skill → 4. Brief + route:
 
-*"Milestone {id}: {name} | {current.status} → {next} ({model}) | {overall_percent}% | Routing..."*
+*"Milestone {id}: {name} | {current.status} → {next} ({model}) | {percent}% | Routing..."*
 
 Briefing, not prompt -- default = forward.
 

package/template/.claude/skills/quick-tasking/SKILL.md

@@ -70,8 +70,8 @@ Invoked via forge routing (mid-workflow or refactor-backlog item with milestone
 
 1. Read `.forge/state/milestone-{id}.yml` for current position
 2. Follow standard workflow (above)
-3. After commit: update milestone state — increment `progress.overall_percent`, log deviations if any Rule 1-3 applied
-4. Report: fix description, files changed, milestone progress update
+3. After commit: update milestone state — advance the `current` cursor if the task moved position, log deviations if any Rule 1-3 applied. Do **not** write a progress percent (derived on read by `forge`).
+4. Report: fix description, files changed, current position
 
 ### Without Milestone
 

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

@@ -24,7 +24,7 @@ Template directory: `{source}/packages/create-forge/template/`.
 |----------|-------|----------|
 | **Framework-owned** | `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` | Overwrite |
 | **Merge-owned** | `CLAUDE.md`, `.claude/settings.json` | Never auto-overwrite |
-| **Template-only** | `.forge/templates/**` | Overwrite |
+| **Template-only** | `.forge/templates/**`, `.forge/migrations/**` | Overwrite |
 
 **Never touch** user-generated files: `.forge/project.yml`, `.forge/state/`, `.forge/constitution.md`, `.forge/context.md`, `.forge/requirements/`, `.forge/roadmap.yml`, `.forge/design-system.md`, `.forge/refactor-backlog.yml`.
 
@@ -40,7 +40,7 @@ For each framework-owned file in the source template:
 
 ## Step 4: Sync Template-Only Files
 
-Same process as Step 3 for `.forge/templates/**`.
+Same process as Step 3 for `.forge/templates/**` and `.forge/migrations/**`. (Matches the npm bin's template-only dirs — keeps migration guides installed so the Step 7 pointers resolve via the in-Claude sync route, not just `npx forge-orkes upgrade`.)
 
 ## Step 5: Handle Merge-Owned Files
 
@@ -116,6 +116,35 @@ Run the migration now? (yes/no/show guide)
 - **show guide** → read and display the file, then re-ask
 - **no** → note in upgrade report. Skills will continue reading the legacy path as deprecated; new writes still go to the new path, causing split-brain state. Recommend running migration before next planning cycle.
 
+### Pre-0.17.0 missing `layers:` field
+
+Run from project root:
+
+```bash
+grep -q '^layers:' .forge/project.yml || echo "no layers field"
+ls .forge/contracts/index.yml 2>/dev/null
+```
+
+If `project.yml` has no `layers:` key AND `.forge/contracts/index.yml` is absent, surface:
+
+```
+Cross-layer contracts: project.yml predates the `layers:` field (Forge 0.17.0)
+─────────────────────────────────────────────────────────────────────────────
+Forge 0.17.0 added cross-layer contract detection (planning Step 6.1), which
+reads `layers:` from .forge/project.yml. Without it, planning falls back to a
+coarse top-level-directory heuristic.
+
+A migration guide is available at: .forge/migrations/0.17.0-cross-layer-contracts.md
+
+Add the layers field now? (yes/no/show guide)
+```
+
+- **yes** → invoke `quick-tasking` skill, hand it the migration guide as the task definition (identify layers, write `layers:` to project.yml, seed `.forge/contracts/index.yml` for multi-layer projects)
+- **show guide** → read and display the file, then re-ask
+- **no** → note in upgrade report. Planning still works on the fallback heuristic; cross-layer detection is just imprecise until `layers:` is declared. A single-layer project can set `layers: []` to opt out and clear the notice.
+
+`upgrading` never edits `.forge/project.yml` directly — this is the only path that adds the field, via `quick-tasking`.
+
 ### Future migrations
 
 Add new detection blocks here for each Forge version that changes file layout. Pattern:

package/template/.forge/migrations/0.17.0-cross-layer-contracts.md

@@ -0,0 +1,110 @@
+# Migration Guide: Cross-Layer Contracts (Forge 0.17.0)
+
+Forge 0.17.0 adds **cross-layer contract detection** to planning (Step 6.1). When a phase introduces or changes an interface that one architectural layer *produces* and another *consumes*, the planner pins the shape in a `contract.md` so an agent building one layer in isolation never has to guess the other's shape.
+
+The detector reads a new `layers:` field from `.forge/project.yml`. Projects created before 0.17.0 have no `layers:` field, so the detector falls back to a coarse top-level-directory heuristic. This guide adds the field (and, for genuinely layered projects, a durable contract index) so detection runs precisely. Safe for an agent to run autonomously.
+
+## Why
+
+`upgrading` syncs framework files and reference templates but, by design, **never edits your live `.forge/project.yml`** — that is user-owned state. So the new `layers:` field is not added automatically on upgrade. Until it exists, planning Step 6.1 cannot read declared layers and falls back to guessing from top-level source directories, which is noisy and imprecise.
+
+Adding `layers:` once makes the detection deterministic. A single-layer project sets `layers: []` to opt out cleanly and silence the upgrade notice.
+
+## Prerequisites
+
+1. Forge framework files upgraded to ≥0.17.0 (run `npx forge-orkes upgrade`, or `Skill(upgrading)` for a local dev sync).
+2. Working tree clean or changes committed — this touches `project.yml` and optionally adds one new file.
+
+## Detection
+
+Run from project root. Migration is suggested if `layers:` is absent:
+
+```bash
+# No `layers:` key in project.yml → migration applies
+grep -q '^layers:' .forge/project.yml || echo "no layers field — migrate"
+
+# Already has a contract index? Then layers were declared at init — likely done.
+ls .forge/contracts/index.yml 2>/dev/null
+```
+
+If `project.yml` already contains a `layers:` key (any value, including `[]`), migration is complete — stop here.
+
+## Migration steps
+
+### 1. Identify the project's layers
+
+A **layer** is a directory whose code is *produced for* or *consumed by* another across a typed boundary — `engine ↔ ui`, `core ↔ plugins`, `api ↔ web`, `native ↔ bindings`. A single cohesive codebase with no internal producer→consumer boundary is **not** layered.
+
+```bash
+ls -d */ src/*/ 2>/dev/null        # top-level + src subdirs as candidates
+# Look for cross-boundary imports: ui importing engine types, generated bindings,
+# ABI/descriptor/schema files shared between directories.
+```
+
+Decisive litmus: *"Would an agent building one directory in isolation have to guess the shape another directory owns?"* If no — it is not a cross-layer boundary.
+
+### 2. Add the `layers:` field to project.yml
+
+**Multi-layer project** — list each layer as `{name, path}`:
+
+```yaml
+layers:
+  - name: engine
+    path: src/engine/
+  - name: ui
+    path: src/ui/
+```
+
+**Single-layer project** — declare empty to opt out and silence the upgrade notice:
+
+```yaml
+layers: []
+```
+
+Place it near the top of `project.yml` (the template puts it just after `tech_stack`). Keep the file under the 5 KB size gate.
+
+### 3. (Multi-layer only) Seed the durable contract index
+
+Standing integration points and their governing ADRs live in `.forge/contracts/index.yml`. Create it from the template so planning Step 6.1 can map an integration point to its authoritative ADR:
+
+```bash
+mkdir -p .forge/contracts
+cp .forge/templates/contracts-index.yml .forge/contracts/index.yml
+```
+
+Then edit `.forge/contracts/index.yml`:
+- Fill `layers:` to match what you wrote in `project.yml`.
+- Add one `integration_points:` entry per standing boundary, each pointing at its governing ADR in `.forge/decisions/`. Leave `integration_points: []` if you have no ADRs yet — the first cross-layer phase will populate it.
+
+Single-layer projects skip this step entirely.
+
+## Post-migration verification
+
+```bash
+# Should print the layers key (non-empty list, or [])
+grep -A4 '^layers:' .forge/project.yml
+
+# Multi-layer projects: index exists and is not the unfilled template
+test -f .forge/contracts/index.yml && echo "contract index present"
+```
+
+Commit as a single change:
+
+```
+chore(forge): declare layers for cross-layer contract detection (0.17.0)
+```
+
+## What changes downstream
+
+After migration, planning Step 6.1 reads declared layers instead of guessing:
+
+- **planning** classifies each phase: Tier 0 (no cross-layer delta), Tier 1 (pin `contract.md`, one plan), or Tier 2 (split into producer/consumer plans against a frozen contract).
+- **executing** runs a seam check on Tier-2 phases — merges the layer plans and verifies the producer's emitted shape matches what the consumer built against.
+- **reviewing** folds each phase `contract.md` delta into its governing ADR (`status: absorbed`) at milestone close.
+- `upgrading` continues to protect `.forge/project.yml` and `.forge/contracts/` as user-owned — it will not overwrite your `layers:` field on future upgrades.
+
+A project that stays `layers: []` keeps single-plan decomposition everywhere — the detector is a no-op, exactly as before 0.17.0.
+
+## Rollback
+
+Reversible by `git revert` of the migration commit. Removing the `layers:` field returns planning to the top-level-directory fallback; no other state is affected.

package/template/.forge/templates/state/milestone.yml

@@ -17,17 +17,14 @@ current:
   status: not_started                  # not_started | researching | discussing | planning | executing | verifying | reviewing | complete
   completed_at: null                    # ISO 8601 timestamp — set when status transitions to complete
 
-progress:
-  phases_complete: 0                   # Number of roadmap phases with all tasks done
-  phases_total: 0                      # Total roadmap phases in this milestone
-  current_phase_percent: 0             # Task completion % within the current phase (0-100)
-  overall_percent: 0                   # Task completion % across all phases (0-100)
-  last_update: null                    # ISO 8601 timestamp
-  # NOTE: overall_percent measures TASK completion, not WORKFLOW completion.
-  # A milestone with 100% tasks done still needs verifying, auditing, and refactoring.
-  # The authoritative workflow position is current.status — not this percentage.
-  # Agents: do NOT set overall_percent above 100 or use it to determine if a milestone is "done".
-  # A milestone is only done when current.status == "complete".
+# NO stored progress block. Progress percent is DERIVED on read, never stored.
+# The forge skill computes it from genuinely-maintained signals:
+#   total  = number of phases listed for this milestone in roadmap.yml
+#   done   = current.phase - 1 (phases before the active one), or total when current.status == complete
+#   percent = round(done / total * 100)
+# Storing a percent here drifts — agents reliably advance current.phase/current.status
+# but did not reliably recompute a stored percentage. current.status is authoritative
+# for "is it done?" (only `complete` means done); the derived percent is display-only.
 
 decisions:                             # Locked decisions (synced from context.md)
   - decision: ""