@event4u/agent-config 9.7.0 → 9.9.0

package/docs/contracts/ticket-bundle-format.md

@@ -1,233 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-17
----
-
-# Ticket-bundle format
-
-> The contract every downstream artifact reads from: the `emit-tickets` skill,
-> the buildability/manifest linters, and the `implement-ticket` bundle
-> input path. Authoritative for the frontmatter
-> schema, the body doctrine, the tracker mapping, and the self-containedness
-> floor. Locked by [ADR-101](../decisions/ADR-101-ticket-bundle-emission.md).
-
-## 1. Why this exists
-
-A roadmap step is a one-line checkbox; the full build spec is spread across the
-roadmap (what), ADRs (why), and the code (how). A `high`-tier agent holds that
-together; a `lite`-tier agent (Haiku) cannot. A **ticket bundle** is the closed,
-durable, importable artifact that lets an expensive planning agent hand a cheap
-building agent a complete unit of work. Markdown is the source of truth; a
-tracker issue (Linear/Jira) is a copy you make by paste or via MCP — not a
-generated export (§8).
-
-## 2. Layout
-
-A bundle is a directory, one per roadmap, under `agents/tickets/`:
-
-```
-agents/tickets/{roadmap-slug}/
-  manifest.yml                 # machine index: dependency graph
-  T-001-{slug}.md              # one ticket = one Markdown build contract
-  T-001-{slug}.assets/         # durable design context for that ticket
-    before.png  wireframe.png  example-io.md
-  T-002-{slug}.md
-  ...
-agents/tickets/_registry.yml   # machine-generated index of all bundles
-```
-
-- **Separate tree, not co-located** under the roadmap — the flat-file dashboard
-  and archival machinery (`update_roadmap_progress.py`,
-  `archive_completed_roadmaps.py`) assume `agents/roadmaps/*.md` are flat files;
-  a separate tree keeps that untouched (ADR-101 R1).
-- **Discovery** is via the generated `agents/tickets/_registry.yml` — one scan,
-  no recursive glob, no roadmap↔manifest circular dependency.
-- **Lifecycle**: a bundle is durable (unlike transient `agents/roadmap-assets/`);
-  when its roadmap archives, the bundle moves with it to
-  `agents/tickets/archive/{slug}/`.
-
-## 3. Ticket frontmatter (schema: `src/scripts/schemas/ticket.schema.json`)
-
-```yaml
----
-id: T-001                      # bundle-local id; stable handle for the ticket
-roadmap: road-to-xyz           # back-link (traceability spine)
-phase: 2                       # roadmap phase number
-title: "…"                     # → Linear Title
-status: ready                  # ready | draft | done
-model_tier: lite               # lite | medium | high — WHO may build it (ADR-035)
-estimate: 3                    # story points (from estimate-ticket)
-priority: 2                    # 0–4, Linear-compatible
-labels: [backend, mcp]
-parent: T-000                  # → Linear "Parent issue"; null at phase root
-blocked_by: [T-000]            # dependency edges (must be acyclic)
-adr_refs:                      # the "why", SHA-pinned (drift here HARD-blocks)
-  - { path: docs/decisions/ADR-101-ticket-bundle-emission.md, sha: <git-blob-sha> }
-source_refs:                   # files the build reads/changes, SHA-pinned (drift WARNS)
-  - { path: src/scripts/build_linear_digest.py, sha: <git-blob-sha> }
-assets: [T-001.assets/wireframe.png]   # relative to the bundle dir
-acceptance:                    # runnable AND isolation-testable; no prose-only
-  - "./scripts-run src/scripts/lint_ticket_buildable exits 0"
-boundaries:                    # ENFORCED by the work_engine boundary guard
-  must_touch:    [src/scripts/lint_ticket_buildable]
-  may_touch:     [Taskfile.yml]
-  must_not_touch: [src/scripts/work_engine/**, ".github/**"]
----
-```
-
-`status` is `done` only after the work landed + verification passed.
-
-## 4. Ticket body doctrine (the build contract)
-
-A lite ticket is autonomous only with this fixed section order:
-
-| Section | Purpose |
-|---|---|
-| `## Why` | 1–3 lines; the outcome, not backstory |
-| `## Context spine` | exact paths (`file.py:142`), the sibling-to-mirror, the producer of any shape it consumes — so the builder never searches |
-| `## Do` | ordered, mechanical steps |
-| `## Do NOT touch` | hard boundaries (mirrors frontmatter `boundaries`) |
-| `## Acceptance` | points at frontmatter `acceptance` (runnable, isolation-testable) |
-| `## Quality gates` | the concrete commands (not "run CI") |
-| `## Assets` | relative links into `T-NNN.assets/` (UI tickets) |
-
-**Self-containedness rule:** if the builder must read a file that is not in the
-context spine or `source_refs`, the ticket is incomplete.
-
-## 5. Self-containedness floor (per `model_tier`)
-
-Enforced by `lint_ticket_buildable`. A ticket FAILS the gate if its tier's
-row is not satisfied:
-
-| tier | acceptance | ≥1 concrete path | non-empty boundaries | resolvable assets | size floor |
-|---|---|---|---|---|---|
-| `lite` | required, runnable + isolation-testable | required | required | required (or `assets: none`) | ≤ 5 files AND ≤ 200 lines, else split or escalate to `medium` |
-| `medium` | required | required | recommended | recommended | — |
-| `high` | required | recommended | — | — | — |
-
-A failing `lite` ticket is rejected or auto-escalated to `medium`.
-
-## 6. Manifest (schema: `src/scripts/schemas/ticket-manifest.schema.json`)
-
-```yaml
-status: ready
-planner_tier: high
-builder_tier: lite
-import_targets: { linear: true, jira: false }
-dependency_graph:              # acyclic (no topological layering in v1)
-  T-001: { status: ready, blocks: [T-002] }
-  T-002: { status: ready, blocks: [] }
-```
-
-The manifest carries no tracker state — there is no API export to keep
-idempotent (§8). The bundle is the source of truth; a tracker issue is created
-by paste or by the agent via MCP, never synced back into the manifest.
-
-## 7. Registry (`agents/tickets/_registry.yml`, machine-generated)
-
-```yaml
-bundles:
-  road-to-ticket-bundles:
-    manifest_path: agents/tickets/road-to-ticket-bundles/manifest.yml
-    source_roadmap: agents/roadmaps/archive/road-to-ticket-bundles.md
-    status: in_progress        # derived from manifest
-```
-
-`update_roadmap_progress.py` reads this one file; never recursive-globs bundles.
-
-## 8. Tracker handoff — paste-ready, or via MCP (no API export)
-
-A ticket goes into Linear/Jira **by copy/paste** or, when programmatic, by the
-**agent using a tracker MCP server**. There is **no bundled API client and no
-automatic export** — the ticket Markdown *is* the handoff artifact.
-
-| Ticket field | Tracker issue |
-|---|---|
-| frontmatter `title` | issue title |
-| the Markdown **body** (everything after the frontmatter) | issue description — paste it; Markdown renders in Linear/Jira |
-| `priority` / `estimate` / `labels` | the matching issue fields (set during paste / by MCP) |
-| `parent` (phase root) | parent issue, when the tracker supports sub-issues |
-
-- **Copy/paste (default):** the ticket body is clean, render-ready Markdown.
-  Paste it into a new Linear/Jira issue; set title from `title`. Asset images
-  are relative repo paths — attach them in the tracker, or (public repo) paste a
-  `raw.githubusercontent.com` URL.
-- **MCP (programmatic):** to create issues without pasting, the agent calls the
-  Linear/Jira **MCP server** with the ticket as input. The package ships **no**
-  API wiring of its own — MCP is the integration surface.
-- **One direction only:** the bundle is the source of truth; a tracker issue is
-  a copy, never read back into the bundle (no sync, no `linear_state`).
-
-## 9. Traceability spine (bidirectional)
-
-`roadmap ↔ ticket ↔ ADR ↔ PR`. Each ticket frontmatter names its `roadmap` +
-`adr_refs`; each materialized roadmap step carries an inline
-`<!-- ticket: T-NNN -->` marker. The `work_engine` ticket envelope
-(`{id, title, body, acceptance_criteria}`) is a strict subset of this
-frontmatter, so `/implement-ticket` consumes a bundle with no schema fork.
-
-## 10. Staleness — split severity
-
-`lint_ticket_stale` recomputes the pinned SHAs:
-
-- **`adr_refs` drift → HARD block** (`not build-ready`); ADRs are semantic
-  decisions, rarely change → resolution = re-emit the bundle.
-- **`source_refs` drift → WARN only**; source files churn constantly, so a hard
-  block would keep most tickets perma-stale and multiply bundles. The builder
-  proceeds on a warning.
-
-## 11. Assets — durable, size-capped (LFS deferred)
-
-Git LFS is **not** configured in this repo today, and wiring it (install +
-remote LFS store) is heavier than v1 needs. v1 decision: assets are git-tracked
-binaries under a **size cap** — ≤ 500 KB per asset — and authors prefer vector /
-text context (Mermaid, ASCII, SVG, example-I/O Markdown) over raster where it
-carries the same information. `lint_ticket_buildable` warns on any asset over
-the cap. LFS is revisited only if `agents/tickets/**` binary weight is proven a
-real problem (same "defer until observed" discipline as the mutable-tickets
-mode). Non-binary design context lives as plain Markdown in the `.assets/` folder.
-
-## 12. Kill-switch & rollback
-
-Two reversal surfaces, since a bundle is git-tracked and the tracker is a
-projection:
-
-- **Per-ticket.** A ticket is reverted by `git`-restoring its `T-NNN-*.md`
-  (and `.assets/`) to a prior commit. A `lite` build gone wrong is bounded by
-  the ticket's `boundaries` (the work_engine boundary guard halts out-of-scope
-  edits before commit) — so the blast radius is the ticket's `must_touch` set.
-- **Per-bundle.** To abandon a bundle entirely, `git mv` it to
-  `agents/tickets/archive/{slug}/` (it moves with its roadmap on archival,
-  §2) — never delete in place, so the audit trail survives.
-
-A tracker issue created by paste/MCP from a ticket is a one-way copy (§8); the
-bundle is the source of truth, so reverting the bundle needs no tracker
-coordination — fix the issue in the tracker by hand if it was already created.
-
-## 13. Status projection — one direction only
-
-Three surfaces show a ticket's progress; exactly one is the truth and the other
-two are derived. The writeback is **single-directional** so they never become
-rival truths:
-
-```
-ticket `status` (MD)  ──►  roadmap checkbox  ──►  agents/roadmaps-progress.md (dashboard)
-```
-
-- The ticket file's `status` (`ready` / `draft` / `done`) is the **truth**.
-- When a ticket flips to `done`, its roadmap step's `<!-- ticket: T-NNN -->`
-  checkbox flips `[x]` in the **same edit**, and the dashboard regenerates
-  (`./agent-config roadmap:progress`) — the existing `roadmap-progress-sync`
-  cadence, unchanged.
-- A tracker issue (created by paste/MCP, §8) is a point-in-time copy; its state
-  is **not** read back into the ticket. If you keep a tracker issue in sync, do
-  it from the ticket outward (re-paste / MCP update), never the reverse.
-
-Never wire the reverse (tracker → ticket): that recreates the two-drifting-truths
-failure the whole format avoids.
-
-## See also
-
-- [ADR-101](../decisions/ADR-101-ticket-bundle-emission.md) — the format commitment + council convergence.
-- [`roadmaps.md`](../../src/agent-src/templates/roadmaps.md) — the sibling planning artifact.
-- [ADR-035](../decisions/ADR-035-model-capability-tiers.md) — the `model_tier` bands.

