@multileaf/ai-workflow 0.11.0 → 0.13.0

package/docs/opportunities/OPP-018-legacy-migration.md

@@ -0,0 +1,59 @@
+# OPP-018: Supported migration path for legacy installations
+
+- Status: Implemented (2026-11-03): aiw migrate with dry-run/rollback, doctor and install detection, deterministic-floor classification
+- Priority: P1 (field-verified pain; cheapest large-value gap in the backlog)
+- Added: 2026-11-01
+- Decision: extends [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md) Decision A
+- Source signal: **field-verified during inception** — this repository itself ran an ancient (pre-ownership) installation and had to be migrated by hand: install preserves, uninstall refuses (ownership unverifiable), repair ignores, sync demands ownership. A controlled backup → fresh install → selective restore worked but is undiscoverable for a normal user. An external evaluation separately scored provider portability 4/5 citing "variable depth per harness" — migration depth is part of that.
+
+## Problem
+
+Installations created before the ownership inventory (roughly ≤0.9.x) enter a **closed loop** under 0.12+:
+
+- `doctor` reports missing `ownership.yml` and stops;
+- `install` sees existing state and preserves it without rebuilding the inventory;
+- `uninstall` refuses to remove resources it cannot verify ownership of (fail-closed — correct);
+- `sync` refuses to apply plans without the inventory;
+- `repair` does not cover the gap.
+
+Result: the only paths are hand-crafted file surgery (undiscoverable, undocumented) or staying on a broken state. Every user who installed before the inventory is stranded on upgrade.
+
+## Proposal
+
+1. **`aiw migrate`** (with `--dry-run` first): detects legacy state (`manifest.yml`/`lock.yml` present, `ownership.yml` absent) and performs a transactional, rollback-protected migration:
+   - snapshot legacy machine state (`lock.yml`, `recommendations.yml`) into `.aiw/checkpoints/migration-<timestamp>/` for history, but leave the live files in place — their owning commands (`aiw recommend`, `aiw skills install`, `aiw sync`) rewrite them in the modern format;
+   - rebuild the ownership inventory by scanning current AI-Workflow-managed paths and classifying each file: `managed-unchanged` (matches known content), `legacy-user-modified` (preserved as user-owned, listed for manual review), `unknown` (listed as manual action);
+   - preserve byte-identical user configuration (`decision.yml`, `semantic.yml`, `organization.yml`, `heartbeats.yml`, `settings.yml`) and all checkpoints/generated artifacts;
+   - produce a migration report: what was archived, rebuilt, preserved, and what needs manual review.
+2. **Detection and guidance**: `doctor` detects the legacy signature and reports it with the typed continuation `aiw migrate --dry-run`; `install` on legacy state suggests the same (instead of the bare "already installed" message).
+3. **Rollback**: apply writes a rollback checkpoint (the archived originals); `aiw migrate --rollback` restores them atomically — mirroring the target-migration rollback contract (MIG-002).
+4. **Fail-closed on ambiguity**: non-standard files that cannot be classified are listed as manual actions and never silently adopted or deleted.
+
+## Affected areas
+
+- New `src/legacy-migration.ts` (detection, classification, transactional apply, rollback)
+- `src/workflow.ts` (command wiring; doctor legacy detection; install legacy suggestion)
+- `src/ownership.ts` (inventory builder for legacy layouts)
+- Tests with fixture legacy layouts (0.7-era and 0.9-era shapes: no ownership, old lock format, old ai-init skill)
+- `docs/` (migration guide; release-process note that v0.12+ environments also trust `main` for the release chain)
+
+## Acceptance criteria
+
+- Given a 0.7-era layout fixture (no ownership, old lock, old ai-init skill), when `aiw migrate --dry-run` runs, then it lists exactly: archived files, rebuilt files, preserved files, and manual actions — without writing anything.
+- Given `aiw migrate` applied, when `aiw doctor` runs, then health passes; when `aiw sync --dry-run` runs, then it produces a plan (ownership present); and user config files are byte-identical to before.
+- Given migration applied, when `aiw migrate --rollback` runs, then the original legacy state is restored atomically and doctor reports the legacy condition again.
+- Given a fixture with a hand-modified generated rule, when migration runs, then the file is classified `legacy-user-modified`, preserved as user-owned, and listed for manual review — never overwritten.
+- Given ambiguous non-standard files, when migration runs, then it refuses to complete and names them as manual actions (fail-closed).
+- Given an installation already on the modern inventory, when `aiw migrate` runs, then it reports nothing to do and changes nothing.
+
+## Non-goals
+
+- No automatic schema upgrades beyond recreating the base state (schema 1 is forward-compatible; legacy artifacts are archived, not transformed).
+- No adoption of ambiguous files without explicit human action.
+- No deletion of any user data at any point (archival, never removal).
+
+## Open questions
+
+- Version heuristic: absence of `ownership.yml` + presence of `lock.yml` is the signature — is any additional fingerprint needed to distinguish 0.7-era from hand-rolled directories?
+- Should `migrate` offer to re-run `scan`+`recommend` at the end (guided continuation), or stop after the transactional state move?
+- Does the ownership rebuild need to recognize resources from known historical package versions to classify `managed-unchanged` accurately, or is content-hash matching against current bundled resources sufficient?

