metaensemble 0.2.0__py3-none-any.whl

metaensemble/commands/dispatch.md

@@ -0,0 +1,39 @@
+---
+name: dispatch
+description: Plan a Task, compose a Manifest, and spawn one or more Executors. Default is N=1 (Solo). Use --fanout, --consensus, --shadow, or --peer-review for multi-instance patterns.
+---
+
+When the Principal invokes `/dispatch <task description> [flags]`, follow the Coordinator protocol in `metaensemble/skills/metaensemble-protocol/SKILL.md`:
+
+1. **Plan.** Decompose the task description into one or more Tasks. For each Task, pick the Role best suited to execute (the subagent_type) and the model tier the Role declares.
+
+2. **Compose the Manifest** *(when the Task warrants a typed contract)*. Write a YAML Manifest at `.metaensemble/manifests/<manifest_id>.yaml`. The Manifest is mandatory for irreversible Tasks and recommended for any multi-step Task. Include `manifest_id` of the form `hm-<UUIDv7 hex>`, typed `context.files` pointers, explicit `expected_deliverables` with paths and verifiable assertions (`must_export`, `coverage`), and `constraints` for model tier and window budget. When the Task affects shared state, set `peer_review.mandatory_for_reversibility: true`. Validation is automatic: the PreToolUse hook validates the Manifest against `metaensemble/schemas/manifest.schema.json` when you reference it.
+
+3. **Embed markers in the Task prompt.** The PreToolUse hook reads bracket-marker metadata from the prompt and uses it to drive the recording layer and the protocol guard. Markers (all optional):
+   - `[manifest: hm-<id>]` — the Coordinator's Manifest for this Task. The hook validates the YAML; if validation fails, the dispatch blocks.
+   - `[task: task-<id>]` — explicit Task id. Use to group multiple Executors under one Task (fan-out, consensus, peer review).
+   - `[project: /absolute/project/root]` — explicit adopted project root. Include this on every Executor prompt when `/dispatch` is invoked from outside the target project or with `--project <path>`, so hooks write the Run to the intended project's Ledger.
+   - `[continuing: <alias>]` — resume a specific Executor by alias (typically used from `/relaunch`).
+   - `[fresh]` — force-create a new Executor of this Role rather than reusing the most-recent active one. Required for fan-out, consensus, and the reviewer leg of peer-review dispatches.
+   - `[fanout: N]` — declared fanout size when dispatching under `--fanout N`. The hook rejects the dispatch deterministically when `N < 2`; this is the enforceable protocol guard for `--fanout 1` and similar invalid invocations. Required on every Executor prompt in a fan-out batch.
+   - `[consensus: N]` — same shape and same guard for `--consensus N`. Required on every Executor prompt in a consensus batch.
+
+4. **Dispatch.** Spawn the Executor(s) via Task invocations, embedding the markers from step 3 in each prompt. The PreToolUse hook runs the cost gate and stamps a pending Run; PostToolUse completes the Run when the Executor returns. The recording layer is automatic — you do not need to write to the Ledger directly.
+
+5. **Respect overlap ownership and report location.** Before composing Briefs, read `<project>/.metaensemble/install-decisions.yaml`. Use its `report_root` for any new MetaEnsemble-authored report Deliverable. For greenfield projects this defaults to `.metaensemble/reports`; existing projects can keep an established convention such as `.claude/reports` when inspection detected one. For every `overlaps.*.action: metaensemble_owned`, do not instruct Executors to maintain the listed project surface. For deliverable/work-record documentation, rely on the Ledger and Deliverables index for structural tracking unless the overlap is `project_owned` or `dual`.
+
+6. **Verify and synthesize without duplicate reports.** After Executors return, confirm declared Deliverables exist at the paths the Manifest declared. Do not write a second Coordinator synthesis file by default; give the synthesis in the Principal-facing response. Write a Coordinator synthesis Markdown file only when the Manifest explicitly declares that synthesis as an expected Deliverable, using `report_root` for greenfield report paths. When multiple Executors ran (fan-out, consensus, peer review), surface dissent explicitly rather than averaging it.
+
+## Multi-instance patterns
+
+`--fanout N` — N Executors of one Role with divergent Briefs; explore hypotheses. Generate one shared `task_id` and one Manifest. Spawn N Tasks, each with `[manifest: hm-...] [task: task-...] [fanout: N] [fresh]` plus a divergent prompt body. `N` must be >= 2; the PreToolUse hook rejects `[fanout: 1]` (or any `N < 2`) deterministically before any Executor work begins.
+
+`--consensus N` — N Executors of one Role with the same Brief; surface majority and dissent rather than averaging. Same markers as fan-out, identical prompt bodies, with `[consensus: N]` in place of `[fanout: N]`. The same `N >= 2` guard applies.
+
+`--shadow tier1,tier2` — two Executors at different model tiers; validate downward tiering. Same markers as fan-out, identical Brief, but each invocation's `subagent_type` may carry tier-specific routing.
+
+`--peer-review role1,role2` — one Executor + one or more reviewer Executors of different Roles. Mandatory for irreversible Tasks. Spawn the executor Task with `[manifest: hm-...] [task: task-...]`, then spawn each reviewer Task with `[manifest: hm-...] [task: task-...] [fresh]` and the reviewer's `subagent_type`. The shared `task_id` groups them in the Ledger for later inspection.
+
+`--project <path>` — dispatch against an adopted project even when the current Claude session cwd is somewhere else. Resolve `<path>` to an absolute path and include `[project: <absolute-path>]` on every Executor prompt and Manifest path decision. The hooks route pending sidecars, Run rows, file provenance, and quality checks through that project's `.metaensemble/state/`.
+
+The full pattern reference is in `ARCHITECTURE.md` §12.

