@event4u/agent-config 1.14.0 → 1.15.0

package/AGENTS.md

@@ -1,5 +1,7 @@
 # event4u/agent-config
 
+> **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
+
 **Shared agent configuration** — skills, rules, commands, guidelines, and templates
 for AI coding tools (Augment Code, Claude Code, Cursor, Cline, Windsurf, Gemini CLI,
 GitHub Copilot).
@@ -66,7 +68,7 @@ want to measure which skills/rules/commands the agent actually applies set
 `telemetry.artifact_engagement.enabled: true` in `.agent-settings.yml`. The
 log is local-only JSONL (no upload, no cross-project share) and is bound
 by the redaction floor described in
-[`agents/contexts/artifact-engagement-flow.md`](agents/contexts/artifact-engagement-flow.md).
+[`docs/contracts/artifact-engagement-flow.md`](docs/contracts/artifact-engagement-flow.md) (beta).
 The recording rule lives at
 [`.agent-src/rules/artifact-engagement-recording.md`](.agent-src/rules/artifact-engagement-recording.md).
 
@@ -78,9 +80,9 @@ surfaces matches as a numbered-options block with an always-present
 picks every time. Engine: `scripts/command_suggester/`. Rule:
 [`.agent-src/rules/command-suggestion.md`](.agent-src/rules/command-suggestion.md).
 Locked eligibility table, scoring contract, and hardening list:
-[`agents/contexts/adr-command-suggestion.md`](agents/contexts/adr-command-suggestion.md)
+[`docs/contracts/adr-command-suggestion.md`](docs/contracts/adr-command-suggestion.md)
 and
-[`agents/contexts/command-suggestion-flow.md`](agents/contexts/command-suggestion-flow.md).
+[`docs/contracts/command-suggestion-flow.md`](docs/contracts/command-suggestion-flow.md) (beta).
 
 ## Key rules for agents editing this repo
 