package/docs/opportunities/README.md

@@ -4,21 +4,43 @@ Improvement opportunities derived from the analysis of Gentle-AI's ODD/RDD metho
 
 The guiding principle: **ceremony should scale with the consequence of the change, not be constant.**
 
-| ID                                                                                              | Opportunity                                                                         | Priority | Depends on                            |
-| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------- |
-| [OPP-001](OPP-001-proportional-ceremony-light-lane.md)                                          | Proportional ceremony — light lane for small, understood work                       | P2       | OPP-002 (advisory signal, optional)   |
-| [OPP-002](OPP-002-risk-assess-command.md)                                                       | `aiw risk assess` — content-based risk classification with exact next command       | P2       | —                                     |
-| [OPP-003](OPP-003-adversarial-review-package.md)                                                | Adversarial review package — blind judges and proof-carrying findings               | P3       | —                                     |
-| [OPP-004](OPP-004-exact-continuation-commands.md)                                               | Exact continuation commands — every block names a runnable way out                  | P1       | —                                     |
-| [OPP-005](OPP-005-friction-benchmark.md)                                                        | Friction benchmark — measure how users get stuck (in-band / out-of-band / dead-end) | P3       | OPP-004                               |
-| [OPP-006](OPP-006-emission-usability-test-policy.md)                                            | Emission ≠ usability — test that named commands actually work                       | P2       | OPP-004 (shared contract)             |
-| [007-decision-findings-triage-scope-watch](OPP-007-decision-findings-triage-scope-watch.md)     | Decision model — findings-evidence triage and lane scope-watch (advisory-only)      | P3       | OPP-001, OPP-003 (integration points) |
-| [008-embedding-covering-tests-judge-context](OPP-008-embedding-covering-tests-judge-context.md) | Embedding retrieval — covering-test detection and judge context scoping             | P3       | OPP-002, OPP-003 (integration points) |
+| ID                                                           | Opportunity                                                                          | Priority | Depends on                              |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------ | -------- | --------------------------------------- |
+| [OPP-001](OPP-001-proportional-ceremony-light-lane.md)       | Proportional ceremony — light lane for small, understood work                        | P2       | OPP-002 (advisory signal, optional)     |
+| [OPP-002](OPP-002-risk-assess-command.md)                    | `aiw risk assess` — content-based risk classification with exact next command        | P2       | —                                       |
+| [OPP-003](OPP-003-adversarial-review-package.md)             | Adversarial review package — blind judges and proof-carrying findings                | P3       | —                                       |
+| [OPP-004](OPP-004-exact-continuation-commands.md)            | Exact continuation commands — every block names a runnable way out                   | P1       | —                                       |
+| [OPP-005](OPP-005-friction-benchmark.md)                     | Friction benchmark — measure how users get stuck (in-band / out-of-band / dead-end)  | P3       | OPP-004                                 |
+| [OPP-006](OPP-006-emission-usability-test-policy.md)         | Emission ≠ usability — test that named commands actually work                        | P2       | OPP-004 (shared contract)               |
+| [OPP-007](OPP-007-decision-findings-triage-scope-watch.md)   | Decision model — findings-evidence triage and lane scope-watch (advisory-only)       | P3       | OPP-001, OPP-003 (integration points)   |
+| [OPP-008](OPP-008-embedding-covering-tests-judge-context.md) | Embedding retrieval — covering-test detection and judge context scoping              | P3       | OPP-002, OPP-003 (integration points)   |
+| [OPP-009](OPP-009-process-entry-points.md)                   | Processes as entry points — bug-fixing and idea assessment alongside SDD             | P2       | OPP-001 (lanes), OPP-004 (reason codes) |
+| [OPP-010](OPP-010-orchestration-worktree-isolation.md)       | Worktree isolation for orchestrated execution                                        | P2       | orchestration (ENT-007)                 |
+| [OPP-011](OPP-011-evals-redteam-generated-artifacts.md)      | Evals + red-team layer for generated artifacts                                       | P3       | OPP-006 (ratchet)                       |
+| [OPP-012](OPP-012-standards-discovery.md)                    | Standards discovery — codebase conventions into versioned standards                  | P3       | OPP-008 (retrieval)                     |
+| [OPP-013](OPP-013-read-optimized-artifacts-digest-layer.md)  | Read-Optimized Artifacts — fingerprint-bound digest layer for downstream reads       | P1       | OPP-004 (typed blocks), CTX-002/004     |
+| [OPP-014](OPP-014-paired-verification-contract.md)           | Paired Verification Contract — expected vs observed, mechanically compared           | P2       | OPP-004 (reason codes)                  |
+| [OPP-015](OPP-015-token-recovery-governance.md)              | Token & Recovery Governance — enforced budgets, recovery block, advisory suggestions | P2       | CTX-004, OPP-002 (advisory signal)      |
+| [OPP-016](OPP-016-behavioral-eval-scenarios.md)              | Behavioral evaluation phase 2 — scenario registry replayed against real harness CLIs | P2       | OPP-011 (deterministic floor)           |
+| [OPP-017](OPP-017-orchestration-depth.md)                    | Orchestration depth — integration forecast, leak reporting, honor matrix             | P2       | OPP-010 (isolation)                     |
+| [OPP-018](OPP-018-legacy-migration.md)                       | Supported migration path for legacy installations                                    | P1       | — (field-verified pain)                 |
 
 Suggested starting order: **OPP-004 → OPP-002 → OPP-006 → OPP-001 → OPP-005 → OPP-003** (smallest/least invasive first; OPP-004's reason codes feed OPP-005 and OPP-006).
 
 OPP-007 and OPP-008 are **model-integration addenda**: deliberately left for after field exposure — their priority should be set by real usage pain, not speculation. All model features respect the spec's NFR contracts: deterministic floor first, models advisory-only, unconfigured = byte-identical offline behavior.
 
+## Trend-sourced addendum (2026-11)
+
+OPP-009 through OPP-012 derive from a November 2026 landscape scan (spec-kit 145K★ shipping independent entry points; Spec Kitty / Conductor normalizing isolated-worktree parallel agents; promptfoo 26K★ establishing artifact evals; Agent OS 5.5K★ on standards discovery). The scan also **validated** the existing positioning: spec-driven development and human-in-the-loop governance are growing markets where AI Workflow's evidence ledger is the differentiator. Deliberately not chased: generic memory layers (audit-first philosophy), cloud-agent infrastructure (harness territory), commercial AI-review feature parity.
+
+### Evaluation-sourced addendum (OPP-016..018)
+
+An external qualitative assessment (Nov 2026) scored the release: specification-driven engineering, token governance, and workflow governance at 5/5; multi-agent orchestration and behavioral evaluation at 3/5; provider portability 4/5. The scores match the internal read — the 5s are the differentiators, the 3s are the frontier. OPP-016 (behavioral scenarios against real harness CLIs), OPP-017 (orchestration integration forecast, leak reporting, honor matrix) and OPP-018 (supported legacy migration, field-verified pain during inception) are the levers on those scores. The assessment also missed two documented strengths: the honest threat-model boundary and the friction benchmark as a quality instrument.
+
+### Token-analysis addendum (OPP-013..015)
+
+Measured on this repository's own full-lane artifacts (~2.2K-token specification, ~4.1K-token plan): downstream re-reads cost ~25-30K tokens per feature — roughly 80% of an artifact's lifetime token cost is re-reading, not writing. OPP-013 (digests), OPP-014 (paired verification) and OPP-015 (governance) attack that multiplier and make observed proof mechanically checkable, synthesizing the shared insight across spec-kit, ODD and HDAE: the full artifact is for humans; agents need a derived, verifiable view.
+
 ## Planning
 
 The implementation is planned as six waves in the project's own SDD format:

package/docs/release-process.md

@@ -8,7 +8,7 @@ AI Workflow releases are reproducible, evidence-backed, and published only from
 2. A maintainer reviews and merges the pull request into `main`.
 3. The `Auto-tag releases` workflow notices that the merged version has no `v<version>` tag yet, creates the tag on the merge commit, and the `Release` workflow takes over: it validates the tagged source and publishes with npm trusted publishing and provenance.
 
-No manual tagging and no environment approvals: merging an reviewed pull request with a version bump is the entire release action. Merges that do not bump the version are ignored by the auto-tag workflow.
+No manual tagging and no environment approvals: merging an reviewed pull request with a version bump is the entire release action. Since 0.11.0 the Auto-tag workflow invokes the Release workflow directly (reusable-workflow call) — tags created through the API with the default `GITHUB_TOKEN` do not trigger other workflows — and the `npm` environment's deployment policy trusts both `v*.*.*` tags and `main` for that call chain. Merges that do not bump the version are ignored by the auto-tag workflow.
 
 ## Preconditions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {

package/resources/skills/implementation-planning.md

@@ -7,6 +7,6 @@ description: Break an approved design into independently verifiable implementati
 
 For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
 
-Create small ordered tasks. Each task must reference requirements, affected modules, tests, commands, dependencies, and completion evidence.
+Create small ordered tasks. Each task must reference requirements, affected modules, tests, commands, dependencies, and completion evidence. Each task that touches existing behavior declares a regression line (`Regression: <behavior> → <test>`) pinning a test that proves the previous behavior still holds; `aiw verify` reports tasks missing it as advisory.
 
 Write `.aiw/generated/plans/implementation-plan.md` with ordered tasks, requirement links, affected modules, tests, validation, dependencies, risks, and completion evidence. After `aiw gate plan` passes, present the exact plan to the human and ask for explicit approval. Stop and wait; a gate pass is not approval. Do not edit implementation files until approval arrives and `aiw approve plan` succeeds. If changes are requested, first record `aiw reject plan --reason=<feedback>`, then revise the plan, rerun its gate, and ask again. After approval, implement in task order. Use `tdd-development` when installed and the project has a test workflow; otherwise use existing validation. When implementation is complete, write `.aiw/generated/reports/implementation-report.md` with changed files, tests, validation results, and deviations; run `aiw gate implementation`, present the diff and evidence to the human, stop, and wait for explicit approval. Record approval with `aiw approve implementation` before verification. Invoke CLI commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/templates/brainstorm.md

@@ -13,4 +13,3 @@
 ## Non-goals
 
 ## Open Questions
-

package/resources/templates/decision-record.md

@@ -9,4 +9,3 @@
 ## Rationale
 
 ## Consequences
-

package/resources/templates/implementation-evidence.md

@@ -10,7 +10,7 @@
 
 ## Validation
 
-- Command and result for required project checks.
+One observed line per plan declaration: `Validation: <command> → <observed>` (for example `npm test → exit 0 (132 passed)`).
 
 ## Deviations
 

package/resources/templates/implementation-plan.md

@@ -8,5 +8,6 @@
 
 ## Validation Commands
 
-## Evidence
+Per task: `Validation: <command> → <expected>` (for example `npm test → exit 0`). Gates compare these declarations against the recorded observed results.
 
+## Evidence

package/resources/templates/migration-report.md

@@ -11,4 +11,3 @@
 ## Conflicts
 
 ## Rollback Plan
-

package/resources/templates/security-review.md

@@ -11,4 +11,3 @@
 ## Remediation
 
 ## Decision
-

package/resources/templates/task.md

@@ -11,4 +11,3 @@
 ## Tests First
 
 ## Completion Criteria
-

package/resources/templates/technical-design.md

@@ -11,4 +11,3 @@
 ## Risks
 
 ## Validation
-

package/resources/templates/test-plan.md

@@ -9,4 +9,3 @@
 ## Failure Cases
 
 ## Evidence
-

package/resources/templates/verification-report.md

@@ -4,9 +4,10 @@
 
 ## Checks Passed
 
+One observed line per plan declaration: `Validation: <command> → <observed>`.
+
 ## Missing Evidence
 
 ## Residual Risks
 
 ## Decision
-