package/docs/contracts/tier-3-contrib-plugin.md

@@ -1,137 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Tier-3 contrib plugin pattern
-
-**Purpose.** Document the deferred-implementation contract for
-**Tier-3 community AIs** — surfaces that have been named in scoping
-discussions or council rounds but have **not yet been requested by
-a real user**. Tier-3 ships when the first user request lands, not
-on speculation.
-
-**Scope.** Defines the candidate list, the manifest shape, the
-promotion path from Tier-3 → Tier-2, and the non-implementation
-guarantee. Does **not** ship code: `agents/manifests/contrib/` is
-unmanifested until a user asks for an entry by name.
-
-Last refreshed: 2026-07-16.
-
-## Tier definitions
-
-| Tier | Status | Trigger | Implementation |
-|---|---|---|---|
-| **Tier-1** | Shipped | First-class surfaces with daily users | Imperative bridge in `scripts/install.py` |
-| **Tier-2** | Shipped | Named in roadmaps + has plausible audience | Imperative bridge, same pattern as Tier-1 |
-| **Tier-3** | **Deferred** | Named in scoping/council but zero user demand | Manifest YAML in `agents/manifests/contrib/` (not yet implemented) |
-
-Phase 2.1 + 2.2 of the `road-to-global-first-install` roadmap
-(under `agents/roadmaps/`) closed Tier-1 and Tier-2 at **16 AIs**.
-Tier-3 is the explicit overflow bucket.
-
-## Candidate list (frozen at proposal time)
-
-The following surfaces are Tier-3 candidates as of 2026-05-12. They
-were surfaced during the
-[`2026-05-12-installer-expansion`](../../agents/runtime/council/sessions/2026-05-12-installer-expansion/synthesis.md)
-council round and had **no entries** in `_VALID_TOOLS`,
-`USER_SCOPE_PATHS`, `SCOPE_SUPPORT` or the bash `VALID_TOOLS` set at
-proposal time.
-
-**Status update (2026-07-16):** the candidates below have since been
-promoted to shipped hosts — each now has entries in `_VALID_TOOLS`,
-`USER_SCOPE_PATHS` and `SCOPE_SUPPORT`, deployed as the universal
-global skill bundle. The bullets are kept as the frozen proposal-time
-record; their rationales describe the pre-promotion state and no
-longer reflect current shipping status.
-
-- `qoder` — community fork, no public adoption signal
-- `trae` — ByteDance IDE, behind login wall
-- `opencode` — bundled into VS Code variants; coverage already via `vscode`
-- `codebuddy` — Tencent-internal, no public install path
-- `droid` — proposed CLI agent, alpha
-- `warp` — terminal-with-AI; integration shape unclear (PTY vs file marker)
-- `antigravity` — Google's agentic IDE (public since 2026); shipped as a global bundle host (see status update above)
-
-Inclusion in this list is **not** a commitment to ship. Promotion
-requires a real user asking by name (issue, PR, council session, or
-recorded ask).
-
-## Manifest shape (when implemented)
-
-When the first user request lands, the responder MUST:
-
-1. Create `agents/manifests/contrib/<tool-id>.yml` matching the
-   schema below.
-2. Add the tool ID to `_VALID_TOOLS`, `USER_SCOPE_PATHS`,
-   `SCOPE_SUPPORT`, and the bash `VALID_TOOLS` set.
-3. Implement `ensure_<tool>_bridge` in `src/install/` (≤60 LOC
-   — if larger, escalate via ADR per Phase 2.5 gate).
-4. Append a row to the `README.md` "Supported Tools" table.
-5. Re-run `task lint-skills` + `task test`.
-
-```yaml
-# agents/manifests/contrib/<tool-id>.yml
-tool_id: <slug>           # lowercase, hyphen-separated
-display_name: <Pretty>    # for README + CLI catalog
-scope: project | global | both
-discovery: marker | hook | config-merge
-marker_path: <relative>   # e.g. .tool-id/agent-config.md
-requested_by: <ref>       # GitHub issue, PR, council session, etc.
-requested_date: YYYY-MM-DD
-notes: |
-  Short rationale, integration shape, known limitations.
-```
-
-## Non-implementation guarantee
-
-`agents/manifests/contrib/` does **not** exist until needed. CI does
-not enforce its presence. The pattern is documented, not scaffolded.
-
-This prevents two failure modes:
-
-1. **Empty-shell drift** — a directory of YAML stubs with no
-   corresponding code, where the manifest claims support but the
-   installer silently no-ops.
-2. **Speculative breadth** — adding 7 IDs to `_VALID_TOOLS` "in
-   case" a user asks, then carrying maintenance cost on dead code.
-
-## Promotion path
-
-Tier-3 → Tier-2 promotion happens in a single PR:
-
-1. The first user request anchors the PR (link in commit body).
-2. Manifest YAML lands alongside the bridge.
-3. README + roadmap update in the same commit.
-4. After two reported successful installs (or one release cycle of
-   no bug reports), the tool moves out of `contrib/` and the manifest
-   YAML is deleted — the bridge stands on its own under the Tier-2
-   contract.
-
-There is no Tier-3 → Tier-3 churn: a candidate either gets
-requested and promoted, or stays unimplemented indefinitely. We do
-not "preemptively scaffold" Tier-3 entries.
-
-## Out of scope
-
-- **Capability matrices** — the manifest does not describe what the
-  tool _can_ do, only what the installer must emit. Capability docs
-  live in the consumer tool's own documentation.
-- **Auto-discovery** — there is no plugin loader. The installer is
-  imperative (see Phase 2.5 gate); manifests are a documentation
-  contract, not a runtime input.
-- **Third-party contribution channel** — this contract governs the
-  package maintainer's response to user requests, not a community
-  plugin marketplace. External plugins would require ADR-009+ to
-  introduce a stable extension surface.
-
-## Cross-references
-
-- [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md) —
-  project / global / both scope taxonomy that Tier-3 entries inherit.
-- [`ADR-008`](../decisions/ADR-008-installed-tools-manifest.md) —
-  `agents/installed-tools.lock` for per-project state, distinct
-  from this maintainer-side contract.
-- The `road-to-global-first-install` roadmap (under
-  `agents/roadmaps/`) Phase 2.6 — completion trigger for this contract.