metaensemble/commands/executors.md

@@ -0,0 +1,12 @@
+---
+name: executors
+description: List the Executors active in the last 30 days, with their Role, status, and most recent Run.
+---
+
+When the Principal invokes `/executors`, run the runner and relay its output unchanged:
+
+```bash
+"$HOME/.metaensemble/runtime/bin/me-run" executors
+```
+
+The tool reads from the Ledger via `get_active_executors(since=now-30d, limit=200)` and renders a Markdown table. No further interpretation needed; the table is the answer.

metaensemble/commands/ledger.md

@@ -0,0 +1,19 @@
+---
+name: ledger
+description: Query the Ledger via named subcommands. Subcommands — recent, by-executor, by-task, window. Forbidden — ad-hoc SQL.
+---
+
+When the Principal invokes `/ledger <subcommand> [args]`, run the runner and relay its output unchanged:
+
+```bash
+"$HOME/.metaensemble/runtime/bin/me-run" ledger <subcommand> [args]
+```
+
+Subcommands:
+
+- `recent [--limit N]` — most recent Runs across all Executors (default 20)
+- `by-executor <executor_id_or_alias> [--limit N]` — Runs for one Executor; accepts UUID or alias
+- `by-task <task_id> [--limit N]` — Runs for one Task
+- `window <window_id>` — aggregate burn for one 5-hour window bucket
+
+Per `PERFORMANCE.md` §3 R1, every subcommand maps to a named query in `metaensemble/lib/ledger.py`. Ad-hoc SQL is forbidden; if the Principal asks a question that no subcommand answers, propose a new named query in `lib/ledger.py` rather than reaching for raw SQL.

metaensemble/commands/limits.md

@@ -0,0 +1,12 @@
+---
+name: limits
+description: Show the current 5-hour window's token burn, remaining capacity, and run count.
+---
+
+When the Principal invokes `/limits`, run the runner and relay its output unchanged:
+
+```bash
+"$HOME/.metaensemble/runtime/bin/me-run" limits
+```
+
+The output is Markdown formatted for direct relay. If the Principal asks for a specific historical window, fall back to `/ledger window <window-id>` for arbitrary buckets.

metaensemble/commands/perf.md

@@ -0,0 +1,12 @@
+---
+name: perf
+description: Rolling performance metrics over the last 24 hours — Run latency distribution, outcome breakdown, hook error log health.
+---
+
+When the Principal invokes `/perf`, run the runner and relay its output unchanged:
+
+```bash
+"$HOME/.metaensemble/runtime/bin/me-run" perf
+```
+
+This surface lets the Principal see drift against the `PERFORMANCE.md` §3 budgets before it becomes a problem. If the Principal wants to drill into specific hook errors, point them at `.metaensemble/hooks/log.jsonl`.

metaensemble/commands/relaunch.md

