@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/plans/workflow-source-setup-phase-2.md

@@ -0,0 +1,361 @@
+# Workflow Source Setup Phase 2
+
+This is the **canonical durable plan/design doc** for the next workflow-source setup phase after rooted-sharing phase 1.
+
+Use it for:
+
+- the recommended **phase 2A / phase 2B** boundary
+- the canonical **effective source catalog** direction
+- the intended onboarding model for repo/folder-driven setup
+- migration stance for env-first and legacy live/runtime-configured sources
+- the trust, conflict, and explainability guardrails that should constrain implementation
+
+Do **not** use this doc as a code-shadow full of exact APIs, file layouts, or ticket-level implementation slices. Those should come later in tickets, code, and tests.
+
+## Goal
+
+Make broader workflow hookup feel like a coherent WorkRail product surface without losing the trust model established in phase 1.
+
+Phase 2 should make it easier for a user to:
+
+- connect a repo or folder without env-first setup
+- inspect all effective workflow sources in one coherent model
+- understand whether a source is rooted, installed, legacy, or external
+- understand the trust, conflict, and migration implications of onboarding a source
+
+## Why phase 2 exists
+
+Phase 1 established the trust and visibility baseline for rooted team sharing:
+
+- explicit `workspacePath`
+- remembered roots
+- recursive rooted discovery
+- source-aware visibility
+- migration-aware precedence explanation
+
+That solved the common team-sharing path, but it did **not** yet provide:
+
+- a canonical control surface for all effective workflow sources
+- a WorkRail-owned onboarding path for repo/folder-style source hookup
+- a coherent migration layer for env-first configuration
+
+Phase 2 exists to add those capabilities without regressing explainability.
+
+## Core phase-2 stance
+
+Phase 2 should **not** be framed as “add an install wizard.”
+
+It is better understood as:
+
+- a **canonical effective source catalog**
+- plus **managed onboarding** for a narrow set of common intents
+- while preserving compatibility with current runtime source heterogeneity during migration
+
+This is a control-layer expansion, not an immediate runtime rewrite.
+
+## Phase-2 structure
+
+### Phase 2A — Catalog + onboarding foundation
+
+Phase 2A is the first credible slice of phase 2.
+
+It should:
+
+- define the **canonical effective source catalog**
+- introduce **managed source entries** for explicit install/connect actions
+- add narrow onboarding for common intents
+- make legacy/env-first sources visible and migration-targetable
+- require trust review and conflict rehearsal before enabling new managed sources
+
+### Phase 2B — Lifecycle and breadth expansion
+
+Phase 2B follows after the 2A foundation is stable.
+
+It should expand into:
+
+- richer update and sync flows
+- clearer health, revision, and last-sync reporting
+- receipts / setup transcripts / stronger observability
+- broader source-type onboarding such as registries, plugins, or community packaging
+- richer console/control-tower integration
+
+## Canonical phase-2 model
+
+### Effective source catalog
+
+The **effective source catalog** is the canonical inspectable model of what sources effectively exist right now and how they relate.
+
+It should answer, at minimum:
+
+- what the source is
+- where it came from
+- what scope it affects
+- what mode it is in
+- whether it is preferred, legacy, or overlapping another source
+- what trust/conflict/migration implications apply
+
+The catalog is a **truth surface**, not necessarily the persistence format.
+
+### Internal entry families
+
+The preferred internal model is hybrid:
+
+#### Derived effective entries
+
+These exist because WorkRail can currently observe or derive them from existing behavior:
+
+- built-in workflows
+- user-library workflows
+- rooted-sharing sources discovered from remembered roots
+- legacy project `./workflows`
+- env-configured live/runtime-configured sources
+
+These should be visible in the catalog even if WorkRail did not explicitly create them.
+
+#### Managed source entries
+
+These exist because WorkRail explicitly attached, installed, or connected them.
+
+They are the right place for durable metadata such as:
+
+- selected mode
+- origin
+- revision or branch intent
+- trust/review result
+- migration target state
+
+Users should not need to think in terms of “derived” versus “managed,” but this distinction is useful internally and in the planning model.
+
+## User-facing phase-2 language
+
+The product should prefer user intents over raw source-kind jargon.
+
+The early onboarding surface should be shaped around intents like:
+
+- `use folder`
+- `use repo`
+- `share repo workflows`
+
+This is better than forcing the user to choose directly among `custom`, `git`, `remote`, or `plugin` semantics.
+
+## Phase-2A onboarding scope
+
+### In scope for onboarding
+
+Phase 2A should focus on **repo/folder-first** onboarding.
+
+That means:
+
+- local folder onboarding
+- local repo onboarding
+- remote repo onboarding
+- rooted-sharing continuity for repo-local `.workrail/workflows/`
+
+### Out of scope for onboarding
+
+Phase 2A should **not** try to support every source kind equally from day one.
+
+Explicitly defer:
+
+- broad registry onboarding
+- broad plugin onboarding
+- community/package distribution breadth
+- richer import flows for archives/chat/shared artifacts
+
+Those belong later, once the catalog and onboarding foundation are proven.
+
+## Remote-source stance
+
+### Default for new onboarding
+
+For **new remote onboarding**, the default should be:
+
+- **managed local sync**
+
+That means:
+
+- the remote repo is the acquisition/update source
+- WorkRail operates over a local effective copy for discovery, validation, and explainability
+
+### Why this is the default
+
+This default:
+
+- preserves a local effective state that is easier to inspect and debug
+- supports a stronger provenance and update story
+- avoids forcing users to think in low-level Git/storage modes
+- aligns with the design-thinking direction around managed sync
+
+### Important constraint
+
+Managed local sync should be treated as the **default for new onboarding**, not as an immediate semantic rewrite of every existing remote/live source.
+
+Legacy live/runtime-configured sources should remain:
+
+- supported during migration
+- visible in the catalog
+- explainable as legacy or advanced paths
+
+### Other remote modes
+
+The long-term model may also include:
+
+- **pinned snapshot**
+  - stronger reproducibility, lower-trust, or explicit-update scenarios
+- **live remote**
+  - if retained, advanced-only and not the preferred onboarding path
+
+Phase 2A does not need to finalize the long-term fate of live remote mode to be useful.
+
+## Migration stance
+
+Phase 2 must coexist with current configuration reality instead of pretending it is already gone.
+
+The product and docs should continue to acknowledge:
+
+- `./workflows`
+- `~/.workrail/workflows`
+- rooted-sharing via remembered roots
+- env-configured custom paths
+- env-configured Git repositories
+- env-configured remote registries
+- env-configured plugin-style sources
+
+### Legacy visibility
+
+Env-first and other legacy-configured sources should appear in the catalog as **legacy-effective** or equivalent user-facing categories.
+
+### Migration proposals
+
+Visibility alone is not enough.
+
+Phase 2A should include **basic migration proposals / change plans** such as:
+
+- this source is currently env-configured
+- this is the recommended preferred path
+- this is the target mode WorkRail recommends
+- this is the overlap/conflict implication if you enable it
+
+This does **not** require full migration automation in 2A, but it should make the path forward explicit.
+
+## Trust and conflict requirements
+
+### Trust review
+
+Phase 2A should require a lightweight explicit trust/review summary before enabling third-party or external managed sources.
+
+At minimum, that summary should make clear:
+
+- origin
+- scope
+- selected mode
+- any auth implication
+- any important portability warning
+
+### Conflict rehearsal
+
+Before attaching or enabling a source, WorkRail should perform a preflight-style conflict rehearsal that can surface:
+
+- shadowing / precedence effects
+- workflow ID conflicts
+- bundled-protection implications
+- obvious portability or compatibility concerns
+
+This is part of making the onboarding path trustworthy rather than surprising.
+
+## Config and persistence stance
+
+### What is decided now
+
+- Phase 2A should avoid overloading `.workrail/config.json` prematurely.
+- The effective catalog does **not** have to be the same as the persistence format.
+- Managed-source durability can be designed separately from the catalog surface.
+
+### What this implies
+
+Phase 2A can plausibly use a dedicated WorkRail durable-state pattern for managed source records without first resolving every long-term `.workrail/*` ownership question.
+
+### What is still intentionally unresolved
+
+- exact managed-source record schema
+- exact storage/layout path
+- final ownership split between user-global config, repo-local metadata, and durable managed-source state
+
+The implementation should preserve flexibility here rather than baking in a premature single-file assumption.
+
+## Acceptance criteria
+
+Phase 2A is successful when all of the following are true:
+
+### User-facing outcomes
+
+- A user can connect a repo or folder without falling back to raw env-first setup.
+- A user can inspect all effective sources in one coherent model.
+- A user can understand whether a source is rooted, legacy, managed, or external without reading implementation details.
+- A user can understand trust/conflict implications before enabling a managed source.
+- A user can see a migration path for legacy/env-first sources.
+
+### Product/design outcomes
+
+- The effective source catalog is canonical for inspection.
+- Managed onboarding exists for repo/folder-first intents.
+- Conflict rehearsal exists before enable/attach.
+- Lightweight trust/review exists before enabling external managed sources.
+- Legacy live/env-configured sources remain visible and supported during migration.
+
+### Maintenance outcomes
+
+- Another maintainer can use this doc as the durable phase-2 reference without replaying the exploration.
+- Future ticketing can proceed without reopening the entire option space.
+- The doc preserves clear boundaries between 2A, 2B, and later phases.
+
+## Non-goals for phase 2A
+
+Phase 2A is **not**:
+
+- a full source-lifecycle platform
+- a richer console control tower
+- a full registry/plugin/community onboarding rollout
+- a complete runtime-source redesign
+- the final answer to every `.workrail/*` ownership question
+- a full receipt/history/transcript system
+
+Those may follow in 2B or later phases, but they are not required for 2A to be useful and coherent.
+
+## Risks to guard against
+
+- **Wizard over chaos**: guided onboarding without a real canonical catalog
+- **Another hybrid setup story**: old and new source paths coexist without a coherent catalog view
+- **Hidden runtime rewrite**: phase 2A quietly changes source semantics instead of productizing them safely
+- **Config overload**: phase 2A pushes too much state into `.workrail/config.json` too early
+- **Migration theater**: legacy sources are labeled but not meaningfully guided toward a better path
+- **Invisible conflicts**: onboarding enables sources without clear rehearsal of overlap or precedence
+
+## Remaining design decisions
+
+These are still important, but now belong inside the chosen direction rather than blocking it:
+
+- exact minimal managed-source record schema
+- exact storage/layout recommendation for those records
+- whether any repo-local metadata artifact is worth adding in 2A
+- long-term role of explicit live remote mount
+
+## Recommended next planning step
+
+If this phase-2 direction is accepted, the next high-value artifact should be a more focused **phase-2A design / execution plan** that refines:
+
+- catalog entry shape
+- managed-source record shape
+- conflict-review / trust-review surface
+- migration-proposal surface
+
+before ticket creation begins.
+
+## Companion docs
+
+- `docs/plans/workflow-source-setup-phase-1.md`
+- `docs/plans/workrail-platform-vision.md`
+- `docs/ideas/third-party-workflow-setup-design-thinking.md`
+- `docs/configuration.md`
+
+`workflow-source-setup-phase-1.md` remains the canonical reference for phase 1. This file is the preferred durable reference for the **next** phase of the initiative.