package/docs/contracts/trust-and-safety.md

@@ -1,144 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-21
----
-
-# Trust & Safety Layer — Phase 5 of the monorepo migration
-
-> **Status:** active · **Stability:** beta · **Owner:** monorepo-phase-5
-> · **Authoritative ADR:** [`ADR-018`](../decisions/ADR-018-trust-and-safety-layer.md)
-
-Phase 1 stamped every artefact with `trust.level`,
-`trust.confidence`, and `trust.human_review_required`. Phase 5
-**enforces** those fields: the installer surfaces them at selection
-time, the condenseor injects banners into compiled output, the
-runtime gates `human_review_required: true` artefacts before final
-output, and a lint catches drift. This contract is what those four
-consumers depend on.
-
-## § 1 — Trust levels
-
-A closed enum on `trust.level`:
-
-| level         | meaning                                                              |
-|---------------|----------------------------------------------------------------------|
-| `core`        | Iron-Law / structural. Cannot be downgraded. Kernel rules sit here.  |
-| `professional`| Domain expertise the user opted into; no human-review floor.         |
-| `advisory`    | High-impact judgement. Installer **must** confirm; banner injected.  |
-| `restricted`  | Reserved for future legal / regulated content. Same surface as advisory, stricter copy. |
-| `experimental`| Pre-stable. May be removed without ADR.                              |
-
-`trust.confidence` is a parallel signal (`high` · `medium` · `low`)
-used by the manifest's summary; it does **not** gate behaviour.
-
-`trust.human_review_required: true` is the per-artefact banner gate.
-Independent of `trust.level` so a `professional` artefact can still
-demand review on its specific surface.
-
-## § 2 — HRR banner
-
-The condenseor (`scripts/condense.py`) prepends every artefact whose
-frontmatter declares `trust.human_review_required: true` with:
-
-```text
-<!-- agent-config:human-review-banner -->
-> HUMAN REVIEW REQUIRED · trust: <level> · owner: <domain>
-
-<original body>
-```
-
-- The HTML comment is the parser-stable marker
-  (`_HRR_BANNER_MARKER` in `scripts/condense.py`). Runtime detection
-  greps for this string, never the prose line.
-- Idempotent: re-condensing a file that already carries the marker
-  leaves it unchanged.
-- `<domain>` is the first pack id that ships the artefact (e.g.
-  `finance-basic`, `founder-strategy`); falls back to `core` for
-  unscoped artefacts.
-
-## § 3 — Domain safety floors
-
-Each pack that ships any `advisory`/`restricted` artefact MUST also
-ship at least one rule whose logical filename contains
-`safety-floor`. The current set:
-
-| pack                    | safety-floor rule                                  |
-|-------------------------|----------------------------------------------------|
-| `core` (universal)      | `rules/engineering-safety-floor.md`                |
-| `pack-finance-basic`    | `rules/finance-safety-floor.md`                    |
-| `pack-finance-advanced` | inherits `finance-safety-floor` from `pack-finance-basic` |
-| `pack-founder-strategy` | `rules/strategy-safety-floor.md`                   |
-
-A safety-floor rule:
-
-- Carries `trust.level: advisory` and `trust.human_review_required: true`
-  itself — it ships with the banner.
-- Names what the agent must **not** issue (final investment call, binding
-  legal advice, single-path strategic verdict) and what it must surface
-  instead (alternatives, sensitivity, assumptions, jurisdiction).
-- Loads automatically alongside the rest of the pack — no opt-in.
-
-## § 4 — Installer flow
-
-[`packages/core/installer/src/trust-escalation.ts`](../../packages/core/installer/src/trust-escalation.ts)
-implements the gate:
-
-1. **Display.** The pack picker reads `packs[].trust_summary` from
-   `dist/discovery/discovery-manifest.json` and renders one line per pack:
-   `Finance basic: 3 advisory · 3 professional · human-review on 1`.
-2. **Confirm.** Selecting a pack with any `advisory`/`restricted`
-   artefact triggers a confirm prompt. Non-interactive mode (CI,
-   agent-mode) requires `--accept-advisory=<pack-id>[,<pack-id>...]`
-   explicitly; absence aborts with a non-zero exit.
-3. **Agent-mode.** Emits a structured `confirm` question type with the
-   trust counts inline; the host agent must relay it verbatim per
-   `command-suggestion-policy`.
-4. **Lockfile.** `.agent-config.lock.json` records the accepted trust
-   counts per pack at install time. A later `sync` that finds the
-   manifest's `trust_summary` has **escalated** (more advisory /
-   restricted artefacts than were accepted) re-runs the confirm step
-   before applying.
-
-## § 5 — Coherence lint
-
-`scripts/lint_trust_coherence.py` (wired into `ci-fast` and `ci-full`)
-asserts three invariants over `dist/discovery/discovery-manifest.json`:
-
-1. **Safety-floor presence.** Every pack with
-   `trust_summary.advisory + trust_summary.restricted > 0` ships at
-   least one artefact whose logical path contains `safety-floor`.
-2. **Banner presence.** Every artefact with
-   `trust.human_review_required: true` has its compiled output under
-   `dist/agent-src/<logical>` and that output contains
-   `<!-- agent-config:human-review-banner -->`.
-3. **Kernel trust floor.** Every rule listed in `dist/router.json` `kernel[]`
-   declares `trust.level: core`. No escalation (advisory blocks the
-   Iron-Law floor) and no demotion (experimental cannot guarantee it).
-
-Exits 0 clean, 1 on any violation. Tests in
-`tests/test_lint_trust_coherence.py` lock the seven failure modes.
-
-## § 6 — What this contract does **not** do
-
-- **Per-user permissions.** Trust is a property of artefacts, not of
-  users. The installer confirms once at install / sync time; there is
-  no runtime per-action authorisation.
-- **Rewriting the Iron Law floor.** `non-destructive-by-default`,
-  `commit-policy`, `scope-control § git-ops`, `security-sensitive-stop`
-  keep their universal scope — this contract references them, never
-  re-declares them. See [`safety-model`](safety-model.md) and
-  [`kernel-membership`](kernel-membership.md).
-- **Versioning the trust enum.** A new level (e.g. a future
-  `regulated`) requires a follow-on ADR; this contract enumerates the
-  current closed set.
-
-## § 7 — References
-
-- ADR: [`ADR-018 — Trust & Safety Layer`](../decisions/ADR-018-trust-and-safety-layer.md)
-- Condenseor implementation: [`scripts/condense.py`](../../src/scripts/condense.py)
-  (`_inject_hrr_banner`, `_HRR_BANNER_MARKER`)
-- Installer implementation: [`packages/core/installer/src/trust-escalation.ts`](../../packages/core/installer/src/trust-escalation.ts)
-- Lint implementation: [`scripts/lint_trust_coherence.py`](../../src/scripts/lint_trust_coherence.py)
-- Sibling contracts: [`safety-model`](safety-model.md) ·
-  [`kernel-membership`](kernel-membership.md) ·
-  [`ADR-013` — discovery frontmatter](../decisions/ADR-013-discovery-frontmatter-contract.md)