@@ -0,0 +1,29 @@
+---
+name: relaunch
+description: Resume a past Executor by alias. Loads its last Brief and Deliverable summary into a fresh Run. Use --full for deep context restore.
+---
+
+When the Principal invokes `/relaunch <alias>` (e.g. `/relaunch arch-7b3`):
+
+1. **Load the relaunch context.** Run the runner and read its output:
+
+   ```bash
+   "$HOME/.metaensemble/runtime/bin/me-run" relaunch <alias>
+   ```
+
+   Add `--full` if the Principal asked for the deep restore. The tool prints a Markdown context block: the Executor's identity, the most recent Brief, and a summary of the most recent Deliverable. If no Executor matches the alias, the tool exits non-zero with an explanatory message; relay it and stop.
+
+2. **Compose the resumption Brief.** Combine the printed context with the new instruction the Principal just gave you. The resumption Brief is the synthesis the next Run will start from.
+
+3. **Dispatch under the same identity.** Spawn the Task and include a continuation marker in the prompt so the recording layer reuses the same Executor row rather than creating a new one:
+
+   ```
+   [continuing: <alias>]
+   <the resumption Brief, in plain English>
+   ```
+
+   The PreToolUse hook reads the marker, resolves the existing Executor by alias, and records the new Run under that identity. From this point on, the dispatch proceeds exactly like any other Task.
+
+4. **Synthesize.** After the new Run completes, return the Deliverable to the Principal as you would for any Dispatch.
+
+See `ARCHITECTURE.md` §14 for the relaunch contract.

metaensemble/commands/standup.md

@@ -0,0 +1,14 @@
+---
+name: standup
+description: Daily-style summary — current window status, last-24h Runs, top token consumers, active Executors over the last 7 days.
+---
+
+When the Principal invokes `/standup`, run the runner and relay its output unchanged:
+
+```bash
+"$HOME/.metaensemble/runtime/bin/me-run" standup
+```
+
+The runner pins one absolute Python interpreter and execs the CLI, so it works regardless of whether the venv is activated in the current shell. It reads from the Ledger via named queries (`get_window_burn`, `get_recent_runs`, `get_active_executors`) and prints a Markdown digest. No further commentary unless the Principal asks for it.
+
+If the runner does not exist (`No such file or directory`), MetaEnsemble has not been installed yet; tell the Principal to run `metaensemble user-setup --layout=namespaced` (or `--layout=top-level`).

metaensemble/config/budgets.example.yaml

@@ -0,0 +1,72 @@
+# MetaEnsemble budget configuration — example
+#
+# Copy this file to one of two locations to activate it:
+#   - User layer:    ~/.metaensemble/budgets.yaml
+#   - Project layer: <project>/.metaensemble/budgets.yaml
+#
+# Project values override User values, which override the Core defaults
+# encoded in `metaensemble/lib/config.py`. The defaults shown here match those
+# defaults; you only need to set values that differ from them.
+#
+# See ARCHITECTURE.md §9 (Cost gating) for the design.
+#
+# The cost gate is two-axis:
+#   Axis 1 — run size (this dispatch vs the window capacity)
+#   Axis 2 — window headroom (how much of the window is left)
+# Either axis can escalate to NOTIFY or BLOCK. Final state is the worst
+# of the two. Irreversibility and novelty are independent hard-blocks
+# on top.
+
+thresholds:
+  # AXIS 1 — run size, expressed as percentage of WINDOW CAPACITY.
+  # "Block any single dispatch that exceeds 40% of my whole window."
+  run_soft_pct_of_capacity: 20   # substantive dispatch — NOTIFY at this point
+  run_hard_pct_of_capacity: 40   # outsized dispatch — BLOCK for explicit OK
+
+  # AXIS 2 — window headroom, expressed as percentage of capacity STILL
+  # REMAINING. "Warn when only 30% of the window is left" /
+  # "Block all dispatches when only 10% is left."
+  window_warn_pct_remaining: 30
+  window_block_pct_remaining: 10
+
+  # WINDOW CAPACITY — tokens (input + output) for the user's plan's
+  # 5-hour cap.
+  #
+  # IMPORTANT: the value below is a FALLBACK used only when MetaEnsemble
+  # cannot read the runtime's authoritative `rate_limits` field. With
+  # the statusline integration installed (which `metaensemble user-setup`
+  # registers by default), the cost gate DERIVES capacity from the
+  # runtime's own per-session rate-limit feed — Claude Code v2.1.80+
+  # exposes the 5-hour window's `used_percentage` to statusline scripts
+  # on every refresh, and MetaEnsemble's statusline captures it. The
+  # derived capacity tracks plan changes (Pro / Max-5 / Max-20)
+  # automatically; the fallback below is only consulted when no fresh
+  # native data is available (e.g., before the first session refresh).
+  window_capacity_tokens: 88000
+
+# Actions matched against the irreversible list always block, regardless
+# of cost, and trigger mandatory peer review per ARCHITECTURE §11.
+# Patterns are matched conservatively; when in doubt, the gate blocks.
+irreversible_actions:
+  - "Write to existing files"
+  - "Bash matching git push|rm |DROP |DELETE "
+  - "any non-localhost network call"
+
+# Novelty escalation: the first time the Ledger sees a new Manifest
+# pattern, the gate blocks for Principal review. After the configured
+# number of successful Runs, the pattern de-escalates to notify, then
+# auto. Set `treat_first_run_of_pattern_as_block` to false to disable
+# the novelty escalation entirely.
+novelty:
+  treat_first_run_of_pattern_as_block: true
+  drop_to_notify_after_n_runs: 2
+  drop_to_auto_after_n_runs: 3
+
+# Capacity calibration: when true (default), the cost gate prefers the
+# runtime's native `rate_limits` feed over the `window_capacity_tokens`
+# value above. The fallback is used only when no fresh native data is
+# available. Set to false to pin capacity to the manual value (useful
+# for testing or for users who want predictable behavior independent
+# of the runtime's reporting).
+capacity_calibration:
+  auto_calibrate_capacity: true

