@event4u/agent-config 1.18.0 → 1.20.0

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **327 public artefacts** shipped by
+Consumer-facing catalog of all **332 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `python3 scripts/generate_index.py`
 > Auto-generated — do not edit manually.
 
-## Skills (129)
+## Skills (134)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -39,6 +39,7 @@ are excluded.
 | skill | [`dashboard-design`](../.agent-src/skills/dashboard-design/SKILL.md) |  | Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling. |
 | skill | [`data-flow-mapper`](../.agent-src/skills/data-flow-mapper/SKILL.md) |  | Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line. |
 | skill | [`database`](../.agent-src/skills/database/SKILL.md) |  | Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'. |
+| skill | [`dcf-modeling`](../.agent-src/skills/dcf-modeling/SKILL.md) |  | Wing-4 valuation cognition for a CFO / finance-partner. Use when a deal, internal investment, or board ask names DCF, intrinsic value, WACC, terminal value, or 'what's it worth on a 5-year hold'. |
 | skill | [`dependency-upgrade`](../.agent-src/skills/dependency-upgrade/SKILL.md) |  | Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification. |
 | skill | [`description-assist`](../.agent-src/skills/description-assist/SKILL.md) |  | Use when polishing a skill/rule/command/guideline frontmatter description — pushier phrasing, trigger coverage, undertrigger audit — even if the user just says 'make this pushier'. |
 | skill | [`design-review`](../.agent-src/skills/design-review/SKILL.md) |  | Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more. |
@@ -54,6 +55,7 @@ are excluded.
 | skill | [`file-editor`](../.agent-src/skills/file-editor/SKILL.md) |  | Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled. |
 | skill | [`finishing-a-development-branch`](../.agent-src/skills/finishing-a-development-branch/SKILL.md) |  | Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'. |
 | skill | [`flux`](../.agent-src/skills/flux/SKILL.md) |  | Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives. |
+| skill | [`funnel-analysis`](../.agent-src/skills/funnel-analysis/SKILL.md) |  | Use when diagnosing where a SaaS or product funnel leaks — visitor → signup → activation → paid → retained — channel-agnostic, conversion-rate-driven. |
 | skill | [`git-workflow`](../.agent-src/skills/git-workflow/SKILL.md) |  | Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git. |
 | skill | [`github-ci`](../.agent-src/skills/github-ci/SKILL.md) |  | Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'. |
 | skill | [`grafana`](../.agent-src/skills/grafana/SKILL.md) |  | Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana. |
@@ -84,6 +86,7 @@ are excluded.
 | skill | [`migration-creator`](../.agent-src/skills/migration-creator/SKILL.md) |  | Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness. |
 | skill | [`module-management`](../.agent-src/skills/module-management/SKILL.md) |  | Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions. |
 | skill | [`multi-tenancy`](../.agent-src/skills/multi-tenancy/SKILL.md) |  | Use when working with the multi-tenant architecture — customer DB switching, FQDN routing, tenant isolation, or cross-tenant operations. |
+| skill | [`okr-tree-modeling`](../.agent-src/skills/okr-tree-modeling/SKILL.md) |  | Use when decomposing a company objective into team OKRs, auditing a draft OKR tree, or stress-testing an existing one for measurability and laddering. |
 | skill | [`openapi`](../.agent-src/skills/openapi/SKILL.md) |  | Use when documenting APIs — OpenAPI/Swagger, PHP attributes, Redocly validation, versioned specs — even when the user just says 'document this endpoint' without naming OpenAPI. |
 | skill | [`override-management`](../.agent-src/skills/override-management/SKILL.md) |  | Creates and manages project-level overrides for shared skills, rules, and commands — extending or replacing originals from .augment/ with project-specific behavior in agents/overrides/. |
 | skill | [`performance`](../.agent-src/skills/performance/SKILL.md) |  | Use when optimizing application performance — caching strategies, eager loading, query optimization, Redis patterns, or background job design. |
@@ -113,6 +116,7 @@ are excluded.
 | skill | [`refine-ticket`](../.agent-src/skills/refine-ticket/SKILL.md) |  | Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt. |
 | skill | [`requesting-code-review`](../.agent-src/skills/requesting-code-review/SKILL.md) |  | Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'. |
 | skill | [`review-routing`](../.agent-src/skills/review-routing/SKILL.md) |  | Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML. |