package/docs/plans/workflow-staleness-detection-candidates.md

@@ -0,0 +1,104 @@
+# Workflow Staleness Detection — Design Candidates
+
+## Problem Understanding
+
+**Tensions:**
+1. Explicit stamp vs inferred signal — stamps are precise but require migration; git-date inference works immediately but isn't deterministic
+2. Noise vs sensitivity — low threshold creates flag fatigue; high threshold misses real staleness
+3. Where staleness lives — in the workflow file vs computed by the engine vs in a separate manifest
+4. Agent-side vs user-side surfacing — same signal, different presentation contracts
+
+**Likely seam:** `V2WorkflowListItemSchema` in `src/mcp/output-schemas.ts` — add a `staleness` field here. The computation feeds from either a stamp in the workflow JSON or a git-date comparison.
+
+**What makes it hard:** Bootstrapping. The right long-term signal requires stamps that don't exist on any current workflow. Any solution must degrade gracefully for unstamped workflows without producing permanent noise.
+
+## Philosophy Constraints
+
+- **Determinism over cleverness** — git-date comparison is not deterministic (CI can retouch files). Spec-version stamp is deterministic.
+- **Make illegal states unrepresentable** — `staleness: boolean` is wrong. `staleness: { level: 'none' | 'possible' | 'likely', reason: string, specVersionAtLastReview?: number }` is correct.
+- **Explicit domain types** — the staleness level is a meaningful enum, not a string.
+- **Architectural fixes over patches** — the stamp is the fix; git-date inference is a patch.
+
+## Impact Surface
+
+- `spec/workflow.schema.json` — new optional field
+- `workflow-for-workflows.v2.json` — new stamp step in Phase 7
+- `src/mcp/output-schemas.ts` — new field in `V2WorkflowListItemSchema` and `V2WorkflowInspectOutputSchema`
+- `src/mcp/handlers/v2-workflow.ts` — staleness computation at list/inspect time
+- Console workflow list — new staleness indicator (follow `migration`/`staleRoots` visual pattern)
+- `spec/authoring-spec.json` — the source of truth for current spec version (currently `version: 3`)
+
+## Candidates
+
+### Candidate A: Engine-computed staleness from spec git-date
+
+**Summary:** At `list_workflows` time, compare `git log -1 %at` for `spec/authoring-spec.json` vs the workflow file. If spec is newer, surface `staleness: { level: 'possible', reason: 'Authoring spec updated since workflow was last committed' }`.
+
+- **Tensions resolved:** works on all existing workflows immediately, zero migration
+- **Tensions accepted:** not deterministic, can't distinguish meaningful spec change from typo fix, no way to clear except committing the workflow file
+- **Boundary:** `v2-workflow.ts` + `V2WorkflowListItemSchema` only
+- **Failure mode:** CI pipeline touches `authoring-spec.json` during a release, flagging every workflow simultaneously
+- **Repo pattern:** follows `staleRoots` pattern — computed at list time
+- **Gains:** zero migration, immediate coverage
+- **Losses:** precision, determinism, actionable reason string
+- **Scope:** best-fit for a temporary bridge, too narrow as a final solution
+- **Philosophy:** honors YAGNI; conflicts with Determinism
+
+---
+
+### Candidate B: Spec-version stamp in workflow JSON ✓ RECOMMENDED
+
+**Summary:** Add optional `validatedAgainstSpecVersion: number` to the workflow JSON schema. `workflow-for-workflows` stamps this in Phase 7. Engine reads the field and compares against `spec/authoring-spec.json` version. Three-tier signal: `none` (stamp matches current), `likely` (stamp < current), `possible` (no stamp).
+
+- **Tensions resolved:** deterministic, precise three-tier signal, actionable reason string, running workflow-for-workflows naturally clears the flag
+- **Tensions accepted:** bootstrapping — existing workflows start as `possible` until reviewed
+- **Boundary:** schema + workflow-for-workflows + output-schemas + handler
+- **Failure mode:** teams run workflow-for-workflows locally but forget to commit the JSON
+- **Repo pattern:** adapts `workflowHash` pattern (content-derived identity) to spec-version identity
+- **Gains:** deterministic, self-documenting, architectural fix, clears naturally with workflow-for-workflows
+- **Losses:** migration cost (organic, not forced), adds schema field most workflows won't have immediately
+- **Scope:** best-fit long-term
+- **Philosophy:** honors Determinism, Make illegal states unrepresentable, Explicit domain types. Minor YAGNI tension.
+
+**Implementation steps:**
+1. `spec/workflow.schema.json`: add `validatedAgainstSpecVersion?: number` (optional, no existing workflow breaks)
+2. `workflow-for-workflows.v2.json`: Phase 7 stamps `validatedAgainstSpecVersion` to current spec version before handoff
+3. `src/mcp/output-schemas.ts`: add `staleness?: { level: 'none' | 'possible' | 'likely', reason: string, specVersionAtLastReview?: number }` to `V2WorkflowListItemSchema` and `V2WorkflowInspectOutputSchema`
+4. `src/mcp/handlers/v2-workflow.ts`: read `validatedAgainstSpecVersion` from compiled workflow; compare against `spec/authoring-spec.json` version; compute staleness
+5. Console: show staleness indicator in workflow list
+6. `spec/authoring-spec.json`: keep `version` field updated when meaningful rules change
+
+---
+
+### Candidate C: Hybrid — stamp when available, git-date fallback
+
+**Summary:** Use stamp-based comparison when `validatedAgainstSpecVersion` is present; fall back to git-date comparison for unstamped workflows.
+
+- **Tensions resolved:** zero migration + precision where stamps exist
+- **Tensions accepted:** git-date fallback inherits A's determinism problem; two code paths
+- **Failure mode:** `possible` from the fallback becomes permanent wallpaper for workflows never run through workflow-for-workflows
+- **Scope:** slightly too broad for a first version, correct long-term shape
+- **Philosophy:** deterministic where stamps exist; conflicts with Determinism in the fallback path
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate B**
+
+The stamp is the architecturally correct fix. It's deterministic, self-documenting, and cleared by the existing workflow-for-workflows tool. The bootstrap problem is real but manageable: unstamped workflows show `possible` (not `likely`), and teams clear it organically by running workflow-for-workflows. No mass migration needed.
+
+**Why A loses:** The CI-noise failure mode is hard to avoid and produces permanent noise. No actionable reason string.
+
+**Why C loses:** The hybrid adds complexity, and the git-date fallback is still the same wallpaper problem — just deferred. The right approach is to accept the bootstrap cost of B and let organic adoption clear it.
+
+## Self-Critique
+
+**Strongest counter-argument:** Spec version is too coarse — v3 may have added rules that don't apply to a given workflow's archetype, making `likely stale` misleading. Mitigation: add a `changedRules` summary to the reason string when the spec version changes.
+
+**Pivot condition:** If teams rarely run workflow-for-workflows and `possible` becomes permanent noise for 80%+ of workflows, add a CI step that reads the spec version and stamps workflows automatically (no human needed, just a `git commit --amend` or separate commit in CI).
+
+## Open Questions for Main Agent
+
+1. Should `workflow-for-workflows` stamp before or after the quality gate loop? (After seems right — only stamp if the workflow passes.)
+2. Should `validatedAgainstSpecVersion` be a required field for new workflows going forward, or permanently optional?
+3. Does the console need a new visual treatment, or can it reuse the `migration` badge pattern that already exists?
+4. Should `inspect_workflow` in `metadata` mode also return the staleness field, or only in `preview` mode?