metaensemble/config/quality.example.yaml

@@ -0,0 +1,82 @@
+# MetaEnsemble quality-gate configuration — example
+#
+# Copy this file to one of two locations to activate it:
+#   - User layer:    ~/.metaensemble/quality.yaml
+#   - Project layer: <project>/.metaensemble/quality.yaml
+#
+# Project values override User values, which override the core defaults
+# encoded in `metaensemble/lib/config.py` (the `_DEFAULT_QUALITY` block). The
+# values shown here match those defaults; you only need to set values
+# you want to differ.
+#
+# See ARCHITECTURE.md §10 (Quality gating) for the design rationale
+# and the industry sources the thresholds anchor on (SonarQube,
+# Snyk, NISTIR 8397, McCabe, DORA).
+
+# Axis 1 — Correctness. Runs the project's pytest suite when a dispatch
+# produces Python deliverables and classifies by failure count.
+correctness:
+  enabled: true
+  notify_failures: 1   # 1+ failing tests → NOTIFY
+  block_failures: 3    # 3+ failing tests → BLOCK
+
+# Axis 2 — Security. Runs bandit on the changed Python files and
+# classifies by the highest severity finding. Mirrors Snyk's defaults.
+security:
+  enabled: true
+  notify_severity: medium   # one or more medium-severity findings → NOTIFY
+  block_severity: high      # one or more high or critical findings → BLOCK
+
+# Axis 3 — Maintainability. Runs ruff on the changed Python files and
+# classifies by issue count, mapped to SonarQube-style A/B/C/D/E grades
+# (A: 0, B: 1–5, C: 6–15, D: 16–30, E: 30+).
+maintainability:
+  enabled: true
+  notify_issues: 6   # 6+ ruff issues across changed files → NOTIFY (grade C)
+  block_issues: 16   # 16+ → BLOCK (grade D or E)
+
+# Axis 4 — Complexity. Runs radon's cyclomatic-complexity check on the
+# changed Python files. Anchors on McCabe's stable 10-and-15 thresholds.
+complexity:
+  enabled: true
+  notify_above: 10   # any function above McCabe 10 → NOTIFY
+  block_above: 15    # any function above McCabe 15 → BLOCK
+
+# Axis 5 — Coverage delta. Reads coverage.py's last report from the
+# project's `.coverage` file. The absolute floor mirrors NISTIR 8397's
+# 80% line-coverage recommendation. v0.1 implements the absolute check
+# only; v0.2 will extend with a committed baseline for true delta.
+coverage:
+  enabled: true
+  notify_drop_pp: 5.0           # 5 percentage-point drop vs baseline → NOTIFY
+  block_drop_pp: 5.0            # 5pp drop → BLOCK
+  block_absolute_below: 80.0    # coverage below 80% → BLOCK regardless of delta
+
+# Axis commands — generalize the gate beyond Python. Each axis can carry
+# a command that runs from the project root whenever a dispatch produces
+# non-Python deliverables, so a JS/TS (or Go, Rust, ...) Deliverable is
+# still checked across the same five axes. Only the exit code is
+# interpreted: exit 0 → AUTO; nonzero → the axis's `state_on_fail`
+# ("notify" by default, or "block"). A command that is not installed or
+# times out skips its axis with a reason — the gate never guesses.
+#
+# Commands run alongside the Python runners: a mixed .py + .ts dispatch
+# records both "correctness" (pytest) and "correctness:cmd" (your
+# command), and the worst state across all axes still decides the gate.
+# Commands are shlex-split and run without a shell — put pipes or `&&`
+# chains in a script and point `cmd` at it.
+#
+# axis_commands:
+#   correctness:
+#     cmd: "npm test --silent"
+#     timeout: 180              # seconds; default 120
+#     state_on_fail: block      # failing tests should stop the line
+#   security:
+#     cmd: "npm audit --audit-level=high"
+#   maintainability:
+#     cmd: "npx eslint ."
+#     state_on_fail: notify     # the default; shown for completeness
+#   complexity:
+#     cmd: "npx eslint . --rule '{\"complexity\": [\"error\", 15]}'"
+#   coverage:
+#     cmd: "npx vitest run --coverage"