@@ -99,7 +101,7 @@ and
 ```
 .agent-src.uncompressed/      ← edit here
   skills/       (128 skills)
-  rules/        (53 rules)
+  rules/        (55 rules)
   commands/     (77 commands)
   guidelines/   (46 guidelines)
   personas/     (7 personas)

package/CHANGELOG.md

@@ -103,10 +103,10 @@ baselines pin the R3 contract.
 * **ADR (R1):** [`agents/contexts/adr-work-engine-rename.md`](agents/contexts/adr-work-engine-rename.md)
   — rationale, scope of the rename, compatibility shim policy, state
   migration, golden-test contract, tradeoffs, non-goals.
-* **ADR (R2):** [`agents/contexts/adr-prompt-driven-execution.md`](agents/contexts/adr-prompt-driven-execution.md)
+* **ADR (R2):** [`docs/contracts/adr-prompt-driven-execution.md`](docs/contracts/adr-prompt-driven-execution.md)
   — naming decision (`/work` over `/do`), confidence-band gate,
   AC-projection fix, R3 deferral boundary, and golden contract.
-* **flow:** `agents/contexts/implement-ticket-flow.md` gains a "Replay
+* **flow:** `docs/contracts/implement-ticket-flow.md` gains a "Replay
   protocol — Strict-Verb comparison" section (R1) and a
   "Prompt envelopes and confidence bands (R2)" section pinning the
   band-action mapping to the scorer module.
@@ -170,17 +170,17 @@ baselines pin the R3 contract.
 
 ### Documentation (R3)
 
-* **ADR (R3):** [`agents/contexts/adr-product-ui-track.md`](agents/contexts/adr-product-ui-track.md)
+* **ADR (R3):** [`docs/contracts/adr-product-ui-track.md`](docs/contracts/adr-product-ui-track.md)
   — audit-as-hard-gate rationale, design-review loop, halt-budget
   reasoning, trivial-path-and-reclassification, stack-detection
   strategy, fe-design migration, tradeoffs, non-goals.
-* **flow contract:** [`agents/contexts/ui-track-flow.md`](agents/contexts/ui-track-flow.md)
+* **flow contract:** [`docs/contracts/ui-track-flow.md`](docs/contracts/ui-track-flow.md)
   — slot-by-slot wiring for `ui` / `ui-trivial` / `mixed`, the
   audit-path table (`STRONG_SIMILARITY = 0.7`, `TIE_GAP = 0.05`),
   design-brief lock + placeholder patterns, stack-dispatch tables,
   polish ceiling, trivial preconditions, mixed sentinels,
   idempotency table, declared ambiguities across all eight directives.
-* **extension recipe:** [`agents/contexts/ui-stack-extension.md`](agents/contexts/ui-stack-extension.md)
+* **extension recipe:** [`docs/contracts/ui-stack-extension.md`](docs/contracts/ui-stack-extension.md)
   — how to add a new stack (Svelte, SolidJS, Astro, …): label
   conventions, detector heuristic, three required skills, dispatch
   wiring, version anchor, Golden fixture, end-to-end verification.
@@ -232,7 +232,7 @@ Maintainer-targeted; consumers see no prompts.
 * **ADR:** [`agents/contexts/adr-artifact-engagement.md`](agents/contexts/adr-artifact-engagement.md)
   — rationale, default-off doctrine, privacy contract, schema
   versioning, deprecation horizon.
-* **flow:** `agents/contexts/artifact-engagement-flow.md` is the
+* **flow:** `docs/contracts/artifact-engagement-flow.md` is the
   cross-cutting reference for what gets recorded, when, and under
   which constraints; includes the maintainer hand-audit recipe.
 * **AGENTS.md + README.md:** short *Maintainer telemetry (opt-in)*
@@ -288,15 +288,90 @@ the as-is option is always present and always last.
 
 ### Documentation
 
-* **ADR:** [`agents/contexts/adr-command-suggestion.md`](agents/contexts/adr-command-suggestion.md)
+* **ADR:** [`docs/contracts/adr-command-suggestion.md`](docs/contracts/adr-command-suggestion.md)
   — "suggest, never invoke" anchor, eligibility rubric, anti-noise
   heuristics, hardening list, three opt-out paths.
-* **flow:** [`agents/contexts/command-suggestion-flow.md`](agents/contexts/command-suggestion-flow.md)
+* **flow:** [`docs/contracts/command-suggestion-flow.md`](docs/contracts/command-suggestion-flow.md)
   — scoring breakdown, evidence semantics, subordination order, and
   hardening tests.
 * **README + AGENTS.md:** short *Context-aware command suggestion*
   section pointing to the ADR and the flow doc.
 
+**Install-path pruning (relabel only)** — `docs/installation.md`
+reorders install paths by recommendation prominence. Composer + npm
+remain the default; manual / submodule / VS Code Git URL are tagged
+`advanced`; Claude.ai Web Skills UI is tagged `experimental`; Linear
+AI workspace guidance is tagged `staged`. **No installer or shipped
+artefact is removed in 1.15.0** — every path on the page still works
+and is still tested. The labels describe how prominent the path is in
+our recommendation order, not its support status.
+
+### Documentation
+
+* **`docs/installation.md`:** new label table at the top
+  (`(no label)` / `advanced` / `experimental` / `staged`) plus a
+  preamble that calls out the no-removal contract explicitly. Section
+  headers carry their label inline for skim-readers.
+* **rationale:** see R9 in
+  [`agents/roadmaps/archive/road-to-post-pr29-optimize.md`](agents/roadmaps/archive/road-to-post-pr29-optimize.md)
+  — relabelling addresses the "four install paths at zero external
+  users" tension without removing any path that an existing user
+  might rely on.
+
+## [1.15.0](https://github.com/event4u-app/agent-config/compare/1.14.0...1.15.0) (2026-05-02)
+
+### Features
+
+* **governance:** rule-interaction matrix + linter (P2.2) ([cd68591](https://github.com/event4u-app/agent-config/commit/cd6859174d289737b829fe49a4c7f92bd318a290))
+* **rules:** split chat-history into ownership/cadence/visibility (P2.1) ([7b5348d](https://github.com/event4u-app/agent-config/commit/7b5348d2656c12000fca667c2e577c026839aa11))
+* **governance:** command-collapse contract + atomic-command linter (P0.8) ([5f1ebb7](https://github.com/event4u-app/agent-config/commit/5f1ebb72484da28679f7a49fffc5cbb4bd7a07f6))
+* **work_engine:** default state file → .work-state.json + collision-safe backup ([b0f487a](https://github.com/event4u-app/agent-config/commit/b0f487a3f261797320b3726211206f813f2c2c1a))
+* **docs:** public contracts to docs/contracts/ + STABILITY policy + link checker ([7c6ac17](https://github.com/event4u-app/agent-config/commit/7c6ac17609d19505625cb4fa9a76798a403997ad))
+* support capture-only roadmaps in dashboard generator ([c0df2dc](https://github.com/event4u-app/agent-config/commit/c0df2dc3c680a6cfa6c87f2e64868360695fa3ec))
+
+### Bug Fixes
+
+* **rules:** restore Iron Law heading + code blocks in compressed roadmap-progress-sync ([96c633b](https://github.com/event4u-app/agent-config/commit/96c633b583fc17ea560fe1ddf7b915ab5a3be3f3))
+* **ci:** clear check-refs regressions in roadmap files ([56b40f3](https://github.com/event4u-app/agent-config/commit/56b40f397e632337f5f69a507b13aa2b475453c3))
+
+### Performance
+
+* **ci:** smoke GT subset + duration line + nightly full replay (P2.4) ([7b0608d](https://github.com/event4u-app/agent-config/commit/7b0608d3f51bac534f835424860049483ae6004a))
+
+### Documentation
+
+* **ui-track:** 1-page mental model + archive Phase 2 roadmap — P2.10/P2.11 ([d87673d](https://github.com/event4u-app/agent-config/commit/d87673d75ec8cd0136336a1954b356a953b79e4e))
+* **install:** relabel install paths (advanced/experimental/staged) — P2.5 ([66e5389](https://github.com/event4u-app/agent-config/commit/66e53894f3dd12ff0762a56f677e302d1ca726c1))
+* add visible (beta) markers to public-surface contract links ([282b74f](https://github.com/event4u-app/agent-config/commit/282b74fccab2c0ba585271013c5fe61b396aaa09))
+* positioning headline + work_engine vs runtime_dispatcher separation ([ccf833f](https://github.com/event4u-app/agent-config/commit/ccf833f07b34ff2c6c5cf64e8328fb67b7629c4d))
+* **roadmaps:** reviewer feedback + directional → out-of-horizon ([6af0320](https://github.com/event4u-app/agent-config/commit/6af03205537d761a0cbe6c205662c34854deea6a))
+* **rules:** position-agnostic recommendation in user-interaction ([ee57ae0](https://github.com/event4u-app/agent-config/commit/ee57ae0d233b3332f30dfd3d3f67b3954ce153ef))
+* **roadmaps:** retire stale open-questions and placeholder sections ([c1ec177](https://github.com/event4u-app/agent-config/commit/c1ec17782521bb5688260d1873423fbf4d4adc99))
+* **roadmaps:** synthesize decisions from multi-AI review ([4d9dcc1](https://github.com/event4u-app/agent-config/commit/4d9dcc19929fe7d3fa2657509a4b8a2e9a1ee7e2))
+* add capture-only synthesis roadmaps ([d2bdb76](https://github.com/event4u-app/agent-config/commit/d2bdb76ec562d8a00313f49b388083fdad8f1b42))
+
+### Refactoring
+
+* **work_engine:** modularise cli.py into 7 focused modules (P2.3) ([ad92366](https://github.com/event4u-app/agent-config/commit/ad9236681c1537beec3d407bead9b7386c57c73d))
+* **roadmaps:** binary status model — ready (implicit) / draft (hidden) ([2d3d713](https://github.com/event4u-app/agent-config/commit/2d3d713a52ac039c08317817331ba6aaa81fcb12))
+
+### Tests
+
+* **work_engine:** cover default state file + UI-prompt routing + medium-band halt (P0.7) ([e97c499](https://github.com/event4u-app/agent-config/commit/e97c499fa7daaf0478423efbdb34d648b6e400c8))
+
+### Chores
+
+* **generated:** sync compressed projections for chat-history split (P2.1) ([f53a44f](https://github.com/event4u-app/agent-config/commit/f53a44f31fd7d93c28122b945f8059bd112dc854))
+* **generated:** regenerate .windsurfrules after rule edits ([0090392](https://github.com/event4u-app/agent-config/commit/00903924eaf1955ad2049dc03c3c57d9f4ff016e))
+* **roadmaps:** mark Phase 1 progress in road-to-post-pr29-optimize + dashboard ([a2160af](https://github.com/event4u-app/agent-config/commit/a2160afd6e7280bd3d4a71641fb4dba8234edf21))
+* **scripts:** whitelist scripts/mcp_server/ in portability check ([259745e](https://github.com/event4u-app/agent-config/commit/259745e9f52ea0a60e3e92a553a5938b15adc0ca))
+
+### Other
+
+* **readme:** drop redundant 'no runtime deps' bullet — clear 500-line limit ([53b5df4](https://github.com/event4u-app/agent-config/commit/53b5df481122ccbd70ce358a3192643c7fff73b0))
+* **readme:** trim Stability tiers + command-suggestion blocks to clear 500-line limit ([5bb50ba](https://github.com/event4u-app/agent-config/commit/5bb50ba43d8734f5deb02c0b34c9c6e26475c52b))
+* **rules:** trim roadmap-progress-sync to 199 lines (clear CI hard limit) ([12c3a2e](https://github.com/event4u-app/agent-config/commit/12c3a2e1357dfca7ec0bd2f6b507e606ec2de596))
+
 ## [1.14.0](https://github.com/event4u-app/agent-config/compare/1.13.0...1.14.0) (2026-05-01)
 
 ### Features

package/README.md

@@ -1,11 +1,13 @@
 # Agent Config — Governed Agent System
 
+> **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
+
 Teach your AI agents Laravel, PHP, testing, Git workflows, and **120+ more skills** — with quality guardrails built in.
 
 > Your agent learns to write Laravel code, run tests, create PRs, fix CI — and follows your team's coding standards while doing it.
 
 <p align="center">
-  <strong>128 Skills</strong> · <strong>53 Rules</strong> · <strong>77 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>128 Skills</strong> · <strong>55 Rules</strong> · <strong>77 Commands</strong> · <strong>46 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -91,7 +93,7 @@ Install in the same project (dev-only):
 npm install --save-dev @event4u/agent-memory
 ```
 