package/docs/plans/workflow-staleness-detection-review.md

@@ -0,0 +1,58 @@
+# Workflow Staleness Detection — Design Review Findings
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Hidden Assumption | Fails If |
+|---|---|---|---|
+| Bootstrap: existing workflows show `possible` | Acceptable | Teams will eventually run workflow-for-workflows on important workflows | `possible` shown as equally urgent as `likely` |
+| External workflows never get stamped | Acceptable | Stamp is optional, no workflow breaks | Same as above |
+| Spec granularity: one update flags all workflows | Acceptable with mitigation | Spec has a changelog per version increment | Spec version bumps silently with no explanation |
+
+**T3 reveals a required companion piece: the authoring spec needs a per-version changelog.** Not a blocker, but must ship alongside the staleness feature to keep the reason string actionable.
+
+## Failure Mode Review
+
+| Failure Mode | Risk | Coverage | Missing Mitigation |
+|---|---|---|---|
+| Spec version not bumped when rules change | **High** | Not in code — process fix needed | Add explicit trigger to `authoring-spec.json` `changeProtocol` |
+| Stamp committed locally but not pushed | Medium | Phase 7 handoff note needed | Note in workflow-for-workflows Phase 7: "stamp must be committed" |
+| `possible` becomes wallpaper | Medium | Three-tier design helps | Ensure `possible` and `likely` are visually distinct in console |
+
+**Highest-risk failure mode: spec version not bumped.** This would make the entire system unreliable. Process fix required.
+
+## Runner-Up / Simpler Alternative Review
+
+- Candidate A (git-date): nothing worth borrowing. CI-noise failure mode is disqualifying.
+- Simpler variant (embed spec in version string): rejected — conflates human-maintained semver with compliance state.
+- Sidecar file stamp: rejected — state would drift from the workflow file, violating determinism.
+
+**Conclusion:** Candidate B as designed is already the minimal correct shape.
+
+## Philosophy Alignment
+
+- **Satisfied:** Determinism, Make illegal states unrepresentable, Explicit domain types, Validate at boundaries, Errors are data
+- **Acceptable tensions:** YAGNI (optional field on existing workflows), Architectural fixes over patches (graceful `possible` degradation)
+- **No risky tensions**
+
+## Findings
+
+**Orange — Spec version bump process undefined**
+`authoring-spec.json` `changeProtocol` has no explicit trigger for incrementing `version`. If this isn't defined before the staleness feature ships, the `validatedAgainstSpecVersion` comparison is unreliable in either direction. Must be fixed.
+
+**Yellow — No per-version changelog in authoring spec**
+The `reason` string in the staleness output must reference what changed between spec versions for the signal to be actionable. Currently there's no changelog. Must be added when version increments.
+
+**Yellow — workflow-for-workflows Phase 7 doesn't mention the stamp**
+The Phase 7 handoff step should explicitly tell the agent: "the `validatedAgainstSpecVersion` stamp was written to the workflow file — commit it for the staleness signal to take effect." Without this, teams may miss it.
+
+## Recommended Revisions
+
+1. Add to `authoring-spec.json` `changeProtocol`: "Increment `version` when any required-level rule is added, removed, or materially changed. Add a `changelog` entry for the new version."
+2. Add `changelog` array to `authoring-spec.json` schema structure — each entry: `{ version, date, summary, affectedRules }`.
+3. Add stamp reminder to workflow-for-workflows Phase 7 handoff step.
+4. Ensure console renders `likely` more prominently than `possible` (not just two shades of the same badge).
+
+## Residual Concerns
+
+- Routine changes (workflows delegating to routines that were updated) are not tracked by spec version. Accepted as out of scope for v1.
+- If the spec version doesn't increment often (historically it's been at v3 for a while), the `likely` tier may rarely appear. That's okay — it means most workflows will be `none` or `possible`, which is the right coarse signal.