metaensemble/hooks/__init__.py

@@ -0,0 +1 @@
+"""MetaEnsemble lifecycle hooks. See ARCHITECTURE.md §8 and PERFORMANCE.md §3 R7."""

metaensemble/hooks/_common.py

@@ -0,0 +1,148 @@
+"""Shared utilities for MetaEnsemble hooks.
+
+Per PERFORMANCE.md §3 R7, hooks are fast (<100ms p95), idempotent, and
+free of model calls and network I/O. They share state-directory location
+and error-logging behavior through this module so each hook script stays
+small and single-purpose.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+# --- State directory resolution --------------------------------------------
+
+def state_dir() -> Path:
+    """Return the project-level `.metaensemble/state/` directory.
+
+    Honors the `METAENSEMBLE_STATE_DIR` environment variable for tests and
+    custom deployments; otherwise resolves to `<cwd>/.metaensemble/state/`.
+    """
+    override = os.environ.get("METAENSEMBLE_STATE_DIR")
+    if override:
+        return Path(override)
+    return Path.cwd() / ".metaensemble" / "state"
+
+
+def project_root_from_payload(payload: dict[str, Any]) -> Path | None:
+    """Resolve an explicit `[project: ...]` prompt marker, if present."""
+    try:
+        from metaensemble.lib.recording import parse_markers
+    except Exception:
+        return None
+    tool_input = payload.get("tool_input")
+    prompt = tool_input.get("prompt") if isinstance(tool_input, dict) else None
+    markers = parse_markers(prompt if isinstance(prompt, str) else None)
+    project_path = markers.get("project_path")
+    if not project_path:
+        return None
+    root = Path(project_path).expanduser()
+    if not root.is_absolute():
+        root = Path.cwd() / root
+    root = root.resolve(strict=False)
+    if not (root / ".metaensemble").is_dir():
+        return None
+    return root
+
+
+def state_dir_for_payload(payload: dict[str, Any]) -> Path:
+    """Return the Ledger state dir for a hook payload.
+
+    Explicit `[project: ...]` markers take precedence so a dispatch started
+    from a different cwd still records into the intended adopted project.
+    """
+    project_root = project_root_from_payload(payload)
+    if project_root is not None:
+        return project_root / ".metaensemble" / "state"
+    return state_dir()
+
+
+def db_path() -> Path:
+    return state_dir() / "department.db"
+
+
+def db_path_for_state(run_state_dir: Path) -> Path:
+    return Path(run_state_dir) / "department.db"
+
+
+def jsonl_path() -> Path:
+    return state_dir() / "runs.jsonl"
+
+
+def jsonl_path_for_state(run_state_dir: Path) -> Path:
+    return Path(run_state_dir) / "runs.jsonl"
+
+
+def hooks_log_path() -> Path:
+    return state_dir().parent / "hooks" / "log.jsonl"
+
+
+def migration_sql() -> str:
+    """Return the canonical migration script text. Idempotent to apply."""
+    here = Path(__file__).resolve().parent.parent
+    return (here / "state" / "migrations" / "001_init.sql").read_text()
+
+
+# --- Stdin / stdout JSON contract -----------------------------------------
+
+def read_input() -> dict[str, Any]:
+    """Read hook input from stdin as JSON. Returns {} if stdin is empty."""
+    raw = sys.stdin.read().strip()
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        log_error("invalid-stdin-json", str(exc), {"raw": raw[:500]})
+        return {}
+
+
+def emit(payload: dict[str, Any]) -> None:
+    """Write a JSON object to stdout. The agent runtime parses it as the hook's response."""
+    sys.stdout.write(json.dumps(payload))
+    sys.stdout.flush()
+
+
+# --- Error logging --------------------------------------------------------
+
+def log_error(kind: str, message: str, context: dict[str, Any] | None = None) -> None:
+    """Append a structured error record to `.metaensemble/hooks/log.jsonl`.
+
+    Hooks never block on logging failures — if the log write itself fails,
+    we silently swallow it, because a stuck hook is worse than a missed
+    log entry (PERFORMANCE.md §3 R7).
+    """
+    try:
+        log_file = hooks_log_path()
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        record = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "kind": kind,
+            "message": message,
+            "context": context or {},
+        }
+        with log_file.open("a") as f:
+            f.write(json.dumps(record) + "\n")
+    except Exception:  # nosec B110
+        # Hooks must remain non-blocking when the diagnostic sink itself
+        # fails; raising here would turn a missed log line into a user-visible
+        # hook failure.
+        pass
+
+
+# --- Window-id derivation -------------------------------------------------
+
+def current_window_id(at: datetime | None = None) -> str:
+    """Return the 5-hour window bucket for the given moment.
+
+    Buckets align to 5-hour blocks starting at 00:00 UTC each day.
+    Format: `YYYY-MM-DDTHH` where HH is the start of the bucket.
+    """
+    now = at or datetime.now(timezone.utc)
+    bucket_start = (now.hour // 5) * 5
+    return f"{now.year:04d}-{now.month:02d}-{now.day:02d}T{bucket_start:02d}"

metaensemble/hooks/deliverable_sync.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""PostToolUse hook for Write invocations that produce Deliverables.
+
+When a Write call lands a markdown file under a `reports/` directory
+(for greenfield MetaEnsemble projects, normally `.metaensemble/reports/`),
+this hook treats the file as a Deliverable and records the path so the
+Registry view can surface it. The hook is
+deliberately non-blocking; if the write turns out not to be a Deliverable
+or the recording fails, the hook logs and exits 0.
+
+Stdin shape:
+    {
+      "tool_name": "Write",
+      "tool_input": { "file_path": "..." },
+      "tool_output": { ... }
+    }
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+
+from metaensemble.hooks._common import (  # noqa: E402
+    emit,
+    log_error,
+    read_input,
+    state_dir,
+)
+
+
+DELIVERABLE_INDEX_PATH = "deliverables_index.jsonl"
+
+
+def _is_deliverable(file_path: str) -> bool:
+    """A Write counts as a Deliverable if its path lies under reports/ and is markdown."""
+    p = Path(file_path)
+    if p.suffix.lower() != ".md":
+        return False
+    return "reports" in p.parts
+
+
+def run() -> int:
+    payload = read_input()
+    if payload.get("tool_name") != "Write":
+        emit({"continue": True})
+        return 0
+
+    tool_input = payload.get("tool_input") or {}
+    file_path = tool_input.get("file_path")
+    if not file_path or not _is_deliverable(file_path):
+        emit({"continue": True})
+        return 0
+
+    try:
+        index_path = state_dir() / DELIVERABLE_INDEX_PATH
+        index_path.parent.mkdir(parents=True, exist_ok=True)
+        # Append the path; the Registry view de-duplicates on read.
+        import json
+        from datetime import datetime, timezone
+        record = {"ts": datetime.now(timezone.utc).isoformat(), "path": file_path}
+        with index_path.open("a") as f:
+            f.write(json.dumps(record) + "\n")
+    except Exception as exc:
+        log_error("deliverable-sync-failed", str(exc), {"file_path": file_path})
+
+    emit({"continue": True})
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run())