+| skill | [`rice-prioritization`](../.agent-src/skills/rice-prioritization/SKILL.md) |  | Use when ranking competing initiatives for a roadmap, breaking a tie between two features, or auditing a backlog for hidden low-value work via Reach × Impact × Confidence ÷ Effort. |
 | skill | [`roadmap-management`](../.agent-src/skills/roadmap-management/SKILL.md) |  | Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking. |
 | skill | [`rtk-output-filtering`](../.agent-src/skills/rtk-output-filtering/SKILL.md) |  | Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns. |
 | skill | [`rule-writing`](../.agent-src/skills/rule-writing/SKILL.md) |  | Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'. |
@@ -125,7 +129,7 @@ are excluded.
 | skill | [`skill-reviewer`](../.agent-src/skills/skill-reviewer/SKILL.md) |  | Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations. |
 | skill | [`skill-writing`](../.agent-src/skills/skill-writing/SKILL.md) |  | Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'. |
 | skill | [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) |  | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL. |
-| skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — five modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate) — models from .agent-settings.yml. |
+| skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml. |
 | skill | [`systematic-debugging`](../.agent-src/skills/systematic-debugging/SKILL.md) |  | Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'. |
 | skill | [`technical-specification`](../.agent-src/skills/technical-specification/SKILL.md) |  | Use when the user says "write a spec", "create RFC", or "document this decision". Writes technical specifications, RFCs, and ADRs with clear structure. |
 | skill | [`terraform`](../.agent-src/skills/terraform/SKILL.md) |  | Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform. |
@@ -134,6 +138,7 @@ are excluded.
 | skill | [`test-performance`](../.agent-src/skills/test-performance/SKILL.md) |  | Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives. |
 | skill | [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) |  | Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation. |
 | skill | [`traefik`](../.agent-src/skills/traefik/SKILL.md) |  | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
+| skill | [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) |  | Use when modeling CAC, LTV, gross-margin payback, or contribution margin per customer — for SaaS, marketplace, or transactional businesses. |
 | skill | [`universal-project-analysis`](../.agent-src/skills/universal-project-analysis/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills. |
 | skill | [`upstream-contribute`](../.agent-src/skills/upstream-contribute/SKILL.md) |  | Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package. |
 | skill | [`using-git-worktrees`](../.agent-src/skills/using-git-worktrees/SKILL.md) |  | Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'. |
@@ -141,7 +146,7 @@ are excluded.
 | skill | [`verify-completion-evidence`](../.agent-src/skills/verify-completion-evidence/SKILL.md) |  | Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (55)
+## Rules (53)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -154,9 +159,6 @@ are excluded.
 | rule | [`ask-when-uncertain`](../.agent-src/rules/ask-when-uncertain.md) | always | Ask when uncertain — don't guess, assume, or improvise |
 | rule | [`autonomous-execution`](../.agent-src/rules/autonomous-execution.md) | auto | Deciding whether to ask the user or just act on a workflow step — trivial-vs-blocking classification, autonomy opt-in detection, commit default; defers to non-destructive-by-default for the Hard Floor |
 | rule | [`capture-learnings`](../.agent-src/rules/capture-learnings.md) | auto | After completing a task where a repeated mistake or successful pattern appeared — capture as rule or skill |
-| rule | [`chat-history-cadence`](../.agent-src/rules/chat-history-cadence.md) | auto | Appending to .agent-chat-history — cadence boundaries (per_turn/per_phase/per_tool), turn-check ownership refusal handling, never writing the file directly; cadence is the trigger, not reply length |
-| rule | [`chat-history-ownership`](../.agent-src/rules/chat-history-ownership.md) | auto | First turn or reference to .agent-chat-history — detects ownership (match/returning/foreign/missing) and HOOK/ENGINE/CHECKPOINT/MANUAL path classification with numbered-options prompt |
-| rule | [`chat-history-visibility`](../.agent-src/rules/chat-history-visibility.md) | auto | Emitting the chat-history heartbeat marker — paste subprocess stdout verbatim or nothing, never type from memory, hybrid mode prints on drift only, slip handling per language-and-tone |
 | rule | [`cli-output-handling`](../.agent-src/rules/cli-output-handling.md) | auto | Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk when installed; tail/grep is fallback. |
 | rule | [`command-suggestion-policy`](../.agent-src/rules/command-suggestion-policy.md) | auto | User prompt without /command but matching an eligible slash command — surface matches as numbered options with as-is escape hatch; never auto-executes, user always picks |
 | rule | [`commit-conventions`](../.agent-src/rules/commit-conventions.md) | auto | Git commit message format, branch naming, conventional commits, committing, pushing, or creating pull requests |
@@ -174,6 +176,7 @@ are excluded.
 | rule | [`minimal-safe-diff`](../.agent-src/rules/minimal-safe-diff.md) | auto | When writing or reviewing a diff — the smallest change that solves the stated problem; no drive-by edits, no opportunistic refactors, no reformatting of untouched code |
 | rule | [`missing-tool-handling`](../.agent-src/rules/missing-tool-handling.md) | auto | When a CLI tool needed for the task is not installed — ask before working around it; do NOT install silently |
 | rule | [`model-recommendation`](../.agent-src/rules/model-recommendation.md) | auto | Starting a new task, switching task type, or invoking a command — detect task complexity and recommend the optimal model (Opus/Sonnet/GPT) before any work |
+| rule | [`no-attribution-footers`](../.agent-src/rules/no-attribution-footers.md) | auto | Generating PR/issue/comment/commit-message bodies — forbids unsolicited 'Generated with', 'Co-authored by', or 'Pull Request opened by' attribution footers in any user-owned artifact |
 | rule | [`no-cheap-questions`](../.agent-src/rules/no-cheap-questions.md) | always | No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on) |
 | rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Adding a link to a specific file in agents/roadmaps/ from any stable artifact (rule, skill, command, context, guideline) — roadmaps are transient; promote durable findings to agents/contexts/ instead |
 | rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass |
@@ -201,7 +204,7 @@ are excluded.
 | rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (95)
+## Commands (94)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -214,11 +217,10 @@ are excluded.
 | command | [`analyze-reference-repo`](../.agent-src/commands/analyze-reference-repo.md) |  | Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project. |
 | command | [`bug-fix`](../.agent-src/commands/bug-fix.md) |  | Plan and implement a bug fix — based on investigation, with quality checks and test verification |
 | command | [`bug-investigate`](../.agent-src/commands/bug-investigate.md) |  | Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause |
-| command | [`chat-history:checkpoint`](../.agent-src/commands/chat-history/checkpoint.md) | cluster: chat-history | Append a phase-boundary entry to .agent-chat-history — CHECKPOINT fallback for platforms without a native hook (Augment IDE, Cursor pre-1.7, Cline non-Mac/Linux). ~1s. |
-| command | [`chat-history:clear`](../.agent-src/commands/chat-history/clear.md) | cluster: chat-history | Manually delete the persistent chat-history log — asks for confirmation, optionally archives to a timestamped backup before wiping |
-| command | [`chat-history:resume`](../.agent-src/commands/chat-history/resume.md) | cluster: chat-history | Load the persistent chat-history log into the current conversation — picks match/returning/foreign flow and supports resume, merge, replace, or continue |
+| command | [`chat-history:import`](../.agent-src/commands/chat-history/import.md) | cluster: chat-history | Surface prior chat-history sessions as numbered options, let the user pick exactly one, then render its entries verbatim into the current chat — selective, user-driven cross-session import |
+| command | [`chat-history:learn`](../.agent-src/commands/chat-history/learn.md) | cluster: chat-history | Pick a prior chat-history session and mine it for project-improving learnings — runs learning-to-rule-or-skill on the picked session, drafts proposal(s) under agents/proposals/ |
 | command | [`chat-history:show`](../.agent-src/commands/chat-history/show.md) | cluster: chat-history | Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and the last few entries |
-| command | [`chat-history`](../.agent-src/commands/chat-history.md) | cluster: chat-history | Chat-history orchestrator — routes to show, resume, clear, checkpoint |
+| command | [`chat-history`](../.agent-src/commands/chat-history.md) | cluster: chat-history | Chat-history orchestrator — routes to show, import, learn |
 | command | [`check-current-md`](../.agent-src/commands/check-current-md.md) |  | Check the open .md file (or a passed path) for German outside DE:/EN: anchor blocks — umlauts, function words, untranslated quotes. Reports and offers fixes. |
 | command | [`commit:in-chunks`](../.agent-src/commands/commit/in-chunks.md) | cluster: commit | Stage and commit all uncommitted changes in logical chunks WITHOUT confirmation — sibling of /commit for autonomous flows |
 | command | [`commit`](../.agent-src/commands/commit.md) | cluster: commit | Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits |
@@ -301,14 +303,16 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (48)
+## Guidelines (51)
 
 | kind | name | category | description |
 |---|---|---|---|
 | guideline | [`agent-interaction-and-decision-quality`](../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md) | agent-infra |  |