package/docs/plans/workflow-staleness-detection.md

@@ -0,0 +1,80 @@
+# Workflow Staleness Detection
+
+## Context / Ask
+
+How to automatically detect when a WorkRail workflow has become stale — out of sync with the authoring spec, schema, or routines it depends on — and surface this transparently to both users (UI/console) and agents (MCP tools).
+
+## Recommendation: Spec-Version Stamp (Candidate B)
+
+**Confidence: High.** Grounded in codebase evidence, adversarially challenged, design-reviewed. No direction changes required.
+
+### How it works
+
+1. `spec/authoring-spec.json` has a `version` field (currently `3`). This is the staleness anchor.
+2. `workflow-for-workflows` stamps `validatedAgainstSpecVersion: <N>` into the workflow JSON at Phase 7 handoff (after the quality gate passes).
+3. At `list_workflows` and `inspect_workflow` time, the engine reads the stamp and compares it against the current spec version.
+4. The output schema gains a `staleness` field: `{ level: 'none' | 'possible' | 'likely', reason: string, specVersionAtLastReview?: number }`.
+
+### Three-tier signal
+
+| Level | Condition | Meaning |
+|---|---|---|
+| `none` | `validatedAgainstSpecVersion` matches current spec version | Workflow was reviewed against current guidance |
+| `likely` | `validatedAgainstSpecVersion` < current spec version | Spec updated since last review — workflow may need attention |
+| `possible` | No stamp present | Workflow was not created/reviewed via workflow-for-workflows |
+
+### Surfacing
+
+- **Agents**: `staleness` field in `list_workflows` and `inspect_workflow` MCP output. Agents can warn users before starting a workflow.
+- **Users**: staleness indicator in console workflow list. `likely` should be visually more prominent than `possible`. Follow the existing `migration`/`staleRoots` visual pattern.
+
+### What clears the flag
+
+Running `workflow-for-workflows` on the workflow and committing the result. The Phase 7 step stamps the current spec version. No other action required.
+
+## Implementation Scope
+
+| File | Change |
+|---|---|
+| `spec/workflow.schema.json` | Add optional `validatedAgainstSpecVersion?: number` field |
+| `spec/authoring-spec.json` | Add explicit bump trigger to `changeProtocol`; add `changelog` array |
+| `workflow-for-workflows.v2.json` | Phase 7: stamp `validatedAgainstSpecVersion` after quality gate passes; note stamp must be committed |
+| `src/mcp/output-schemas.ts` | Add `staleness?` to `V2WorkflowListItemSchema` and `V2WorkflowInspectOutputSchema` |
+| `src/mcp/handlers/v2-workflow.ts` | Compute staleness from stamp vs current spec version at list/inspect time |
+| Console | Staleness indicator in workflow list; `likely` > `possible` visual hierarchy |
+
+## Constraints / Anti-goals
+
+- Must not block workflow execution
+- Must not require per-workflow manual maintenance
+- No auto-fixing (that's workflow-for-workflows territory)
+- No mass migration — bootstrap via organic adoption
+
+## Required Companion Changes (must ship with the feature)
+
+1. **`authoring-spec.json` `changeProtocol`**: add "Increment `version` when any required-level rule is added, removed, or materially changed."
+2. **`authoring-spec.json` `changelog`**: add a `changelog` array so the `reason` string in staleness output can reference what changed.
+3. **`workflow-for-workflows` Phase 7**: add note — "The `validatedAgainstSpecVersion` field was written to the workflow file — commit it for the staleness signal to take effect."
+
+## Accepted Tradeoffs
+
+- Existing unstamped workflows show `possible` permanently until reviewed — acceptable, `possible` is the correct coarse signal for unreviewed workflows
+- External workflows not using workflow-for-workflows may never get stamped — acceptable, same reason
+- Spec version granularity: a spec update touching one archetype flags all workflows — mitigated by changelog + specific reason string
+
+## Residual Risks
+
+- If spec version is not bumped when meaningful rules change (no clear owner), the `likely` signal never fires. Mitigated by adding explicit trigger to `changeProtocol`.
+- Routine changes (delegation to updated routines) not tracked by spec version. Out of scope for v1.
+
+## Switch Trigger
+
+If teams rarely run workflow-for-workflows and `possible` becomes permanent noise for 80%+ of workflows, add a CI step that stamps workflows automatically.
+
+## Decision Log
+
+- **Candidate A (git-date inference) rejected**: CI-noise failure mode disqualifying; no actionable reason string; not deterministic.
+- **Candidate C (hybrid) rejected**: complexity; git-date fallback inherits A's wallpaper problem.
+- **Candidate B selected**: deterministic, architectural fix, self-clearing via workflow-for-workflows, follows `workflowHash` pattern.
+- **Challenge**: spec version too coarse. Mitigated by changelog + reason string. Position held.
+- **Review**: no direction change. Three companion changes required pre-ship.

package/docs/plans/workflow-v2-design.md

@@ -0,0 +1,69 @@
+# Workflow v2 Design
+
+This is the **canonical durable design doc** for WorkRail v2.
+
+Use it for:
+
+- durable architectural intent
+- invariants that should remain true over time
+- the high-level reasoning behind the v2 model
+
+Do **not** use this doc as a chat-resumption script or a line-by-line implementation cookbook.
+
+## North star
+
+Make agent-driven workflows **deterministic and rewind-safe** while keeping the WorkRail tool surface small, durable, and hard to misuse.
+
+## Durable design principles
+
+### Token-based execution boundary
+
+Agents should never assemble engine internals. The MCP boundary should expose opaque tokens and explicit intents instead.
+
+### Append-only truth
+
+Execution truth should be append-only, with sessions/runs/dashboard views derived from projections.
+
+### Pinned determinism
+
+Runs should be pinned to the fully expanded compiled workflow snapshot so replay/resume behavior stays stable.
+
+### Recovery without transcript dependence
+
+WorkRail should not depend on the chat transcript for correctness. Recovery context should come from durable execution truth.
+
+### Closed, typed execution semantics
+
+Preferences, contracts, and other workflow-shaping primitives should prefer closed sets and explicit semantics over loose bags of data.
+
+## Important consequences
+
+### Rewinds are an engine concern
+
+Rewinds should branch safely rather than pushing structural recovery onto the user or agent.
+
+### Preferences are product semantics, not arbitrary metadata
+
+Execution preferences should be WorkRail-defined and durable, not an unbounded preference bag.
+
+### Authoring power should stay deterministic
+
+Templates, features, contracts, and related authoring primitives should remain auditable and deterministic, not become ad hoc runtime magic.
+
+### Failure visibility matters
+
+The system should prefer explicit blocked/error paths and durable recovery over silent degradation.
+
+## Canonical references
+
+- `docs/reference/workflow-execution-contract.md`
+- `docs/reference/mcp-platform-constraints.md`
+- `docs/adrs/005-agent-first-workflow-execution-tokens.md`
+- `docs/adrs/006-append-only-session-run-event-log.md`
+- `docs/adrs/007-resume-and-checkpoint-only-sessions.md`
+- `docs/design/v2-core-design-locks.md`
+
+## Companion docs
+
+- `docs/plans/workflow-v2-roadmap.md`
+- `docs/plans/v2-followup-enhancements.md`