-→ [Memory contract & retrieval API](agents/contexts/agent-memory-contract.md)
+→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta)
 
 ---
 
@@ -129,7 +131,7 @@ so you decide — never a silent guess. Persona comes from
 (plan-only, skips implementation).
 
 → [Command reference](.agent-src/commands/implement-ticket.md) ·
-  [Flow contract](agents/contexts/implement-ticket-flow.md)
+  [Flow contract](docs/contracts/implement-ticket-flow.md) (beta)
 
 ### Sibling entrypoint: `/work` (free-form prompt)
 
@@ -156,7 +158,7 @@ to `/implement-ticket`. UI-shaped prompts are routed through the
 
 → [Command reference](.agent-src/commands/work.md) ·
   [`refine-prompt` skill](.agent-src/skills/refine-prompt/SKILL.md) ·
-  [ADR](agents/contexts/adr-prompt-driven-execution.md)
+  [ADR](docs/contracts/adr-prompt-driven-execution.md)
 
 **Pick which one:** ticket id or pasted ticket payload → `/implement-ticket`.
 Free-form goal, no ticket → `/work`. The two share `.work-state.json`
@@ -188,9 +190,10 @@ screenshots / findings) via a defined contract. Stack detection routes
 `react-shadcn` / `vue` / `plain`; trivial path reclassifies loudly when
 preconditions fail. Halt budget on the happy path is 2.
 