+| guideline | [`ask-when-uncertain-demos`](../docs/guidelines/agent-infra/ask-when-uncertain-demos.md) | agent-infra |  |
 | guideline | [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md) | agent-infra |  |
 | guideline | [`break-glass-usage`](../docs/guidelines/agent-infra/break-glass-usage.md) | agent-infra |  |
 | guideline | [`developer-judgment`](../docs/guidelines/agent-infra/developer-judgment.md) | agent-infra |  |
+| guideline | [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md) | agent-infra |  |
 | guideline | [`engineering-memory-data-format`](../docs/guidelines/agent-infra/engineering-memory-data-format.md) | agent-infra |  |
 | guideline | [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md) | agent-infra |  |
 | guideline | [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) | agent-infra |  |
@@ -322,6 +326,7 @@ are excluded.
 | guideline | [`self-improvement-pipeline`](../docs/guidelines/agent-infra/self-improvement-pipeline.md) | agent-infra |  |
 | guideline | [`size-and-scope`](../docs/guidelines/agent-infra/size-and-scope.md) | agent-infra |  |
 | guideline | [`tool-integration`](../docs/guidelines/agent-infra/tool-integration.md) | agent-infra |  |
+| guideline | [`verify-before-complete-demos`](../docs/guidelines/agent-infra/verify-before-complete-demos.md) | agent-infra |  |
 | guideline | [`readme-size-and-splitting`](../docs/guidelines/docs/readme-size-and-splitting.md) | docs |  |
 | guideline | [`playwright`](../docs/guidelines/e2e/playwright.md) | e2e |  |
 | guideline | [`api-design`](../docs/guidelines/php/api-design.md) | php |  |

package/docs/contracts/adr-chat-history-split.md

@@ -4,7 +4,16 @@ stability: beta
 
 # ADR — Chat-history rule split
 
