@event4u/agent-config 5.10.1 → 6.0.0

package/docs/command-flows.md

@@ -0,0 +1,232 @@
+<!-- GENERATED by scripts/generate_command_flows.py — do not edit by hand. -->
+<!-- Source: src/flows/surface-map.yaml + src/flows/<flow>.yaml. Re-run: task generate-command-flows. -->
+
+# Command flows — the primary view
+
+> road-to-6.1.0 Step 9. Commands are **flow members**, not a flat list. The layered model is `Profile → Pack → Flow → Command → Skill → Rule`; this view answers *"what am I trying to do?"* before *"which command do I type?"*.
+
+> Every command is classified in `src/flows/surface-map.yaml` (coverage enforced by `scripts/lint_command_flow_coverage.py`). The four user-work flows carry rich definitions in `src/flows/<flow>.yaml`.
+
+**150 commands** across **10 surfaces** (4 user-work flows + 6 platform/domain surfaces).
+
+## User-work flows
+
+The developer story: **discovery → implementation → review → delivery**.
+
+### Discovery
+
+_Explore, plan, estimate, refine, and investigate before building. The "what should we build and how" front of the developer journey._
+
+**Entry points:** `feature/plan` · `bug-investigate` · `research`
+
+**Default path:** `feature/explore` → `feature/plan` → `estimate-ticket` → `refine-ticket`
+
+- `analyze-reference-repo` — Analyze an external reference repository (competitor, inspiration, peer) and produce a structured compariso…
+- `bug-investigate` — Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause
+- `estimate-ticket` — Estimate a Jira/Linear ticket before sprint planning — size + risk + split recommendation + uncertainty, si…
+- `feature` — Feature orchestrator — routes to explore, plan, refactor, roadmap, dev
+- `feature:explore` — Brainstorm and explore a feature idea before committing to a full plan
+- `feature:plan` — Interactively plan a feature — research, discuss, and create a structured feature document
+- `feature:refactor` — Refine and update an existing feature plan through interactive discussion
+- `feature:roadmap` — Generate implementation roadmap(s) from a feature plan and link them
+- `project-analyze` — Full project analysis — detect stack, inventory modules, audit docs, create missing contexts
+- `project-health` — Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything
+- `refine-ticket` — Refine a Jira/Linear ticket before planning — rewritten ticket + Top-5 risks + persona voices, orchestrates…
+
+### Implementation
+
+_Build it. The core "make the change" front — drive a prompt, ticket, or feature end-to-end through plan → implement → verify._
+
+**Entry points:** `work` · `implement-ticket` · `feature/dev` · `bug-fix`
+
+**Default path:** `work` → `review-changes` → `quality-fix` → `commit`
+
+- `bug-fix` — Plan and implement a bug fix — based on investigation, with quality checks and test verification
+- `e2e-heal` — Find, debug, and fix failing Playwright E2E tests
+- `e2e-plan` — Explore the application and create a structured E2E test plan in Markdown
+- `feature:dev` — Full 7-phase feature development workflow for complex features.
+- `implement-ticket` — Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — O…
+- `jira-ticket` — Read Jira ticket from branch name, analyze linked Sentry issues, implement feature or fix bug
+- `module:create` — Create a new module from .module-template with interactive setup
+- `tests` — Tests orchestrator — routes to create, execute
+- `tests:create` — Write meaningful tests for the current branch — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
+- `tests:execute` — Run the project's test suite — stack-adaptive (pest / phpunit / vitest / jest / pytest / …)
+- `update-form-request-messages` — Sync the messages() method of a FormRequest class — add missing entries, link them to language keys, and cl…
+- `work` — Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Op…
+
+### Review
+
+_Check it. Self-review, judge, quality-fix, and threat-model a change before it ships._
+
+**Entry points:** `review-changes` · `judge`
+
+**Default path:** `review-changes` → `judge` → `quality-fix` → `threat-model`
+
+- `fix:ci` — Fetch CI errors from GitHub Actions and fix them
+- `judge` — Judge orchestrator — routes to solo, steps, on-diff
+- `judge:on-diff` — Run a single change through an implementer→judge loop with a two-revision ceiling, then hand back to the user
+- `judge:solo` — Run a standalone judge on an existing diff or code change — no implementer, no revision loop, verdict only
+- `judge:steps` — Execute an ordered plan step by step with a judge gate between steps — stops on first failed verdict
+- `quality-fix` — Run quality pipeline (PHP and/or JS/TS) and fix all errors — auto-detects language from changed files
+- `review-changes` — Self-review local changes before creating a PR — dispatches to five specialized judges (bug, security, test…
+- `threat-model` — Run a pre-implementation threat model on a proposed change — enumerates abuse cases, trust boundaries, and…
+
+### Delivery
+
+_Ship it. Commit in logical chunks, open the PR, answer review comments, and prepare the branch for review._
+
+**Entry points:** `commit` · `pr/create` · `prepare-for-review`
+
+**Default path:** `commit` → `pr/create` → `fix/pr-comments`
+
+- `git-commit` — Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits
+- `git-commit-in-chunks` — Stage and commit all uncommitted changes in logical chunks WITHOUT confirmation — sibling of /commit for au…
+- `fix` — Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, pr-bot-comments, pr-develope…
+- `fix:portability` — Find and fix project-specific references in shared .augment/ package files
+- `fix:pr-bot-comments` — Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR
+- `fix:pr-comments` — Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR
+- `fix:pr-developer-comments` — Fix and reply to human reviewer comments on a GitHub PR
+- `fix:refs` — Find and fix broken cross-references in .augment/ and agents/ files
+- `fix:seeder` — Scan seeder data files for broken foreign key references — find constants used without getReference() and f…
+- `git-pr-create` — Create a GitHub PR with structured description from Jira ticket and code changes
+- `git-pr-create-description-only` — Generate a PR description as a copyable markdown block — used standalone or by create-pr
+- `prepare-for-review` — Prepare a PR branch for local review — updates main and merges the full branch chain so the branch is up to…
+
+## Platform & domain surfaces
+
+### Product-surface features
+
+_Deliberately-started features — not daily flow members, never buried as skills._
+
+- `challenge-me` — Challenge-me orchestrator — routes to vision, with-docs
+- `challenge-me:vision` — Stress-test a plan or idea by one-question-at-a-time interview until 95% confidence — emits a copyable Mark…
+- `challenge-me:with-docs` — Doc-aware /challenge-me — 95%-confidence interview with session glossary vs CONTEXT.md, load-bearing claim-…
+- `council` — Council orchestrator — routes to default, pr, design, optimize, analysis, debate
+- `council:analysis` — Run the council on a local analysis output (project-analyze, audit script, codebase scan) — critiques the a…
+- `council:debate` — Multi-round council debate with progressive cost disclosure — each member produces a position, then rebuts…
+- `council:default` — Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <inpu…
+- `council:design` — Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rol…
+- `council:optimize` — Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output…
+- `council:pr` — Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-o…
+- `grill-me` — Alias for /challenge-me — interactive grill-style interview that sharpens a fuzzy plan/idea into a copyable…
+- `research` — Preliminary research scaffolder — pick objects, define fields, emit `outline.yaml` + `fields.yaml` for down…
+- `research:deep` — Read `outline.yaml`, research each item in batches, write per-item JSON validated against the project-local…
+- `research:report` — Summarise per-item JSON results from `/research:deep` into `report.md`. Agent renders directly + emits an o…
+- `roadmap` — Roadmap orchestrator — routes to create (authoring) and process-step / process-phase / process-full (autono…
+- `roadmap:ai-council` — Challenge a roadmap with the AI council (deep tier) and refactor from convergence findings. Wraps `/council…
+- `roadmap:create` — Interactively create a new roadmap file in agents/roadmaps/
+- `roadmap:process-full` — Autonomously process every open step across every phase of a roadmap until the file is fully closed. Larges…
+- `roadmap:process-phase` — Autonomously process every open step in the next or current phase of a roadmap, then stop. Default executio…
+- `roadmap:process-step` — Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /road…
+
+### Platform surface — `agent-admin`
+
+_The system/admin surface (NOT a flow): memory · analytics · governance · config · introspection, reached on demand._
+
+- `agents` — Agent-layer orchestrator — routes to init, optimize, audit. Covers AGENTS.md and its multi-tool stubs (CLAU…
+- `agents:audit` — Audit agent infrastructure — token overhead, rule triggers, AGENTS.md health, Capability-over-Structure adh…
+- `agents:init` — Initialize the agent layer for a consumer project — creates AGENTS.md and .github/copilot-instructions.md f…
+- `agents:optimize` — Refactor AGENTS.md to the Thin-Root contract (caps, pointer ratio, capability bullets, emergency-triage) an…
+- `agents:user` — User-persona file (.agent-user.md) — interview, render, and maintain who the user is and how they want to b…
+- `agents:user-accept` — Apply a buffered observation to .agent-user.md after explicit user confirmation; bumps last_updated and dro…
+- `agents:user-init` — Interactive interview that creates the project-root .agent-user.md from the locked v1 schema (name, languag…
+- `agents:user-review` — List buffered observations from .agent-user.observations.jsonl with numbered options to inspect or accept i…
+- `agents:user-show` — Read-only render of .agent-user.md — prints the persona summary the host agent loads at session start.
+- `agents:user-update` — Open .agent-user.md in the user's IDE for manual edit; validates schema and 100-line cap on save.
+- `analytics` — Analytics orchestrator — routes to show, prune. Local-only workspace event log under `~/.event4u/agent-conf…
+- `analytics:prune` — Drop events older than the 90-day retention window from the local analytics log. Atomic and idempotent.
+- `analytics:show` — Render top prompts, launcher → completion rate per role, average session length, and knowledge-source usage…
+- `chat-history` — Chat-history orchestrator — routes to show, import, learn
+- `chat-history:import` — Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit…
+- `chat-history:learn` — Pick a prior chat-history session and mine it for project-improving learnings — runs learning-to-rule-or-sk…
+- `chat-history:show` — Show the status of the persistent chat-history log — file size, entry count, header fingerprint, age, and t…
+- `check-current-md`
+- `condense` — Condense .md files from .agent-src.uncondensed/ into telegraph format and write to dist/agent-src/
+- `context` — Context orchestrator — routes to create, refactor
+- `context:create` — Analyze a codebase area and create a structured context document
+- `context:refactor` — Analyze, update, and extend an existing context document
+- `cost-report` — Capture token cost from the active Claude Code session, append to the local sessions store, and surface the…
+- `knowledge` — Knowledge orchestrator — routes to ingest, list, forget. Local-only file ingestion into the agent memory na…
+- `knowledge:cross-repo` — Targeted, read-only retrieval over opted-in linked-project siblings (ADR-032 Option A). Pulls a shared type…
+- `knowledge:forget` — Drop a knowledge ingest from `agents/memory/knowledge/` by id prefix. Atomic, no partial state. Pinning pro…
+- `knowledge:ingest` — Walk a local path (folder, .zip, single file), redact PII + secrets, chunk to 2 KB markdown, and persist in…
+- `knowledge:list` — List existing knowledge ingests in `agents/memory/knowledge/` (table or JSON); pin / unpin by id prefix to…
+- `memory` — Memory orchestrator — routes to add, load, mine-session, promote, propose
+- `memory:add` — Interactively add a validated entry to an engineering-memory file (domain-invariants, architecture-decision…
+- `memory:learn-low-impact` — Preview validated low-impact entries that would be upstreamed to the package seed (default `--preview`); `-…
+- `memory:load` — Load ALL curated entries of a given memory type into the current context — opt-in full load for deep analys…
+- `memory:mine-session` — Mine the active session transcript for memory signals (corrections, preferences, decisions, recurring patte…
+- `memory:promote` — Promote an intake signal (or provisional proposal) into a curated memory entry — opens a PR and runs the ad…
+- `memory:propose` — Append a provisional memory signal to the intake stream — the universal fallback for any producer (human or…
+- `module` — Module orchestrator — routes to create, explore
+- `module:explore` — Explore a module — load its structure, docs, and context into the current conversation
+- `optimize` — Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters
+- `optimize-prompt` — Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL…
+- `optimize:agents-dir` — Manage the agents/ directory — scaffold, folder-audit, fix. Single command with three modes (--scaffold / -…
+- `optimize:augmentignore` — Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifact…
+- `optimize:rtk` — Create or optimize project-local rtk filters based on the actual toolchain
+- `optimize:skills` — Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto…
+- `orchestrate` — Run a YAML pipeline defined under `.agent-config/orchestrations/` — chains personas / skills / commands / s…
+- `override` — Override orchestrator — routes to create, manage
+- `override:create` — Creates a project-level override for a shared skill, rule, or command.
+- `override:manage` — Reviews, updates, and refactors existing project-level overrides.
+- `package-reset` — /package-reset
+- `package-test` — /package-test
+- `profile` — Session-profile orchestrator — activate / deactivate / show the active packs for this session (recommendati…
+- `profile:activate` — Activate a session profile — surface only the named profile/pack closure plus core artefacts, no persistence
+- `profile:deactivate` — Deactivate the session profile — clear the overlay (or drop named packs) so the full surface returns
+- `profile:show` — Show the active session profile — active packs and surfaced/hidden command+skill counts (observability surf…
+- `review-routing` — Compute reviewer roles and matched historical bug patterns for the current diff, using project-local owners…
+- `rule-compliance-audit` — Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules
+- `set-cost-profile` — Change the rule_loading_tier in .agent-settings.yml — shows each profile's meaning and applies the selection
+- `skill` — Single-skill orchestrator — routes to preview. Non-destructive "what will this skill do?" before you run it.
+- `skill:preview` — Non-destructive preview of a skill — its declared steps, execution type, allowed tools, and file/command ta…
+- `skills` — Skill discovery orchestrator — routes to discover. Local, explained skill recommendations over the catalog…
+- `skills:discover` — Recommend skills for a role — ranked by four explained classes (most-useful-for-role, related-to-current-ta…
+- `sync-agent-settings` — Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user…
+- `sync-gitignore` — Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserve…
+- `sync-gitignore:fix` — Scrub legacy pre-`/agents/` patterns from the consumer's .gitignore (inside or outside the managed block) a…
+- `upstream-contribute` — Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package
+
+### Domain flow — media
+
+_AI image + video pipeline._
+
+- `image` — Character-image fidelity orchestrator — analyse, create, and verify a character image against its canon. Ro…
+- `image:analyse` — Analyse a character image down to the smallest mole and diff it against a canon — per-feature spec, OCR tat…
+- `image:create` — Generate a character image to spec — assemble a max-fidelity, anchors-first prompt from a Canon Spec; gover…
+- `image:verify` — Verify a candidate render against its canon — run the analyser in loop mode, emit the gate verdict + remain…
+- `video` — Video-creation orchestrator — Hollywood-level AI video pipeline. Routes to from-script, from-song, scene, s…
+- `video:from-script` — Drive a script end-to-end through the AI video pipeline — scenes → blueprint → image → operator pick → moti…
+- `video:from-song` — Music-video from a song + reference images — accept or derive a timed scene script, optional character-lock…
+- `video:scene` — Render a single scene from a one-line idea — scene-expander → blueprint → image → operator pick → motion →…
+- `video:stitch` — Re-stitch existing clips in `<project>/scenes/*/` after operator edits — no re-render. ffmpeg concat driven…
+- `video:storyboard` — Image-only storyboard — script → scenes → blueprint → image render → contact-sheet PNG via ffmpeg montage.…
+
+### Domain flow — marketing
+
+_Ghostwriter + post-as voice pipeline._
+
+- `ghostwriter` — Ghostwriter cluster — fetch, write, list, show, and delete public-figure voice profiles (the third voice pr…
+- `ghostwriter:delete` — Hard-delete a ghostwriter profile at agents/reference/ghostwriter/<slug>.md after a two-step confirmation.…
+- `ghostwriter:fetch` — Build or refresh a public-figure voice profile under agents/reference/ghostwriter/ from a URL or bare name;…
+- `ghostwriter:list` — List captured ghostwriter profiles under agents/reference/ghostwriter/ as a numbered table with confidence,…
+- `ghostwriter:show` — Render a single ghostwriter profile in full — identity, style fingerprint, voice samples, taboos, source UR…
+- `ghostwriter:write` — Draft a markdown post in the voice of a captured public-figure ghostwriter profile; appends the mandatory n…
+- `post-as` — Consumer-facing write entry points — :me drafts in the maintainer's own voice from .agent-user.md (no discl…
+- `post-as:ghostwriter` — Thin alias for /ghostwriter:write — drafts a copyable markdown post in a captured public-figure voice with…
+- `post-as:me` — Draft a copyable markdown post in the maintainer's own voice (style source = .agent-user.md.voice_sample).…
+
+### Domain flow — fun
+
+_Recreational packs._
+
+- `prediction-pool` — Fill a prediction pool (kicktipp, football/basketball WM): optimize expected points under the rules, enter…
+
+### Session surface
+
+_Handoff / status / mode — conversation lifecycle._
+
+- `agent-handoff` — Generate a context summary for continuing work in a fresh chat. Replaces the session system.
+- `agent-status` — Show current conversation stats — message count, token costs, task progress, next freshness check.
+- `mode` — Set the active role mode — prints the contract, lists default skills, and refuses work outside the contract…

package/docs/contracts/CHANGELOG-conventions.md

@@ -52,7 +52,7 @@ Tests: NNNN (+M since X.Y.(Z-1))
 ```
 
 The test-count line is enforced for any release that ships changes to
-`scripts/`, `internal/workers/`, or `.agent-src/` content; it can be omitted for
+`scripts/`, `internal/workers/`, or `dist/agent-src/` content; it can be omitted for
 pure-docs releases.
 
 ## What counts as breaking
@@ -72,7 +72,7 @@ A change is **breaking** (and MUST appear under `### BREAKING CHANGES`
    [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) (tool shape, prompt
    ids, resource URIs).
 4. **Generated tree shape** — removing or renaming top-level
-   directories under `.agent-src/`, `.augment/`, `.claude/`,
+   directories under `dist/agent-src/`, `.augment/`, `.claude/`,
    `.cursor/`, `.clinerules/`, or `.windsurfrules`.
 5. **Settings keys** — removing / renaming a key in
    `.agent-settings.yml` that consumer projects may rely on. Adding a

package/docs/contracts/STABILITY.md

@@ -147,7 +147,7 @@ for the contract and the transitional allowlist.
   or relocated to `contexts/` between releases as long as the global
   and per-rule caps still hold.
 - The condensed-vs-uncondensed delta. The CI gate runs against the
-  shipped `.agent-src/` (condensed) directory; the uncondensed
+  shipped `dist/agent-src/` (condensed) directory; the uncondensed
   source size is informational only.
 
 ## See also

package/docs/contracts/adoption-signal-floor.md

@@ -7,7 +7,7 @@ roadmap_ref: road-to-adoption-proof-and-ci-green.md
 # Adoption Signal Floor
 
 > **Status** · v0 / beta · 2026-05-26. Phase D Step 1 of
-> [`road-to-adoption-proof-and-ci-green.md`](../../agents/roadmaps/road-to-adoption-proof-and-ci-green.md).
+> the `road-to-adoption-proof-and-ci-green` roadmap (archived).
 > Defines the privacy-floor for adoption-signal collection — what
 > the package may measure, what it may NOT, and the opt-in gate
 > consumer-side telemetry would need to clear before it could ship.
@@ -99,7 +99,7 @@ Re-audit on each of:
 
 ## See also
 
-- [`scripts/adoption_snapshot.py`](../../scripts/adoption_snapshot.py)
+- [`scripts/adoption_snapshot.py`](../../src/scripts/adoption_snapshot.py)
   — the collector for the four public signals.
 - `domain-safety-pii` rule — the redaction floor any future opt-in
   telemetry would inherit.

package/docs/contracts/adr-architectural-consensus-mechanism.md

@@ -62,7 +62,7 @@ The final acceptance gate (lint going from warn-only to fail-the-build) is defer
 ## Related
 
 - Origin: [`agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md`](../../agents/runtime/council/sessions/2026-05-14-v2-analysis/feedback/01-bus-factor-and-consensus.md) <!-- council-ref-allowed: ADR decision trace -->
-- Mechanical scripts: [`scripts/skill_collision_clusters.py`](../../scripts/skill_collision_clusters.py), [`scripts/score_skill_selection.py`](../../scripts/score_skill_selection.py)
+- Mechanical scripts: [`scripts/skill_collision_clusters.py`](../../src/scripts/skill_collision_clusters.py), [`scripts/score_skill_selection.py`](../../src/scripts/score_skill_selection.py)
 - Sibling decision: [`docs/contracts/rule-router.md`](rule-router.md) — the routing layer the ADR feeds
 - Sibling decision: [`docs/contracts/multi-tool-projection-fidelity.md`](multi-tool-projection-fidelity.md) — Phase 4 of the same roadmap
 - Standing skill: [`.augment/skills/ai-council/SKILL.md`](../../.augment/skills/ai-council/SKILL.md) — the explicit-opt-in path for the rare moments tier C is invoked

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

@@ -128,7 +128,7 @@ sequence, just across three files.
 1. Create the three new rules under `.agent-src.uncondensed/rules/`.
 2. Delete `.agent-src.uncondensed/rules/chat-history.md`.
 3. Run `bash scripts/condense.sh --sync` to project the change into
-   `.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`,
+   `dist/agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`,
    `.windsurfrules`.
 4. Update every cross-reference (~30 files) — `check-refs` is the
    gate.

package/docs/contracts/adr-gtm-context-spine.md

@@ -18,7 +18,7 @@ keep-beta-until: 2026-08-12
 The context-spine adds **three Wing-3-specific slots** under
 `agents/context-spine/`: `channel-stage`, `funnel-stage`,
 `customer-segment`. The schema enum in
-[`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json)
+[`scripts/schemas/skill.schema.json`](../../src/scripts/schemas/skill.schema.json)
 extends from `{product, team, repo}` to
 `{product, team, repo, channel-stage, funnel-stage, customer-segment}`.
 
@@ -107,7 +107,7 @@ Three signals that this decision is wrong and the ADR needs revisiting:
 
 - [`context-spine.md`](context-spine.md) § 2 (slot table — extended),
   § 5 (slot-add policy — wing-bounded extension clause).
-- [`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json)
+- [`scripts/schemas/skill.schema.json`](../../src/scripts/schemas/skill.schema.json)
   — `context_spine.items.enum` extended in this ADR.
 - `agents/roadmaps/` § Block G — the authorising roadmap (archived
   after merge; this ADR is the durable record).

package/docs/contracts/adr-install-user-type-axis.md

@@ -25,7 +25,7 @@ The `user-types/` directory holds **seven** YAML configs — `consultant`,
 `creator`, `developer`, `finance`, `founder`, `gtm`, `ops` — matching
 every value already in active use across 32 skills' frontmatter. Adding
 an eighth value requires a new YAML plus a frontmatter audit (Phase 4).
-Schema: [`scripts/schemas/user-type-axis.schema.json`](../../scripts/schemas/user-type-axis.schema.json).
+Schema: [`scripts/schemas/user-type-axis.schema.json`](../../src/scripts/schemas/user-type-axis.schema.json).
 
 ## Why this is distinct from the review-lens axis
 
@@ -70,7 +70,7 @@ Three options were considered:
   accept `--user-type=<id>`. Validation against `user-types/*.yml`
   stems happens in one place (`install.py`) and the bash entry-point
   delegates. Invalid values fail fast with a non-zero exit.
-- `config/agent-settings.template.yml` keeps a commented
+- `src/config/agent-settings.template.yml` keeps a commented
   `personal.user_type:` stub documenting the seven valid values.
 - The existing `--interactive` flag (legacy `.agent-config.local.json`
   stub) is preserved for backward compat; the new flag is the
@@ -80,7 +80,7 @@ Three options were considered:
   `recommended_for_user_types` MUST have a corresponding YAML, and
   every YAML SHOULD be consumed by at least one skill. The audit ships
   as a CI gate (`task lint-user-type-axis` →
-  [`scripts/audit_user_type_axis.py`](../../scripts/audit_user_type_axis.py)).
+  [`scripts/audit_user_type_axis.py`](../../src/scripts/audit_user_type_axis.py)).
   Initial sweep at Phase 4 close: 7 declared / 7 used / 0 orphans / 0
   unused — coverage is clean, no rename or backfill needed. Report:
   [`agents/runtime/reports/user-type-axis-audit.md`](../../agents/runtime/reports/user-type-axis-audit.md).

package/docs/contracts/adr-layout.md

@@ -30,7 +30,7 @@ docs/adrs/
 
 `<area>` is a kebab-case stem matching one of:
 
-- An entry in the canonical area inventory (see [`scripts/audit_adr_coverage.py`](../../scripts/audit_adr_coverage.py) `AREAS`).
+- An entry in the canonical area inventory (see [`scripts/audit_adr_coverage.py`](../../src/scripts/audit_adr_coverage.py) `AREAS`).
 - A new area added to that inventory in the same PR.
 
 Reserved areas (bootstrap pass — step-11 Phase 4 Step 3):
@@ -103,6 +103,6 @@ The skill's template, numbering logic, and validation hooks are identical for bo
 
 - [`docs/adrs/cost/0001-hard-stop-hook.md`](../adrs/cost/0001-hard-stop-hook.md) — first per-area ADR (bootstrap).
 - [`docs/decisions/INDEX.md`](../decisions/INDEX.md) — flat surface index.
-- [`scripts/audit_adr_coverage.py`](../../scripts/audit_adr_coverage.py) — coverage gate.
-- [`scripts/adr/regenerate_index.py`](../../scripts/adr/regenerate_index.py) — index regenerator (works on both surfaces; pass `--dir`).
+- [`scripts/audit_adr_coverage.py`](../../src/scripts/audit_adr_coverage.py) — coverage gate.
+- [`scripts/adr/regenerate_index.py`](../../src/scripts/adr/regenerate_index.py) — index regenerator (works on both surfaces; pass `--dir`).
 - `step-11-ruflo-parity` Phase 4 — origin.

package/docs/contracts/adr-mcp-runtime.md

@@ -13,7 +13,7 @@ stability: stable
 
 The MCP server at `scripts/mcp_server/` runs on **Python 3.11+** using the
 official Anthropic **`mcp` Python SDK** (PyPI; pinned to `mcp==1.27.1`
-per [`scripts/mcp_server/requirements.txt`](../../scripts/mcp_server/requirements.txt)).
+per [`scripts/mcp_server/requirements.txt`](../../src/scripts/mcp_server/requirements.txt)).
 **FastMCP** (the higher-level decorator wrapper) and the **MCP TypeScript SDK**
 are explicitly rejected for this surface.
 
@@ -48,14 +48,14 @@ re-litigated every time a contributor read `scripts/mcp_server/server.py`.
 
 Evidence the decision is already realised in code:
 
-- [`scripts/mcp_server/server.py`](../../scripts/mcp_server/server.py) — uses
+- [`scripts/mcp_server/server.py`](../../src/scripts/mcp_server/server.py) — uses
   `mcp.server.Server`, `mcp.server.stdio.stdio_server`, `InitializationOptions`
   directly (no FastMCP decorators).
-- [`scripts/mcp_server/__init__.py`](../../scripts/mcp_server/__init__.py) —
+- [`scripts/mcp_server/__init__.py`](../../src/scripts/mcp_server/__init__.py) —
   pins `__version__` and declares stability/contract pointer.
-- [`scripts/mcp_server/requirements.txt`](../../scripts/mcp_server/requirements.txt)
+- [`scripts/mcp_server/requirements.txt`](../../src/scripts/mcp_server/requirements.txt)
   — `mcp==1.27.1`, no FastMCP, no Node tooling.
-- [`scripts/mcp_setup.sh`](../../scripts/mcp_setup.sh) — onboarding writes
+- [`scripts/mcp_setup.sh`](../../src/scripts/mcp_setup.sh) — onboarding writes
   the Claude Desktop config snippet against `python -m scripts.mcp_server`.
 
 ## Tool surface (Phase 1 scoping)
@@ -63,7 +63,7 @@ Evidence the decision is already realised in code:
 Locked separately by [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) Phase 4
 amendment. The current ALLOWLIST is exactly two tools, registered as a
 hardcoded module-level tuple in
-[`scripts/mcp_server/tools.py`](../../scripts/mcp_server/tools.py):
+[`scripts/mcp_server/tools.py`](../../src/scripts/mcp_server/tools.py):
 
 | Tool | Mode | Source |
 |---|---|---|
@@ -73,7 +73,7 @@ hardcoded module-level tuple in
 No `push`, `merge`, `commit`, or prod-write surface is exposed. The
 unimplemented-tool envelope from
 [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) governs the rest of
-the [`consumer_tool_catalog.json`](../../scripts/mcp_server/consumer_tool_catalog.json)
+the [`consumer_tool_catalog.json`](../../src/scripts/mcp_server/consumer_tool_catalog.json)
 entries.
 
 `agent-config init`, `agent-config skills list`, and
@@ -92,7 +92,7 @@ That shape was rejected in favour of two existing entrypoints, both
 already shipped:
 
 - **One-liner onboarding:** `task mcp:setup` runs
-  [`scripts/mcp_setup.sh`](../../scripts/mcp_setup.sh) — creates
+  [`scripts/mcp_setup.sh`](../../src/scripts/mcp_setup.sh) — creates
   `.venv-mcp/`, installs `mcp`, and prints the Claude Desktop JSON snippet
   the operator pastes into
   `~/Library/Application Support/Claude/claude_desktop_config.json`

package/docs/contracts/adr-prompt-driven-execution.md

@@ -72,7 +72,7 @@ gate solves this with a **deterministic, heuristic-only scorer** at the
 `refine` boundary.
 
 **Single source of truth:**
-[`scripts/work_engine/scoring/confidence.py`](../../.agent-src/templates/scripts/work_engine/scoring/confidence.py).
+[`scripts/work_engine/scoring/confidence.py`](../../dist/agent-src/templates/scripts/work_engine/scoring/confidence.py).
 The rubric, dimension definitions, weights, and band thresholds live in
 that module. SKILL.md, this ADR, and `implement-ticket-flow.md` cite
 the module — they do **not** re-derive the values. Tuning happens by

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

@@ -17,12 +17,12 @@ keep-beta-until: 2026-08-12
 ## 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),
+round-trip parser + emitter** in [`scripts/sync_yaml_rt.py`](../../src/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`).
+`.agent-settings.yml` plus its template (`src/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`.
 
@@ -120,7 +120,7 @@ of the following holds:
 
 - [`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
+- [`scripts/sync_yaml_rt.py`](../../src/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.

package/docs/contracts/adr-user-types-axis.md

@@ -40,7 +40,7 @@ as a first-class directory mirroring the persona pipeline:
 
 - Source dir: `.agent-src.uncondensed/user-types/`
 - Schema doc: [`user-type-schema`](user-type-schema.md) — 7-section spine, ≤ 120 lines
-- JSON schema: [`scripts/schemas/user-type.schema.json`](../../scripts/schemas/user-type.schema.json)
+- JSON schema: [`scripts/schemas/user-type.schema.json`](../../src/scripts/schemas/user-type.schema.json)
 - Linter: `scripts/skill_linter.py § lint_usertype`
 - CLI surface: `/refine-ticket --user-type=<id>` (single id in v1)
 - Composition: `--user-type=` and `--personas=` compose orthogonally
@@ -61,7 +61,7 @@ as user-types — existing personas stay as personas.
 - One new directory (`user-types/`) projected the same way `personas/`
   is
 - Three seed files at merge time; consumer projects add their own
-  domain-specific user-types under `.agent-src/user-types/`
+  domain-specific user-types under `dist/agent-src/user-types/`
 
 **Locked v1 boundaries:**
 

package/docs/contracts/adr-wing4-context-spine.md

@@ -18,7 +18,7 @@ keep-beta-until: 2026-08-12
 The context-spine adds **three Wing-4-specific slots** under
 `agents/context-spine/`: `fiscal-period`, `org-stage`,
 `regulatory-regime`. The schema enum in
-[`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json)
+[`scripts/schemas/skill.schema.json`](../../src/scripts/schemas/skill.schema.json)
 extends from
 `{product, team, repo, channel-stage, funnel-stage, customer-segment}`
 to additionally include
@@ -119,7 +119,7 @@ re-opens the slot-sprawl risk and needs a separate ADR.
   § 5 (slot-add policy — wing-scoped track).
 - [`adr-gtm-context-spine.md`](adr-gtm-context-spine.md) — Wing-3
   reference ADR this one composes against.
-- [`scripts/schemas/skill.schema.json`](../../scripts/schemas/skill.schema.json)
+- [`scripts/schemas/skill.schema.json`](../../src/scripts/schemas/skill.schema.json)
   — `context_spine.items.enum` extended in this ADR.
 - [`.agent-src.uncondensed/rules/skill-quality.md`](../../.agent-src.uncondensed/rules/skill-quality.md)
   § Senior-Tier Required Structure — the four blocks every senior

package/docs/contracts/agent-user-schema.md

@@ -38,7 +38,7 @@ last_updated: "2026-05-15" # YYYY-MM-DD — bumped on every accepted change
 
 `role` is an **unordered** YAML block-style list. Order carries no meaning
 (no "primary" role). The seeded enum mirrors `SEED_PROFILE_IDS` in
-[`scripts/config/profiles.py`](../../scripts/config/profiles.py):
+[`scripts/config/profiles.py`](../../src/scripts/config/profiles.py):
 `founder`, `developer`, `content_creator`, `agency`, `finance`, `ops`.
 Free-form additions are accepted (forward-compatibility) — closed
 validation lives in the wizard / settings GUI, not in the loader.
@@ -54,7 +54,7 @@ enforced by `/agents user accept` and `/agents user update`.
 |---|---|---|
 | `version` | yes | Schema version. v1 is the only valid value today. |
 | `identity.name` | yes | How the agent addresses the user (full name or shorthand — user's choice). |
-| `language` | yes | Primary language; the agent mirrors per [`language-and-tone`](../../.agent-src/rules/language-and-tone.md). |
+| `language` | yes | Primary language; the agent mirrors per [`language-and-tone`](../../dist/agent-src/rules/language-and-tone.md). |
 | `role` | no | Unordered list of role labels (may be empty). Drives reviewer-voice selection and persona pairing when populated. Seeded enum mirrors `SEED_PROFILE_IDS`; additional free-form entries accepted; each present entry must be non-empty. The setup wizard never blocks a save on it. |
 | `style.pace` | yes | `pragmatic` (default), `thorough` (more verification), or `rapid` (shorter replies). |
 | `voice_sample` | no | Optional representative paste — sharpens mirror-back and tone calibration when present; may be empty. The setup wizard never blocks a save on it. |
@@ -151,7 +151,7 @@ and the buffer.
 
 `.agent-user.md` and `.agent-user.observations.jsonl` are added to the
 package-managed `.gitignore` block
-([`config/gitignore-block.txt`](../../config/gitignore-block.txt)) and
+([`src/config/gitignore-block.txt`](../../config/gitignore-block.txt)) and
 ignored by default. A `--shared` opt-in to commit `.agent-user.md` is
 deferred — only the doc note lands in v1. The observation buffer is
 **never** shared.
@@ -165,6 +165,6 @@ Copy it to the project root as `.agent-user.md` and edit, or run
 
 ## See also
 
-- [`language-and-tone`](../../.agent-src/rules/language-and-tone.md) — language-mirroring rule the loader feeds.
-- [`agents-md-thin-root`](../../.agent-src/skills/agents-md-thin-root/SKILL.md) — Thin-Root contract that this file complements (user-state vs project-state).
-- [`ghostwriter-schema`](ghostwriter-schema.md) — sibling voice primitive for **external public-figure** voices (`/ghostwriter:write`, mandatory disclosure footer). `.agent-user.md` covers the maintainer's **own** voice (`/post-as:me`, no footer); the three-primitive model is summarised in [`personas/README.md § See also — sibling voice primitives`](../../.agent-src/personas/README.md).
+- [`language-and-tone`](../../dist/agent-src/rules/language-and-tone.md) — language-mirroring rule the loader feeds.
+- [`agents-md-thin-root`](../../dist/agent-src/skills/agents-md-thin-root/SKILL.md) — Thin-Root contract that this file complements (user-state vs project-state).
+- [`ghostwriter-schema`](ghostwriter-schema.md) — sibling voice primitive for **external public-figure** voices (`/ghostwriter:write`, mandatory disclosure footer). `.agent-user.md` covers the maintainer's **own** voice (`/post-as:me`, no footer); the three-primitive model is summarised in [`personas/README.md § See also — sibling voice primitives`](../../dist/agent-src/personas/README.md).

package/docs/contracts/agents-md-tech-stack.md

@@ -13,7 +13,7 @@ is the long-form reference.
 ## Recommended ingestion path for non-text formats
 
 PDF, DOCX, XLSX, PPTX, EPUB, image, and audio inputs route through the
-[`markitdown`](../../.agent-src/skills/markitdown/SKILL.md) skill — a
+[`markitdown`](../../dist/agent-src/skills/markitdown/SKILL.md) skill — a
 thin markdown-only wrapper over Microsoft's MIT-licensed
 `markitdown-mcp` server (peer-side install, zero Python in this
 package). The skill ships the four-layer security defense:
@@ -71,5 +71,5 @@ Malice Floor for the full rule.
   architecture and cloud-bundle pipeline
 - [`.agent-src.uncondensed/rules/skill-quality.md`](../../.agent-src.uncondensed/rules/skill-quality.md)
   — Structural Malice Floor
-- [`.agent-src/skills/markitdown/SKILL.md`](../../.agent-src/skills/markitdown/SKILL.md)
+- [`dist/agent-src/skills/markitdown/SKILL.md`](../../dist/agent-src/skills/markitdown/SKILL.md)
   — markitdown skill entry point

package/docs/contracts/ai-council-config.md

@@ -197,7 +197,7 @@ A heuristic pre-flight that decides whether the request actually
 warrants a full council deliberation. Three verdicts (`necessary`,
 `borderline`, `unnecessary`) drive three exit paths in the dispatcher
 (skip silently, educate + block, or proceed). Implemented in
-[`scripts/ai_council/necessity.py`](../../scripts/ai_council/necessity.py);
+[`scripts/ai_council/necessity.py`](../../src/scripts/ai_council/necessity.py);
 wired into `council_cli.cmd_run` and `cmd_debate` before any member
 is invoked.
 
@@ -259,7 +259,7 @@ Decision table:
 | `== 0` | `== 0` | no | `borderline` |
 
 Trigger word lists live in
-[`scripts/ai_council/necessity.py`](../../scripts/ai_council/necessity.py)
+[`scripts/ai_council/necessity.py`](../../src/scripts/ai_council/necessity.py)
 as `NECESSARY_TRIGGERS` and `UNNECESSARY_TRIGGERS` — extend there with
 a unit test; never edit downstream copies.
 
@@ -271,7 +271,7 @@ final-round per-member texts — no extra model calls. The artefact
 surfaces, per top finding, the verdict band (Strong/Moderate/Weak), the
 evidence-quality bucket (H/M/L), the agree/dissent member split, and one
 key argument per member. Implementation:
-[`scripts/ai_council/replay.py`](../../scripts/ai_council/replay.py).
+[`scripts/ai_council/replay.py`](../../src/scripts/ai_council/replay.py).
 
 **Configuration.**
 
@@ -532,7 +532,7 @@ Markdown parsing reserved as fallback.
 | CI gate | `task check-corpus` (used by `task consistency`) | Fails on drift between source and lockfile. |
 
 The committed lockfile is the contract: a stale lockfile fails CI the
-same way `.agent-src/` drift does. The Markdown parser stays in the
+same way `dist/agent-src/` drift does. The Markdown parser stays in the
 repo as a build-time dependency, not a runtime dependency — a parser
 regression breaks `task consistency`, never the live council.