-→ [Flow contract](agents/contexts/ui-track-flow.md) ·
-  [ADR](agents/contexts/adr-product-ui-track.md) ·
-  [Stack-extension recipe](agents/contexts/ui-stack-extension.md)
+→ [Mental model](docs/ui-track-mental-model.md) (1 page — when each set, where it stops, what the agent must never do) ·
+  [Flow contract](docs/contracts/ui-track-flow.md) (beta) ·
+  [ADR](docs/contracts/adr-product-ui-track.md) ·
+  [Stack-extension recipe](docs/contracts/ui-stack-extension.md) (beta)
 
 ---
 
@@ -252,16 +255,16 @@ Start with **Rules + Skills**. Everything else is optional.
 | Mode | What's active | Token overhead |
 |---|---|---|
 | **Minimal** (default) | Rules, Skills, Commands | Zero |
-| **Balanced** | + Runtime dispatcher for skills that declare a shell command | Low |
-| **Full** | + Tool adapters (GitHub / Jira read-only, opt-in) | Moderate |
+| **Balanced** | + Runtime Dispatcher for skills that declare a shell command | Low |
+| **Full** | + Tool Adapters (GitHub / Jira read-only, opt-in) | Moderate |
 
 Nothing runs automatically without your control. [Configure modes →](docs/customization.md)
 