-> **Status:** Decided · 2026-05-02
+> **Status:** Superseded · 2026-05-04 · by
+> [`agents/contexts/chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+> The cooperative three-rule split this ADR locked in
+> (`chat-history-ownership` / `-cadence` / `-visibility`) has been
+> reduced to a hook-only structural artifact. The three always-rules,
+> the heartbeat marker, and the Foreign-Prompt handshake are gone;
+> `session_start` hooks auto-adopt foreign sessions silently. The text
+> below is preserved for historical context only.
+>
+> **Original status:** Decided · 2026-05-02
 > **Context:** AI #1, AI #3, AI #5 review of PR #29 flagged the
 > 200-line monolithic `rules/chat-history.md` as the rule the agent
 > revisited 12+ times during the 1.14.0 cycle — three independent

package/docs/contracts/adr-settings-sync-engine.md

@@ -0,0 +1,127 @@
+---
+stability: beta
+---
+
+# ADR — Settings sync engine: stdlib-only round-trip
+
+> **Status:** Decided · 2026-05-04
+> **Context:** Additive Settings Sync roadmap — review round 2
+> (Self-Review + AI Council, Anthropic + OpenAI) flagged the
+> 735-line `scripts/sync_yaml_rt.py` as potential NIH burden vs.
+> adopting `ruamel.yaml` as a third-party dependency.
+> **Builds on:** [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md)
+> § Sync rules — defines the additive-merge-with-user-line-preservation
+> contract this engine implements.
+
+## Decision
+
+`.agent-settings.yml` synchronization uses a **custom, stdlib-only
+round-trip parser + emitter** in [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py),
+not `ruamel.yaml` or any other third-party YAML library.
+
+The engine implements a narrow YAML subset (block-mappings, scalars,
+flow-list values, comments, CRLF/LF) that covers the full surface of
+`.agent-settings.yml` plus its template (`config/agent-settings.template.yml`).
+Out-of-subset YAML — anchors, aliases, multi-document streams, complex
+keys, nested flow mappings — is **not supported** and raises `ValueError`.
+
+The merge layer (additive walk, max-index insertion, scalar→section
+guard, healer for legacy `_user._user.foo` corruption, EOL
+normalization) sits on top of the parser and is custom regardless of
+the parser choice.
+
+## Why this was a real question
+
+Three options were on the table:
+
+1. **`ruamel.yaml` for parse + emit, custom merge on top.** Rejected.
+2. **`PyYAML` for parse, custom emitter for round-trip.** Rejected
+   earlier in the roadmap — PyYAML's parser drops comments and
+   formatting before the merger ever sees them.
+3. **Custom stdlib-only parser + emitter + merger.** Chosen.
+
+### Why ruamel.yaml does not match the contract
+
+The driving requirement from `layered-settings.md` is **verbatim
+user-line preservation** — every byte of every line in the user's
+file is preserved unless that line carries a key the merger is
+explicitly editing. Tests pin this contract by asserting byte-identity
+across two consecutive sync runs (`test_user_block_round_trip_is_idempotent`,
+`test_three_level_idempotent`).
+
+`ruamel.yaml` is a round-trip-aware library, not a verbatim one — it
+re-parses into an in-memory model and **re-emits** through its own
+emitter. This re-emit normalizes:
+
+| Behavior | ruamel.yaml | Custom engine |
+|---|---|---|
+| User-line bytes (whitespace, quoting, blanks) | re-emitted, may shift | preserved 1:1 |
+| Mixed CRLF/LF in user file | normalized to one EOL (typically platform default) | detected + normalized to the user's predominant EOL |
+| `personal: null` blocking template-section injection | requires custom merge logic regardless | scalar guard in `_merge_into` |
+| Legacy `_user._user.foo.bar` healer (one-off migration) | requires custom logic regardless | `heal_user_block` |
+| Synthetic header rendering for newly-inserted template keys | re-emits the entire file | only renders the new subtree |
+| Unknown user blocks at top level | preserved as data, but indent / quoting may shift on emit | preserved verbatim |
+| 3rd-party dependency in distribution package | +1 (`ruamel.yaml` + transitive `ruamel.yaml.clib`) | 0 |
+
+The rows where the libraries diverge are exactly the rows the test
+suite asserts on.
+
+### Cost analysis
+
+| Axis | Custom engine | ruamel.yaml |
+|---|---|---|
+| Lines of code | 735 (engine) + 335 (merge/heal) = 1070 | ~400 (parser+emitter saved) + 335 (merge/heal stays) + adapter glue = ~735 |
+| Net code saved | — | ~335 lines |
+| 3rd-party deps | 0 | +2 (`ruamel.yaml`, `ruamel.yaml.clib`) |
+| Runtime YAML surface | narrow (documented subset) | full YAML 1.2 |
+| Verbatim guarantee | yes | no |
+| Performance | irrelevant — cold-path, runs on profile change | irrelevant |
+
+The 335-line saving is real but offset by a stronger contract (verbatim)
+and a 0-dep posture. The package is a distribution-layer library
+(`composer.json` `type: library`, `package.json` thin manifest); it
+already restricts itself to stdlib for portability across consumer
+projects, several of which lock Python deps tightly.
+
+## Consequences
+
+- **Maintenance:** the engine must keep covering the YAML subset its
+  template + user files exercise. Any new template feature (e.g. a
+  block-style nested list) is a parser change, not a config change.
+- **Error surface:** YAML outside the subset (anchors, complex keys)
+  surfaces as a friendly `ValueError` from `_rt.sync()`, caught by
+  `sync_agent_settings.main` and turned into exit code 2 with a
+  user-readable message. Documented in
+  `tests/test_sync_agent_settings.py::test_malformed_user_yaml_exits_2_with_message`.
+- **Test debt:** `tests/test_sync_round_trip.py` (34 tests) and
+  `tests/test_sync_agent_settings.py` (15 tests) are the contract.
+  Any parser change must keep those green and is the entry point
+  for new fixtures under `tests/fixtures/sync_yaml_rt/`.
+
+## Revisit triggers
+
+This decision is revisited (new ADR with successor link) when **any**
+of the following holds:
+
+1. `.agent-settings.yml` schema gains a YAML feature outside the
+   supported subset (anchors, multi-doc, complex keys, nested flow
+   mappings) — the cost of extending the parser exceeds the cost of
+   adopting ruamel.
+2. The verbatim-preservation contract is relaxed (e.g. consumers
+   accept that sync can re-format) — the driver for the custom engine
+   is gone.
+3. The 0-dep posture for Python tooling is dropped at the package level
+   — the marginal cost of one more dep collapses.
+4. A maintenance bug surfaces in the engine that would have been
+   prevented by ruamel's mature spec coverage.
+
+## See also
+
+- [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md)
+  § Sync rules — the contract this engine implements.
+- [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) module
+  docstring — the supported YAML subset, listed exhaustively.
+- `tests/test_sync_round_trip.py` — verbatim, scalar-guard, healer,
+  CRLF, and synthetic-header pinning.
+- `tests/test_sync_agent_settings.py` — CLI integration, profile
+  override, malformed-input exit code.

package/docs/contracts/command-clusters.md

@@ -30,7 +30,7 @@ column 1 of this table.
 | `fix` | 1 | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder` |
 | `optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `optimize-agents` · `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` |
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
-| `chat-history` | 2 | `show` · `resume` · `clear` · `checkpoint` | `chat-history` (legacy status) · `chat-history-resume` · `chat-history-clear` · `chat-history-checkpoint` |
+| `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
 | `agents` | 2 | `audit` · `cleanup` · `prepare` | `agents-audit` · `agents-cleanup` · `agents-prepare` |
 | `memory` | 2 | `add` · `load` · `promote` · `propose` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory` |
 | `roadmap` | 2 | `create` · `execute` | `roadmap-create` · `roadmap-execute` |

package/docs/contracts/cross-wing-handoff.md

@@ -0,0 +1,133 @@
+---
+stability: beta
+---
+
+
+# Cross-Wing Handoff Contract
+
+> **Status:** active · **Stability:** beta · **Owner:** suite-closure Phase 3
+> · **Lint gate:** `task lint-handoffs` (CI)
+
+The four wings (Engineering, Product+Foundation, GTM+Growth,
+Money+Strategy+Ops) compose by handing off **typed artifacts** between
+senior-tier skills, not by sharing a runtime. This contract locks the
+shape of those handoffs so cognition clusters do not collide and the
+linter can detect drift mechanically.
+
+## § 1 — Purpose
+
+Typed composition across wings prevents three failure modes:
+
+1. **Cognition-cluster collision** — a Wing-3 skill silently re-implements
+   Wing-4 reasoning (e.g. funnel-analysis ad-hoc forecasting); the
+   handoff makes the dependency explicit.
+2. **Tier mismatch** — a senior skill delegates to a non-senior peer,
+   weakening the per-wing authoring floor; the linter blocks this.
+3. **Untyped artifact drift** — caller and callee disagree on the input
+   shape; the contract requires the delegated skill to declare its
+   `## Input` block so the linter can verify call-site compatibility.
+
+## § 2 — Anatomy
+
+A handoff has three named parts:
+
+```
+initiator-skill  →  delegated-skill(input-shape)  →  output-artifact
+   senior-tier         senior-tier                    declared in
+   in wing X           in wing Y (may = X)            delegated-skill's
+                                                      `## Output` block
+```
+
+- **initiator-skill** — the senior-tier skill that triggers the handoff;
+  declares the target in its `## Related Skills` § *WHEN NOT to use this*
+  routing list **or** as a `Composes` line in the procedure.
+- **delegated-skill** — the senior-tier skill that owns the cognition
+  step being handed off; MUST declare a `## Input` block listing the
+  shape the initiator must pass (named fields + 1-line type hint).
+- **output-artifact** — the named artifact from the delegated skill's
+  `## Output` block (e.g. `opportunity-tree.md`, `forecast-band.json`).
+
+A handoff that omits any of the three parts is incomplete and the
+linter rejects it.
+
+## § 3 — Worktree boundary
+
+Each handoff MAY run in a fresh git worktree when invoked through
+[`subagent-orchestration`](../../.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md)
+mode 6 (`do-in-worktrees`). Mode 6 is the state-machine layer — it
+declares when worktree isolation is mandatory (multi-step cross-wing
+chain, each step ≥30 min, branch state would otherwise leak between
+steps) and what handoff shape each step emits / consumes. The
+executor lives in
+[`using-git-worktrees`](../../.agent-src.uncompressed/skills/using-git-worktrees/SKILL.md)
+and
+[`finishing-a-development-branch`](../../.agent-src.uncompressed/skills/finishing-a-development-branch/SKILL.md);
+this contract does not duplicate that runtime.
+
+The boundary is **advisory** for chains that do not opt into mode 6:
+the handoff contract does not force isolation, but every handoff
+MUST not assume shared in-process state with the initiator. Write
+artifacts to disk; never pass live Python objects. Chains that opt
+into mode 6 promote the boundary from advisory to mandatory for the
+duration of the chain.
+
+## § 4 — Lint rules
+
+`scripts/lint_handoffs.py` enforces three rules over the handoff graph
+built from senior-tier skills. The graph is built from the
+`**WHEN to use this**` sub-block of each skill's `## Related Skills`
+section — those links are **composition (delegation) edges**. Links
+under `**WHEN NOT to use this**` are **alternative pointers** (peer
+cognition the user picks instead) and are NOT composition edges:
+mutual `A ↔ B` "use the other instead" pointers are intentional and
+MUST NOT be flagged.
+
+| Rule | Failure code | Description | Sub-block scope |
+|---|---|---|---|
+| **No cycles** | `handoff_cycle` | Composition graph must be a DAG. A→B→A or longer cycles fail. | WHEN-to-use only |
+| **No dangling references** | `handoff_dangling` | Every link must resolve to an existing skill file. | WHEN-to-use **and** WHEN-NOT |
+| **No tier mismatch** | `handoff_tier_mismatch` | A senior skill MAY only reference other senior skills (delegate to OR offer as alternative). | WHEN-to-use **and** WHEN-NOT |
+
+Optional rule (warning only, locked in Phase 6):
+
+| Rule | Code | Description |
+|---|---|---|
+| Input shape declared | `handoff_missing_input` | Delegated skill SHOULD declare `## Input`. Warning today; error after Phase 6. |
+
+Lint runs in CI between `task lint-skills` and `task test`. Output
+mirrors `lint_skills` (`file:line:reason`).
+
+## § 5 — Reference chains
+
+Three shipped chains across the suite illustrate the contract:
+
+### W3 launch chain — `positioning` → `messaging-architecture` → `gtm-launch`
+
+- `positioning` (H1) owns category framing.
+- `messaging-architecture` (H2) **composes** `positioning` — primary
+  message + supporting proofs derive from H1's point-of-view output.
+- `gtm-launch` (H3) **composes** `messaging-architecture` plus
+  `release-comms` (unified-senior-roles Block L) — launch sequencing
+  reuses the messaging stack.
+
+### W4 / W3 forecasting chain — `forecasting` → `forecast-accuracy`
+
+- `forecasting` (Wing-4 O2) owns construction cognition (top-down vs
+  bottom-up, confidence-band, retro-loop).
+- O2 ships an interface-first stub (`forecast-construction-shape` ADR)
+  before full implementation — locks the call shape early.
+- `forecast-accuracy` (Wing-3 H10) **composes** O2's interface for the
+  forecast-call loop. Contract drift = O2's break, not H10's.
+
+### W4 build-buy → org-design chain — `build-buy-partner` → `org-design`
+
+- `build-buy-partner` (P1) owns insource-vs-outsource reasoning.
+- `org-design` (Q1) **composes** `build-buy-partner` for insource-vs-
+  outsource shape — team-design follows the build-buy verdict.
+
+## See also
+
+- `.agent-src.uncompressed/rules/skill-quality.md` § Senior-Tier
+  Required Structure — defines the `## Related Skills` and `## Output`
+  blocks the contract reads.
+- `scripts/lint_handoffs.py` — mechanical enforcement.

package/docs/contracts/decision-trace-v1.md

@@ -0,0 +1,146 @@
+---
+stability: beta
+---
+
+# Decision-trace v1
+
+**Purpose.** Pin the JSON shape that `/implement-ticket` and `/work`
+runs emit when the user opts into trace surfacing. The trace is the
+audit substrate for the rule-interaction matrix
+([`rule-interactions.md`](rule-interactions.md)) and feeds the
+showcase-session capture pipeline
+([`outcome-baseline.md`](../../agents/contexts/outcome-baseline.md)).
+
+**Scope.** Defines the JSON envelope written next to a `WorkState`
+file when `decision_engine.surface_traces: true`. Does **not**
+specify how individual rules detect their own activation — that is
+the rule's own responsibility — only the shape of the report.
+
+Last refreshed: 2026-05-04.
+
+## Opt-in
+
+Off by default. Toggled in `.agent-settings.yml`:
+
+```yaml
+decision_engine:
+  surface_traces: true
+```
+
+The `/work` and `/implement-ticket` engines check this flag at phase
+boundaries and emit one trace file per phase when set.
+
+## File location
+
+```
+agents/state/work/<work-id>/decision-trace-<phase>.json
+```
+
+`work-id` matches the `WorkState` directory; `phase` is one of
+`refine`, `memory`, `analyze`, `plan`, `implement`, `test`, `verify`,
+`report`. Files are gitignored.
+
+## Envelope shape
+
+```json
+{
+  "schema_version": 1,
+  "work_id": "ABCD-1234-2026-05-04T12-34-56Z",
+  "phase": "implement",
+  "started_at": "2026-05-04T12:35:01Z",
+  "ended_at": "2026-05-04T12:38:42Z",
+  "confidence_band": "high",
+  "risk_class": "low",
+  "rules": [
+    {
+      "rule_id": "verify-before-complete",
+      "applied": true,
+      "skipped": false,
+      "conflicted_with": [],
+      "evidence_refs": ["agents/state/work/.../verify.log"]
+    }
+  ],
+  "memory": {
+    "asks": 3,
+    "hits": 2,
+    "ids": ["mem_42", "mem_57"]
+  },
+  "verify": {
+    "claims": 1,
+    "first_try_passes": 1
+  }
+}
+```
+
+Concerns and engines MUST treat unknown top-level keys as forward-
+compat extensions and MUST NOT raise on them.
+
+## Field semantics
+
+| Field | Meaning |
+|---|---|
+| `schema_version` | Always `1` for this contract. Major bump on breaking changes. |
+| `work_id` | Stable id of the WorkState directory. Allows cross-trace correlation across phases. |
+| `phase` | Engine phase that produced the trace. One of the eight phases above. |
+| `confidence_band` | One of `low` / `medium` / `high`. Heuristic defined below — derived from memory hits + ambiguity flags + verify evidence count. |
+| `risk_class` | One of `low` / `medium` / `high`. Per [`rule-interactions.md`](rule-interactions.md) — drives reviewer routing. |
+| `rules[].rule_id` | Stable rule id, matches the filename under `.agent-src.uncompressed/rules/` minus `.md`. |
+| `rules[].applied` | True if the rule's Iron Law fired and changed engine behaviour this phase. |
+| `rules[].skipped` | True if the rule was checked but produced no effect (no trigger match). |
+| `rules[].conflicted_with` | List of rule_ids that fired against this one. Reduction handled per `rule-interactions.md`. |
+| `rules[].evidence_refs` | Optional list of paths under `agents/state/` or `tests/` that back the `applied` claim. |
+| `memory.asks` | Count of `memory_retrieve` calls during the phase. |
+| `memory.hits` | Count of calls that returned ≥ 1 result. |
+| `memory.ids` | Stable memory entry ids returned. Bounded to ≤ 32 ids per phase; remainder dropped silently. |
+| `verify.claims` | Count of "done"-class claims the engine attempted this phase. |
+| `verify.first_try_passes` | Count of those claims that passed the verify gate without a re-prompt. |
+
+## Confidence-band heuristic
+
+```
+high:    memory.hits ≥ 2  AND  verify.first_try_passes == verify.claims  AND  no ambiguity flag
+medium:  memory.hits ≥ 1  OR   verify.first_try_passes ≥ 1
+low:     otherwise
+```
+
+Edge case: `verify.claims == 0` is not "high" by default — it folds
+into "medium" if at least one memory hit landed, "low" otherwise.
+
+## Risk-class heuristic
+
+Mirrors [`file-ownership-matrix.json`](file-ownership-matrix.json):
+the trace inherits the **maximum** risk class across all files the
+phase touched. If no files were touched (pure planning phase), risk
+is `low`.
+
+## Privacy floor
+
+- `memory.ids` carries opaque ids only — no entry bodies, no secrets.
+- `evidence_refs` carries paths only — no file contents.
+- `rules[].rule_id` is stable id, not free-form text.
+
+The visibility line surfaced to the user (Phase 4) consumes this file
+under the same floor.
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Engines MUST gate on `schema_version` and refuse unknown
+majors.
+
+## Cross-references
+
+- Personas (Architect, Risk-Officer) live in the package's persona
+  library under [`.agent-src.uncompressed/personas/`](../../.agent-src.uncompressed/personas/).
+  This contract does not duplicate them — when a future trace consumer
+  attributes a decision to one of those personas, the persona file is
+  the source of truth, not this envelope.
+- Rule-interaction matrix:
+  [`rule-interactions.md`](rule-interactions.md) (machine-readable
+  source: [`rule-interactions.yml`](rule-interactions.yml)).
+- Confidence-band heuristic is implemented in
+  `work_engine/scoring/decision_trace.py` and exercised by
+  `tests/work_engine/scoring/test_decision_trace_scoring.py`.
+- Outcome metrics consume `verify.first_try_passes`:
+  [`outcome-baseline.md`](../../agents/contexts/outcome-baseline.md).