-> **Experimental modules:** the runtime (dispatcher + shell handler) runs
-> two pilot skills in CI (`lint-skills`, `check-refs`). The tool registry
-> ships two read-only adapters (GitHub, Jira) behind the `full` profile.
-> Other handlers (`php`, `node`) are still scaffold. The `minimal`
-> profile — which most users should pick — is unaffected.
+> **Stability tiers** — [`STABILITY.md`](docs/contracts/STABILITY.md) for
+> the full matrix. Runtime Dispatcher: **stable** (`php` / `node` handlers
+> scaffold). Work Engine: **beta (beta)** — orchestrator behind `/work`
+> + `/implement-ticket`. Tool Adapters: **experimental**, read-only,
+> behind `full`. `minimal` profile unaffected.
 
 ---
 
@@ -377,9 +380,9 @@ builds artefacts you upload or paste into the platform's own surface.
 
 The Linear digest is split into three layers — workspace (universal
 coding posture), team (framework-specific), personal (empty stub). See
-[`agents/contexts/linear-ai-three-layers.md`](agents/contexts/linear-ai-three-layers.md)
+[`docs/contracts/linear-ai-three-layers.md`](docs/contracts/linear-ai-three-layers.md) (beta)
 for the rationale and
-[`agents/contexts/linear-ai-rules-inclusion.md`](agents/contexts/linear-ai-rules-inclusion.md)
+[`docs/contracts/linear-ai-rules-inclusion.md`](docs/contracts/linear-ai-rules-inclusion.md) (beta)
 for the per-rule routing.
 
 ---
@@ -404,6 +407,7 @@ for the per-rule routing.
 | [**Development**](docs/development.md) | Prerequisites, editing workflow, all `task` commands, project structure |
 | [**Customization**](docs/customization.md) | Overrides, AGENTS.md, agent settings, cost profiles |
 | [**Quality & CI**](docs/quality.md) | Linting, CI pipeline, compression system |
+| [**Migration**](docs/MIGRATION.md) | Per-version upgrade steps (e.g. `implement_ticket → work_engine` in 1.15.0) |
 
 Uninstalling: see
 [docs/installation.md#uninstalling](docs/installation.md#uninstalling) —
@@ -427,7 +431,7 @@ telemetry:
 
 Reports: `./agent-config telemetry:report`. Full contract,
 privacy/redaction floor, and quartile semantics:
-[`agents/contexts/artifact-engagement-flow.md`](agents/contexts/artifact-engagement-flow.md).
+[`docs/contracts/artifact-engagement-flow.md`](docs/contracts/artifact-engagement-flow.md) (beta).
 
 ### Context-aware command suggestion
 
@@ -446,11 +450,9 @@ commands:
 ```
 
 Per-conversation: `/command-suggestion-off` disables the layer until
-the user re-enables or the chat ends. Full scoring contract and
-hardening list:
-[`agents/contexts/adr-command-suggestion.md`](agents/contexts/adr-command-suggestion.md)
-and
-[`agents/contexts/command-suggestion-flow.md`](agents/contexts/command-suggestion-flow.md).
+re-enabled or the chat ends. Full scoring contract and hardening:
+[`adr-command-suggestion`](docs/contracts/adr-command-suggestion.md),
+[`command-suggestion-flow`](docs/contracts/command-suggestion-flow.md) (beta).
 
 ---
 
@@ -492,7 +494,6 @@ task lint-skills   # Lint skills, rules, commands
 **For contributors only** (rebuilding `.augment/` locally):
 
 - [Task](https://taskfile.dev/) — runs the CI pipeline (`task ci`).
-- No runtime dependencies — the package ships static markdown files.
 
 ## License
 

package/docs/MIGRATION.md

@@ -0,0 +1,122 @@
+# Migration Guide
+
+How to move existing checkouts forward when `event4u/agent-config`
+ships breaking layout changes. Each section is self-contained: read
+only the version you are upgrading to.
+
+> Symbol legend — 🔄 automatic, ✋ manual, 💡 advisory.
+
+## 1.14.x → 1.15.0 — `implement_ticket` → `work_engine`
+
+1.15.0 finishes the rename started with PR #29: the orchestration
+package is now `work_engine` and the default state file is
+`.work-state.json`. A back-compat shim keeps `implement_ticket`
+imports working for one minor release; the legacy state filename is
+detected on load and surfaces a one-shot migration hint instead of
+failing silently.
+
+### What changed
+
+| Surface | 1.14.x | 1.15.0 |
+|---|---|---|
+| Orchestration package | `implement_ticket/` | `work_engine/` |
+| Default state file | `.implement-ticket-state.json` | `.work-state.json` |
+| Legacy package import | native | thin shim, removed in 1.16.0 |
+| State schema | v0 (flat `ticket`) | v1 (`input.kind` envelope) |
+
+The schema migration itself shipped in 1.14.0 (`migrate_payload`
+already wraps v0 → v1). 1.15.0 only flips the *default* output
+filename and the shipped package name; v0 files on disk are still
+recognised on a clear error path.
+
+### Required action
+
+✋ **Run the one-shot migration** if your project still has a
+`.implement-ticket-state.json` file:
+
+```bash
+python3 -m work_engine.migration.v0_to_v1 .implement-ticket-state.json
+```
+
+This:
+
+1. Writes `.work-state.json` with the v1 envelope alongside the
+   legacy file.
+2. Rotates the v0 file to `.implement-ticket-state.json.bak` (or
+   `.bak.1`, `.bak.2`, … if a previous backup is already present —
+   no silent overwrites).
+3. Refuses to overwrite an existing `.work-state.json`.
+4. Exits `0` on success, `2` on schema errors.
+
+Pass `--no-backup` if you do not want the v0 file kept around, or
+`--destination <path>` for a custom location.
+
+🔄 **Detection on load.** If the engine is invoked with
+`--state-file .work-state.json` (or no `--state-file` at all) and
+finds only the legacy file, it stops with:
+
+```
+error: Found legacy state file .implement-ticket-state.json but no
+.work-state.json. The default state file was renamed in 1.15.0. Run
+`python3 -m work_engine.migration.v0_to_v1 .implement-ticket-state.json`
+to migrate, or pass `--state-file .implement-ticket-state.json` to
+keep using the old name. See docs/MIGRATION.md.
+```
+
+The detection only fires when the requested state file uses the
+canonical name; explicit `--state-file <other>.json` bypasses it,
+so power users with their own naming scheme stay in control.
+
+### Optional — keep using the legacy name
+
+💡 You do **not** have to migrate immediately. Both of these keep
+working through the 1.15.x cycle:
+
+- Pass `--state-file .implement-ticket-state.json` on every CLI
+  invocation. The loader reads v0 and v1 transparently; format is
+  preserved on save.
+- Keep importing from `implement_ticket` — the shim under
+  `templates/scripts/implement_ticket/` re-exports the
+  `work_engine` API verbatim. Removed in 1.16.0.
+
+The legacy hint is a UX nudge, not a hard cutover.
+
+### Rolling back
+
+If something goes wrong:
+
+```bash
+mv .work-state.json /tmp/work-state-bad.json
+mv .implement-ticket-state.json.bak .implement-ticket-state.json
+```
+
+Then either re-run the migration or pin to 1.14.x until the issue
+is reported. The v0 backup is byte-equal with the input —
+`migrate_file` only renames the source after successfully writing
+the v1 destination.
+
+### CI / repository hygiene
+
+If your project commits state files (uncommon but supported):
+
+- Update `.gitignore` to exclude both `.implement-ticket-state.json`
+  and `.work-state.json` if you want them transient.
+- Otherwise, commit the new `.work-state.json` and either delete
+  the `.bak` rotation or move it under an archive path — the
+  loader never reads `.bak` files.
+
+### Reference
+
+- Schema and field-by-field semantics:
+  [`docs/contracts/implement-ticket-flow.md`](contracts/implement-ticket-flow.md#workstate-v1-schema).
+- Stability level: `work_engine` is **beta** — see
+  [`docs/contracts/STABILITY.md`](contracts/STABILITY.md).
+- Source of truth for the migrator:
+  [`templates/scripts/work_engine/migration/v0_to_v1.py`](../.agent-src.uncompressed/templates/scripts/work_engine/migration/v0_to_v1.py).
+
+## Older versions
+
+No formal migration was required before 1.15.0. The pre-1.14.0 v0
+state schema (flat `ticket`, `.implement-ticket-state.json`) is
+documented in `docs/contracts/implement-ticket-flow.md` and is
+covered by the same `v0_to_v1` migrator above.

package/docs/architecture.md

@@ -1,17 +1,22 @@
 # Architecture
 
+> **agent-config is not a runtime, but it ships a deterministic orchestration contract / state machine for host agents.**
+
 ## System overview
 
 ```
-Rules         → Behavior enforcement (always active)         ← stable
-Skills        → Execution logic (on-demand expertise)        ← stable
-Runtime       → Dispatcher + shell handler (pilot skills)    ← partial
-Tools         → External integrations (GitHub, Jira)         ← experimental
+Rules               → Behavior enforcement (always active)              ← stable
+Skills              → Execution logic (on-demand expertise)             ← stable
+Runtime Dispatcher  → Single-skill shell execution (pilot skills)       ← stable (mechanism)
+Work Engine         → Multi-step orchestration for /work + /implement   ← beta
+Tool Adapters       → External integrations (GitHub, Jira)              ← experimental
 ```
 
-**Stable** = shipped, documented, exercised by the default (`minimal`) profile.
-**Experimental** = scaffold with tests and data model, but no real execution
-wired up yet.
+Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
+
+- **stable** = shipped, documented, exercised by the default (`minimal`) profile or by CI on every PR; SemVer-major for breaks.
+- **beta** = shipped and load-bearing for one or more flows, but the surface is expected to evolve; minor-version breaks allowed under a `### Breaking` CHANGELOG note.
+- **experimental** = scaffold or pilot status; breaks allowed in any release.
 
 > The previous "observability, feedback, lifecycle" layers were removed in
 > 1.5 — they were scaffolds without production consumers. See the
@@ -59,10 +64,10 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 93 | On-demand expertise — Laravel, testing, Docker, API design, security, ... |
-| **Rules** | 31 | Always-active constraints — coding standards, scope control, verification |
-| **Commands** | 51 | Slash-command workflows — `/commit`, `/create-pr`, `/fix-ci`, `/compress`, ... |
-| **Guidelines** | 34 | Coding guidelines by language — PHP patterns, Eloquent, Playwright, ... |
+| **Skills** | 128 | On-demand expertise — Laravel, testing, Docker, API design, security, ... |
+| **Rules** | 55 | Always-active constraints — coding standards, scope control, verification |
+| **Commands** | 77 | Slash-command workflows — `/commit`, `/create-pr`, `/fix-ci`, `/compress`, ... |
+| **Guidelines** | 46 | Coding guidelines by language — PHP patterns, Eloquent, Playwright, ... |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 
@@ -79,18 +84,25 @@ fails on any source-side violation, without producing artifacts.
 
 Ensures: no guessing, analysis before action, real verification, consistent outputs.
 
-### 2. Execution Layer (Runtime) — partially real, partially scaffold
+### 2. Runtime Dispatcher — stable mechanism, pilot coverage
+
+> **Scope:** single-skill execution. Resolves a `SKILL.md` with
+> `execution.command` argv, enforces safety constraints, hands off to
+> the matching handler. **Not** a multi-step orchestrator — that is
+> the Work Engine (next section).
 
 > **Status:**
-> - **Real:** shell-handler path — skills that declare an `execution.command`
->   argv are dispatched and executed by `scripts/runtime_handler.py`. A typed
->   `ExecutionResult` (exit code, stdout, stderr, duration, artifacts) is
->   returned and can be persisted as JSON via `--output FILE`. Pilots:
->   `lint-skills`, `check-refs`. Both run on every PR and appear in the
->   GitHub Step Summary via `scripts/ci_summary.py`.
-> - **Scaffold:** `php` and `node` handlers — the frontmatter accepts them
->   and the registry validates them, but no handler implementation exists
->   yet.
+> - **Stable mechanism:** the dispatcher itself
+>   (`scripts/runtime_dispatcher.py`), the shell handler
+>   (`scripts/runtime_handler.py`), and the `ExecutionResult` shape.
+>   `subprocess.run` is invoked with `shell=False` (argv only); the
+>   environment is scrubbed to an explicit allowlist.
+> - **Pilot coverage:** two skills ship as live pilots —
+>   `lint-skills` and `check-refs` — both run on every PR and appear
+>   in the GitHub Step Summary via `scripts/ci_summary.py`.
+> - **Scaffold:** `php` and `node` handlers — the frontmatter accepts
+>   them and the registry validates them, but no handler
+>   implementation exists yet.
 
 Skills opt into runtime by declaring execution metadata:
 
@@ -113,14 +125,49 @@ Invoke a runtime-capable skill end-to-end:
 python3 scripts/runtime_dispatcher.py run --skill lint-skills
 ```
 
-The dispatcher resolves the skill, enforces safety constraints, then hands
-off to the matching handler. Environment is scrubbed to an explicit
-allowlist; `subprocess.run` is invoked with `shell=False` (argv only).
-
-Planned scope (still to come): `php` / `node` handlers, tool-registry
-wiring for `allowed_tools`, streaming output.
-
-### 3. Tool Integration — experimental
+A typed `ExecutionResult` (exit code, stdout, stderr, duration,
+artifacts) is returned and can be persisted as JSON via
+`--output FILE`.
+
+Planned scope: `php` / `node` handlers, tool-registry wiring for
+`allowed_tools`, streaming output.
+
+### 3. Work Engine — beta, multi-step orchestration
+
+> **Scope:** multi-step phase dispatch for `/work` and
+> `/implement-ticket`. Drives the
+> `refine → score → plan → implement → test → verify → report` loop,
+> persists state in `.work-state.json`, and routes UI-shaped work
+> through the product UI track. Lives at
+> [`templates/scripts/work_engine/`](../.agent-src.uncompressed/templates/scripts/work_engine/);
+> shipped to consumer projects via `scripts/install.py`.
+
+> **Status: beta.** The contract (directive sets, halt budgets,
+> envelope shape) has shipped one full SemVer-minor cycle, but the
+> surface is still expected to evolve. Breaks are allowed in
+> minor-version releases under a `### Breaking` CHANGELOG note. See
+> [`docs/contracts/STABILITY.md`](contracts/STABILITY.md).
+
+Key responsibilities:
+
+- **Directive routing** — `ui` / `ui-trivial` / `mixed` directive
+  sets, locked into the contract at
+  [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md) (beta).
+- **Halt protocol** — every phase emits a structured halt; the
+  agent re-enters with the user's answer, never improvises.
+- **State machine** — `.work-state.json` is the single source of
+  truth across resumes; the engine refuses to switch envelope
+  mid-flight. Legacy `.implement-ticket-state.json` files are
+  detected on load and routed through
+  [`docs/MIGRATION.md`](MIGRATION.md).
+- **Hooks** — chat-history, telemetry, and platform hooks fire
+  through the engine's hook layer.
+
+The Work Engine **uses** the Runtime Dispatcher when a phase needs
+to execute a single skill (e.g. lint, refs check), but the two are
+independent components with separate stability tiers.
+
+### 4. Tool Adapters — experimental
 
 > **Status: scaffold + read-only GitHub calls.** With a `GITHUB_TOKEN` the
 > GitHub adapter performs real read calls; without one it returns scaffold
@@ -134,14 +181,16 @@ Controlled integration via adapters:
 - Tool registry with safety rules for execution
 - Structured responses with error classification
 
-### 4. Cost Control
+### 5. Cost Control
 
 > **Key principle:** Opt-in by default.
 
-The dispatcher and tool adapters activate only under the `balanced` or
-`full` profile. The default `minimal` profile ships rules, skills, and
-commands and nothing else. All settings and their profile defaults are
-documented in
+The Runtime Dispatcher and Tool Adapters activate only under the
+`balanced` or `full` profile. The Work Engine activates whenever
+`/work` or `/implement-ticket` is invoked and is independent of the
+cost profile. The default `minimal` profile ships rules, skills, and
+commands and nothing else. All settings and their profile defaults
+are documented in
 [`.agent-src.uncompressed/templates/agent-settings.md`](../.agent-src.uncompressed/templates/agent-settings.md).
 
 ---