@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/docs/standards/briefing-contract.md

@@ -0,0 +1,161 @@
+---
+type: standard
+status: active
+scope: core
+appliesTo:
+  - All dispatches between an orchestrator and a worker
+---
+
+# Briefing Contract Standard
+
+The structured prompt an orchestrator hands to a worker. Every dispatch — whether a single subagent invocation, a task-group worker, or any future mechanism — uses this contract. The structure is mechanical because every missing field is a question the worker has to ask, and every question costs a round trip we cannot afford to a worker running detached.
+
+The big rule, drawn from Cognition's published failure analysis, is the **trace field**: every brief must include the reasoning that led to the task, not just the task description. Without it, workers re-derive context from scratch and make locally consistent but globally incompatible choices.
+
+---
+
+## The contract
+
+Every brief MUST include all of these fields, in this order. Section headings are mechanical — copy them verbatim.
+
+```markdown
+# <Task name>
+
+## Goal
+<one sentence — what success looks like>
+
+## Trace — why we're doing this
+<one paragraph — the reasoning that led to this task. Decisions already
+made, alternatives ruled out, the broader context the worker needs to
+make consistent choices. Do not skip this section. Cognition's Flappy
+Bird failure happens when workers are briefed without context: they
+embed conflicting assumptions and the integration step is forced to
+reconcile two miscommunications.>
+
+## Context
+<paths, files, decisions already made, constraints, relevant operator
+preferences. Extracted from the operator profile for this task — do not
+send the full profile. Reference standards and existing patterns by
+path so the worker reads the canonical source rather than a paraphrase.>
+
+## Tools and sources
+<which tools the worker should use, which to avoid, where to find
+authoritative information. If the worker should consult specific
+existing files, list them. If the worker should NOT touch certain
+files or systems, say so explicitly.>
+
+## Boundaries
+<what is in scope, what is out of scope. The boundary between "decide
+yourself" and "escalate to me" should be explicit. Reference the
+worker's autonomy envelope if relevant.>
+
+## Output format
+<exactly what the worker returns. File paths, document structure,
+length cap, format. Vague output specs produce vague outputs.>
+
+## Done when
+<concrete acceptance criteria the worker can self-check. "Tests pass"
+is not enough — say which tests, how to run them, what counts as pass.>
+
+## Escalation rule
+<when the worker should stop and escalate rather than guess. Default:
+"if any of the above fields is unclear or you encounter a constraint
+not covered here, stop and report the question rather than guessing."
+Customise per task.>
+```
+
+If your brief is missing any of these fields, **do not dispatch**. Write the missing field or fall back to in-thread execution.
+
+---
+
+## Field-by-field rationale
+
+### Goal
+
+One sentence, outcome-shaped. Not "implement function X" — "the system can do Y when Z". The goal is what the worker checks against when it thinks it might be done.
+
+### Trace — the load-bearing field
+
+This is the field most often missed and most often the cause of bad outcomes. The trace tells the worker *why* this task exists, what alternatives were considered, what decisions were already made and why. Without it, the worker re-derives context from scratch, and its derivation may not match the orchestrator's.
+
+Cognition's Flappy Bird example: one subagent built Mario-style art, another built incompatible bird sprite, the integrator had to reconcile two miscommunications. The cause was not poor briefing — it was *briefing without trace*. Each subagent made consistent local choices that were globally incompatible.
+
+The trace prevents this by sharing the orchestrator's reasoning. It does not need to be long. Three to six sentences is usually enough. What matters is that the worker reads it before acting.
+
+For task groups of 2+ workers, the trace lives in the shared context store and every worker reads it at the start of every action. The brief still includes a per-worker trace summarising the *worker-specific* reasoning, but the broader trace is in the context store.
+
+### Context
+
+The "what" — paths, files, constraints, operator preferences. Distinct from the trace (which is the "why"). Extracted and tailored — never the full operator profile. The worker should not need to read the operator profile to do its job; the orchestrator has already extracted what's relevant.
+
+Reference existing standards by path. Do not paraphrase a standard in a brief; the worker should read the canonical source so the standard's evolution propagates.
+
+### Tools and sources
+
+Explicit. Workers default to "use whatever tool seems right" which is sometimes wrong. If the task requires WebFetch, say so. If the task forbids modifying files outside a specific path, say so. If the worker should consult a specific reference document before starting, list it.
+
+### Boundaries
+
+Where decision authority sits. The default is "decide-alone within the goal, escalate everything else". A more constrained envelope might be "decide-alone within these specific files, decide-and-log everything else, escalate anything affecting external systems". A more permissive envelope might be "you have full latitude on architecture and implementation; report decisions in your final output".
+
+The autonomy envelope of the worker's role is the default. The brief can tighten it for this task but should not loosen it without explicit reason.
+
+### Output format
+
+Exactly what the worker returns. File paths, length cap, structure. Vague output specs produce vague outputs and force the orchestrator to re-derive structure when integrating.
+
+For detached dispatches: the worker writes a report file at a known path. The orchestrator reads the report, not the worker's full context.
+
+### Done when
+
+Concrete acceptance criteria. The worker checks against these before declaring done. "Tests pass" alone is not enough — which tests, how to run them, what counts as pass. Vague done criteria produce work that "looks done" but isn't.
+
+### Escalation rule
+
+The default escalation rule is the standard one: *if any field is unclear or you encounter a constraint not covered here, stop and report the question rather than guessing*. The brief can customise this — for example, "if you discover the existing implementation is broken in a way that affects your task, fix it and report; do not escalate for a same-file fix".
+
+The escalation rule is also where the brief makes peer coordination explicit when the worker is part of a task group: "do not communicate with other workers in this group directly; coordinate via the shared context store at <path>".
+
+---
+
+## Brief size signals
+
+A brief shorter than ~50 lines for a detached dispatch is **usually** under-specified. The fields above can all be terse, but the trace and the done criteria in particular are rarely complete in fewer than ten lines combined. If your brief is short, check whether you're missing the trace — that's the most common cause.
+
+A brief longer than ~300 lines is **usually** over-specified. If you're prescribing every step, you're not delegating, you're remote-controlling. Step back and ask whether the worker has enough autonomy to actually be useful.
+
+---
+
+## Bolt-on: worktree-isolated dispatches
+
+Any dispatch with `isolation: "worktree"` must include the following in its **Boundaries** section, verbatim or equivalent:
+
+> **Phase 0 — cwd verification:** Before ANY file-write or git op, run `pwd` and verify the output is inside `.claude/worktrees/agent-<id>/`. If not, `cd` to the worktree root before proceeding.
+>
+> **Worktree absolute-path rule:** Every absolute path passed to Write, Edit, MultiEdit, or Bash (for writes) MUST begin with the worktree root — typically `<project-root>/.claude/worktrees/agent-<id>/...`. Paths beginning with the main worktree root (no worktree segment) are the MAIN worktree and writing to them is forbidden for source changes. Absolute paths are still fine for READING context files from main — the rule applies to writes only.
+
+**Why both rules:** Phase 0 catches shell-cwd drift. The absolute-path rule catches Write/Edit tool calls that use absolute paths (the default behaviour in some agent runtimes), which bypass `cwd` entirely. Phase 0 alone is necessary but not sufficient; field experience has shown dozens of file changes landing in main via absolute paths despite a passing `pwd` check.
+
+**Recovery playbook** (when a worker writes to the wrong worktree):
+1. `cp <file-in-main> <worktree>` for every intended edit
+2. `git -C <main> checkout -- <file>` on files the worker themselves modified (surgical — never `git checkout .`)
+3. `rm <main>/<file>` for untracked files the worker created
+
+---
+
+## Bolt-on: specification quality checklist
+
+When a brief's **Context** or **Goal** includes consuming a structured payload (API response, config file, event schema) to gate decisions or rendering, the brief must address:
+
+1. **Effective-value rule.** If the payload contains multiple fields describing the same phenomenon (e.g. `overall.indicator` vs per-incident `impact`), the brief MUST define how to reconcile disagreement. Do not pick one field arbitrarily.
+
+2. **Shell-path test coverage.** If the output is UI rendered inside an iframed shell (a workspace shell or any future wrapper), the **Done when** must include at least one e2e test that navigates through the shell, not just direct-to-page loads.
+
+Both rules derive from incidents where individually-passing specs missed real user-path failures.
+
+---
+
+## See also
+
+- [`tooling.md`](./tooling.md) — the tooling standard that briefs reference for any worker that writes internal tooling.
+- Operator extensions: an operator's `operator/knowledge/engineering/standards/briefing-contract.md` (when present) MAY add operator-specific bolt-ons but MUST NOT relax this contract.

package/dist/engineering-pa-core/docs/standards/tooling.md

@@ -0,0 +1,240 @@
+---
+type: standard
+status: active
+scope: core
+appliesTo:
+  - core/tools/**
+  - operator/extensions/tools/**
+---
+
+# Tooling Standard
+
+Canonical contract for shared and library tools on the platform. This document is authoritative for every tool that ships in `core/tools/`, and the default contract for tools under `operator/extensions/tools/`. Operators MAY extend this standard with additional, more-restrictive rules in their own `operator/knowledge/engineering/standards/tooling.md`; they MUST NOT relax it.
+
+A tool that does not satisfy every section below is non-compliant. Compliance is enforced by code review, by the tooling lint described in [§17](#17-lint-enforcement), and by the readers of every README who treat it as the spec.
+
+See also: [`naming.md`](./naming.md) (when present in your tree), the per-tool README under `core/tools/<alias>/README.md`, and the broader principles document at `operator/knowledge/principles.md` if your operator layer ships one.
+
+---
+
+## 1. Identity & naming
+
+- Reverse-domain identity in `package.json` under `"name"`: `<org>.<scope>.<component>`, e.g. `ai.example.platform.svc`.
+  - `<scope>` is the functional domain (`platform`, `ops`, `knowledge`, …).
+  - `<component>` is a short identifier matching the CLI alias.
+- Short CLI alias — single lowercase word, verb-ish or noun-ish. The alias is the directory name under `core/tools/` (or `operator/extensions/tools/`) and the name of the shim in `bin/`.
+- Location: `core/tools/<alias>/`. The bin shim is `core/tools/<alias>/bin/<alias>`.
+- Reference implementations shipped in core: `core/tools/secrets/`, `core/tools/memory-sync/`, `core/tools/smoke/`, `core/tools/distill/`.
+
+## 2. Language and cross-platform posture
+
+- **Tools are written in Node.js. Full stop.** Shell scripts (`.sh`, `.ps1`, `.bat`, `.zsh`, `.fish`) are not acceptable tool implementations. The platform ships to macOS, Linux, and Windows — a Unix-shell tool silently breaks on Windows; a PowerShell tool silently breaks on Unix; a platform that depends on maintaining two parallel shell implementations is a platform with twice the surface area and half the confidence.
+- **The only acceptable shell files in the repo are thin launchers at repo root** (`dave.sh` + `dave.ps1`) which exist because *something* has to pre-date Node being available. Any logic inside those launchers that grows beyond "parse flags, find node, hand off" belongs in a Node.js tool they invoke.
+- Tools shell out to external **binaries** (git, docker, ssh, sops, age, node itself) as needed — those are cross-platform programs with native installers, not scripts. `node:child_process.spawn` does this fine without a shell in the middle.
+- Rationale: every `.sh`-only tool ever shipped on this platform created a Windows gap that wasn't noticed until an operator hit it. The cost of writing one tool in Node is always less than the cost of discovering the gap in production.
+
+## 3. Dependencies
+
+- **Zero runtime npm dependencies in the tool itself.** Tools use only the Node standard library.
+- Allowed stdlib surface: `node:util` (especially `parseArgs`), `node:child_process`, `node:fs/promises`, `node:path`, `node:os`, `node:test`, `node:assert/strict`.
+- No schema libraries, no CLI frameworks, no test frameworks, no lodash.
+- Rationale:
+  - **Auditability** — the entire tool is readable without third-party spelunking.
+  - **Supply-chain hygiene** — no transitive footguns, no lockfile churn.
+  - **Reproducibility** — a cloned repo runs immediately; no `npm install` step to fail.
+  - **Longevity** — the Node stdlib outlives every fashion in userland.
+- Runtime infrastructure that a tool *manages* (e.g. pm2 for native service supervision, docker for container orchestration) is a separate concern — those are external programs the tool shells out to, not dependencies of the tool.
+
+## 4. Project structure
+
+Canonical layout:
+
+```
+core/tools/<alias>/
+  bin/<alias>        # node shebang shim — one line
+  package.json       # name, version, type: module, no dependencies
+  README.md          # the spec (see §9)
+  src/
+    cli.mjs          # arg parsing, verb routing, exit-code translation
+    {domain}.mjs     # domain loaders (e.g. discover.mjs, manifest.mjs)
+    runner.mjs       # SOLE chokepoint for external effects (see §7)
+    commands/
+      {verb}.mjs     # thin glue per command
+    renderers/
+      {runtime}.mjs  # pure functions per target runtime
+  test/
+    fixtures/        # sample inputs, fake trees
+    *.test.mjs       # node:test, one per module under test
+```
+
+Per-directory rationale:
+
+- **`bin/<alias>`** — a single-line node shebang shim importing `src/cli.mjs`. The entry point is unambiguously the CLI module; the shim carries no logic.
+- **`src/cli.mjs`** — the only module that knows about `process.exit` codes. Commands return numbers or throw; `cli.mjs` translates to exit codes.
+- **`src/{domain}.mjs`** — pure loaders, validators, and domain helpers. No spawning, no SSH.
+- **`src/runner.mjs`** — the chokepoint (§7). Nothing else spawns processes.
+- **`src/commands/`** — glue. Each command file is thin: discover → render → run → format.
+- **`src/renderers/`** — pure functions per runtime. No I/O. Easy to test, easy to swap.
+- **`test/`** — `node:test` files alongside `fixtures/`. No separate test config.
+
+Smaller tools may compress this layout — a single `src/cli.mjs` is fine when there is no chokepoint to isolate. Larger tools must observe the boundaries above.
+
+## 5. CLI conventions
+
+- **Verb-noun pattern**: `<alias> list`, `<alias> status <target>`, `<alias> health <target>`. Verb first, target after.
+- **`--help` / `-h`** prints usage and exits `0`.
+- Arg parsing uses `node:util.parseArgs` with `strict: true`. No ad-hoc string splitting.
+- Subcommand routing is an explicit `switch` in `cli.mjs`. No dynamic dispatch, no plugin mechanism.
+- Unknown verbs exit `1` with usage printed to stderr.
+- Flags use long form primarily (`--device foo`). Short flags only for `--help` / `-h`.
+
+## 6. Exit code contract
+
+Every tool uses the same four exit codes:
+
+| Code | Meaning |
+|---|---|
+| `0` | OK |
+| `1` | Usage error (bad arguments, unknown target, ambiguous selector) |
+| `2` | Logical / operational failure (the thing you asked about is broken, unhealthy, missing) |
+| `3` | Transport / IO failure (ssh, spawn, network, disk) |
+
+Rationale: automation can distinguish *"you invoked me wrong"* from *"the world is broken"* from *"I couldn't even reach the world"*. Translation is centralised in `cli.mjs` — domain code throws errors carrying an exit-code property (e.g. `err.exitCode`), and the CLI wrapper maps them to `process.exit`.
+
+## 7. Module boundaries and the chokepoint pattern
+
+**Every external-effect API has exactly one place where it can happen.**
+
+This is a general principle, not a tool-specific detail. When an operation has safety properties that must always hold — rate limits, destructive guards, dry-run support, retry logic, auditing — those properties are enforced in a single chokepoint module. Scattered call sites mean scattered violations.
+
+- A canonical example: an SSH-driven tool exposes a `runner.mjs` that is the only module that spawns processes or opens SSH. It deliberately does **not** expose a "run a command N times remotely" API. Tools that need more remote work must build a bigger script and dispatch it once.
+- Renderer-per-runtime separation: `renderers/{runtime}.mjs` produces the script or config for a given substrate. Renderers are pure — no I/O. Commands drive the actual execution via the runner.
+- Domain concerns (`discover.mjs`, `manifest.mjs`) are separate from execution concerns (`runner.mjs`) are separate from presentation concerns (`renderers/`, `cli.mjs`).
+
+When designing a new tool, ask: *what operation, if it ever happens in the wrong place or the wrong way, causes the most damage?* That operation gets a chokepoint.
+
+## 8. Testing
+
+- Test runner: `node:test`. Assertions: `node:assert/strict`. Nothing else.
+- Layout: `test/*.test.mjs` plus `test/fixtures/` for sample inputs.
+- Run: `node --test core/tools/<alias>/test/*.test.mjs`.
+- **Dependency injection over mocking libraries.** Modules that touch the outside world expose a seam for tests — e.g. `runner.mjs` accepts (or can be monkey-patched to use) a fake spawner. No `sinon`, no `jest.mock`.
+- Coverage expectations:
+  - Every module has a test file.
+  - Commands are tested via fake renderers.
+  - Renderers are pure — tested directly as input-to-output functions.
+  - The runner is exercised against a real local command *and* against a fake spawner to verify framing and error paths.
+  - Real network / SSH never appears in the test suite.
+
+## 9. README as contract
+
+The README is the specification. It is not marketing, not a tutorial, not a changelog. Read-and-extend: a new contributor should be able to read only the README and understand the tool completely. Required sections:
+
+- **Identity** — reverse-domain name, one-line purpose.
+- **Status** — what's implemented vs deferred.
+- **Install / invoke** — how to run it.
+- **Commands** — every verb, synopsis, flags.
+- **Exit codes** — the contract from §6.
+- **Operational discipline rules** — non-negotiable constraints baked into the architecture (see §10).
+- **Project layout** — the directory tree with one-line rationale per entry.
+- **Tests** — how to run them.
+- **The tooling standard** — back-reference to this document, naming the sections that govern the tool.
+
+Tone: dense, declarative, no fluff. This is a contract.
+
+## 10. Operational discipline rules
+
+Some tools have non-negotiable safety rules baked into their architecture. These rules are documented in the README, enforced in the chokepoint module, and have no escape hatch API.
+
+**Example — SSH discipline.** A target host enforces, say, a 6-connection / 60-second SSH rate limit. Exceeding it locks the agent out and trips a firewall dead-man switch. Therefore every command of an SSH-driven tool performs at most one SSH call per cluster. For a `health` verb, all healthchecks are concatenated into a single bash script and dispatched once via `ssh <host> bash -s`. The runner deliberately has no "run remote command N times" API — there is no remote-loop footgun because there is no remote-loop API.
+
+When a tool has a similar constraint (rate limits, destructive operations, audit requirements), it follows the same pattern: one chokepoint, no loop API, rule written into the README.
+
+## 11. JSON conventions
+
+All JSON produced or consumed by tools uses **camelCase** property names. **No exceptions.** This matches the rule the Librarian enforces across the knowledge system. Values that are identifiers (service IDs, role IDs, map keys) keep their natural form; only the property *names* are governed.
+
+Snake_case and kebab-case property names are violations and must be corrected in place; consumers are updated in the same change.
+
+## 12. Reference implementations
+
+Concrete tools shipped in core that exemplify this standard:
+
+- [`core/tools/secrets/`](../../tools/secrets/) — vault CLI; clean chokepoint, hand-rolled validation, exit-code discipline.
+- [`core/tools/memory-sync/`](../../tools/memory-sync/) — bidirectional cache mirror; demonstrates the `2`-overload for "asked-thing-not-where-it-should-be" semantics.
+- [`core/tools/smoke/`](../../tools/smoke/) — health-check orchestrator; pure renderer + chokepoint runner pattern.
+- [`core/tools/distill/`](../../tools/distill/) — scheduled tool with the audit-record contract from §15.
+
+Read these before designing a new tool.
+
+## 13. Versioning
+
+Tools are versioned via the `version` field in their `package.json`. Release notes live in the README under a `## Changelog` heading, or in a dedicated `CHANGELOG.md` once the history grows large enough to warrant it. SemVer applies: the CLI surface and exit-code contract are the public API.
+
+## 14. Installing on PATH
+
+Tools live under `core/tools/<name>/` and are invoked through their `bin/<name>` shim. To make them callable as a bare command from any directory, the convention is:
+
+- A single directory `core/tools/bin/` at the repo root contains **symlinks** to each tool's `bin/<name>` shim.
+- The PATH addition is **one entry**, set by the operator (e.g. in `~/.zshrc` or via the launcher script). Adding a new tool means dropping one symlink — no PATH change.
+- The shim is `#!/usr/bin/env node` with one line: `import('../src/cli.mjs').then(m => m.main(process.argv.slice(2)))`. Node resolves the symlink to its target before resolving the relative `import`, so the symlink Just Works without any `--preserve-symlinks` ceremony.
+
+To install on a new machine:
+
+```bash
+ln -sf ../<tool>/bin/<tool> core/tools/bin/<tool>
+```
+
+That's the entire install procedure. Operators who automate this can add the PATH entry to whatever shell-rc loader they ship.
+
+## 15. Scheduled-tool audit-record contract
+
+Any scheduled tool that writes a `runs.jsonl` MUST append one record on every non-dry-run exit path — success, legitimate no-op, AND failure. Downstream freshness monitors (e.g. `tasks status` overlays) read `runs.jsonl`'s last line; if any exit path skips the append, the monitor sees stale data and either alarms falsely or stays silent on real outages.
+
+**Required fields:**
+
+| Field | Values | Notes |
+|---|---|---|
+| `status` | `ok`, `noop-*`, `fail-*` | Closed vocabulary. Prefix match for monitors: `noop-*` = fresh, `fail-*` = failing |
+| `ts` | RFC-3339 (`YYYY-MM-DDTHH:MM:SSZ`) | Must `new Date(ts)` without NaN. Filename-safe ts with dashes belongs only in filenames and commit-message slugs |
+
+**Rules:**
+
+1. Append on every non-dry-run exit path — success, no-op, AND failure.
+2. Skip the append on dry-run (no side effects).
+3. Tests must cover every exit path's audit record, not just the happy path.
+4. Backwards compat: consumers that fall back to `exitCode` when `status` is absent handle historical records.
+
+## 16. Operational artefacts must be gitignored
+
+Per-host operational files — audit logs (`runs.jsonl`), last-run timestamps, host-local caches, PID files — **must be in `.gitignore`**. They must never be git-tracked.
+
+**Why:** Any tool that combines (a) writes to a tracked file on every invocation (audit log, counter, timestamp) with (b) a precondition that fails on working-tree modifications will deadlock itself within one cycle. The first run dirties the tree; the next run sees the dirty tree and refuses to start; the refusal writes another audit line; the tree gets dirtier.
+
+This is not a hypothetical. Multiple scheduled tools across the platform have hit exactly this deadlock — `runs.jsonl` was tracked, the runner had a clean-tree precondition, and the schedule wedged for days.
+
+**Rule:** cross-host visibility of operational state is a legitimate need, but git-tracking the file is the wrong solution. Use a workspace endpoint, a sync job, or shared storage instead. The file stays local and gitignored; the visibility layer reads it on demand.
+
+## 17. Lint enforcement
+
+A `core/*` document, role definition, or tool source file must not refer to paths under `operator/`, `agents/`, `work/`, `projects/`, `.vault/`, or `schedules/`. Those directories are operator-owned; nothing in core is allowed to depend on them. Cross-layer references invert the layering and silently break for forks that have not populated their operator layer in the same shape as the originating fork.
+
+The `core/tools/lint-core-isolation/` tool enforces this rule. It scans `core/**/*.{md,mjs,js,ts,json}` and exits `2` with a list of violations on any cross-layer reference. CI runs the lint on every push and pull request.
+
+Allowed exceptions are limited and explicitly enumerated in the lint tool's README:
+
+- Comments or strings naming `operator/` purely as a *destination convention* (e.g. server code that locates the operator's knowledge tree at runtime). These are functional references, not documentation pointers, and they live in the lint's allowlist with a one-line justification.
+- Test fixtures that simulate the operator layer for the purpose of testing core code. These live under `core/tools/<tool>/test/fixtures/operator/` and the lint allowlist names that prefix.
+
+If you need a new exception, change the lint allowlist and explain in the same change why the reference cannot be eliminated. "It would be inconvenient to remove" is not a justification.
+
+---
+
+## Operator extensions
+
+Operators may layer additional rules on top of this standard at `operator/knowledge/engineering/standards/tooling.md`. The operator-side document SHOULD:
+
+- Cite this document as the base.
+- State only the operator-specific *additions* (e.g. operator-private CLI conventions, operator-private chokepoints, naming for operator-private runtime targets). It MUST NOT contradict any rule in this document.
+
+Tools under `operator/extensions/tools/` follow this standard as the floor; the operator's extensions raise it where needed.

package/dist/engineering-pa-core/docs/tools/distill.md

@@ -0,0 +1,230 @@
+# distill
+
+`@stravica-ai/engineering-pa-core` › `distill` — the librarian distillation
+sweep runner.
+
+Launches a non-interactive Claude Code session as the Librarian, hands it
+the repo-wide distillation prompt, and writes its outputs into the working
+tree. **It does not commit, pull, fetch, or push.** Git is owned by the
+per-host `sync` CLI (`packages/cli/src/sync/`); distill is a pure file
+writer.
+
+Designed for cron: quiet on success, loud on failure, exit-code accurate
+so cron mail / monitoring can catch breakage.
+
+## Status
+
+Implemented: `run`, `run --dry-run`, `--help`.
+
+## Install / invoke
+
+Via the core package's bin shim — from an operator repo:
+
+```
+pnpm exec distill run
+pnpm exec distill run --dry-run
+pnpm exec distill --help
+```
+
+(or directly in this repo: `node packages/core/bin/distill run`.)
+
+Scheduled by the operator repo's `schedules/distillation-sweep.json`
+(cadence is operator-configured). The scheduler invokes it from the
+operator repo root via cron. The companion sync schedule (e.g.
+`schedules/dave-sync.json`, every 30 minutes on the same host) picks up
+any file changes distill produced.
+
+## Commands
+
+### `distill run`
+
+1. Resolve prereqs — repo root (walks up to `.git`), `paName` from
+   `operator/config/preferences.json`, librarian definition per the
+   resolution order below, `claude` on `$PATH`, log dir
+   `<repoRoot>/.cache/distill/logs/` (created if missing; gitignored per
+   tooling standard §16).
+2. Count markdown observations under `agents/*/staging/` (depth ≤ 2,
+   excluding `_archived/`). If zero, append a `noop-empty-staging`
+   audit record and exit 0.
+3. Invoke `claude` with the librarian definition as an appended system
+   prompt and the distillation instructions as the positional prompt.
+   Output is written to `<repoRoot>/.cache/distill/logs/<ts>.log`.
+4. Append a one-line JSON audit record to
+   `<repoRoot>/.cache/distill/logs/runs.jsonl` (schema below).
+5. Exit 0 (ok) or 3 (claude transport failure).
+
+### Librarian definition resolution
+
+The system prompt appended to the sweep session is resolved in this
+order (highest precedence first):
+
+1. **Explicit `librarianDef` option** (tests pass fixture paths here).
+   The caller controls the whole prompt; no supplement is applied.
+2. **Full operator override** at
+   `operator/extensions/roles/librarian/definition.md` (under the
+   discovered repo root). The operator has taken ownership of the whole
+   prompt: the file is used byte-for-byte and **no supplement is
+   appended, even if `overrides.md` also exists**. This preserves exact
+   back-compat with pre-supplement operator repos.
+3. **Bundled definition + operator supplement.** When there is no full
+   override but `operator/extensions/roles/librarian/overrides.md`
+   exists, the composed prompt is the bundled definition followed by the
+   supplement, joined by an explicit precedence statement: wherever the
+   supplement conflicts with the bundled text, **the supplement wins**;
+   where it is silent, the bundled definition applies unchanged. This is
+   the recommended way to customise routing (e.g. a repo-specific
+   operational-rules destination) without forking — and silently
+   diverging from — the whole bundled definition.
+4. **Bundled definition alone**
+   (`engineering-pa-core/roles/librarian/definition.md` inside the
+   package tree).
+
+A supplement file that exists but is empty or whitespace-only is treated
+as absent (outcome 4): appending an empty supplement under an
+operator-wins banner would claim a customisation that does not exist.
+The dry-run plan reports which outcome applied — the resolved definition
+path and byte size, the supplement path and byte size (or `none`, or
+`empty — ignored`), and the composed total.
+
+**Git changes the librarian produces are committed by sync, not here.**
+Distill stops at the audit-record write; the sync CLI's next tick on
+the same host picks up the staging-area changes, the deletions from
+`agents/*/staging/`, the additions/updates under `operator/knowledge/`
+and `operator/profile/`, etc.
+
+### Why the change (2026-05-11)
+
+Previously distill did `git status / fetch / pull --rebase` as a pre-flight
+and `git add / commit / push` as a post-flight. This raced with the other
+cron writers on the same host (`wsd-ingest` every 15m, `upstream-triage`
+every 30m), each doing the same thing on their own clocks. A ~2-second
+window between `isTreeClean` and `pull --rebase` was enough to surface
+`fail-rebase` audit records — including the 2026-05-11 03:00 BST alert.
+The fix is structural: cron tools stop touching git; a single per-host
+writer (the `sync` CLI, `packages/cli/src/sync/`) handles all of it.
+
+### `runs.jsonl` audit-record schema
+
+One JSON object per line, camelCase keys (§11 of the tooling standard):
+
+| Field | Type | Description |
+|---|---|---|
+| `ts` | string | RFC-3339 / ISO-8601 UTC timestamp (e.g. `2026-04-16T02:00:06Z`). Round-trips cleanly through `new Date()`. |
+| `status` | string | Semantic status, closed vocabulary (see below). |
+| `exitCode` | number | Process exit code (0 / 2 / 3). Consumers that only need pass/fail can ignore `status`. |
+| `durationSec` | number | Seconds elapsed. Typically 0 for pre-claude early exits. |
+| `stagingCount` | number | Result of `countStagedObservations`. 0 on `noop-empty-staging`. |
+| `log` | string \| null | Basename of the per-run log file, or `null` when no log file was created (pre-claude early exits). |
+| `reason` | string | Human-readable one-liner. Present on every non-`ok` record; omitted on `ok`. |
+
+Status vocabulary (closed set):
+
+| Status | exitCode | When |
+|---|---|---|
+| `ok` | 0 | Claude ran successfully (changes, if any, will be committed by sync). |
+| `noop-empty-staging` | 0 | No observations in `agents/*/staging/` — healthy no-op. |
+| `fail-claude` | 3 | Claude exited non-zero. |
+| `fail-cli-bootstrap` | 1 / 2 | parseArgs / startup failure before runDistill was reached. |
+
+Statuses that USED to exist but no longer can (the git pre/post-flight was removed):
+`fail-dirty-tree`, `fail-rebase`, `fail-git`. Historical records carrying
+those statuses remain valid and consumers should still recognise them.
+Git is now owned end-to-end by the per-host `sync` CLI
+(`packages/cli/src/sync/`).
+
+Consumer contract: monitors should treat `status == 'ok'` and any
+`noop-*` as healthy; any `fail-*` as failing. For backwards compatibility
+with historical entries (pre-2026-04-22) that lack the `status` field,
+derive from `exitCode`: 0 ⇒ healthy, non-zero ⇒ failing.
+
+### `distill run --dry-run`
+
+Same as step 1–2, then print what *would* be invoked (including the
+explicit "git: none — sync (core/tools/sync) picks up changes" line) and
+exit 0. Never spawns `claude`, never writes `runs.jsonl`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | OK — nothing to distill, or sweep completed. |
+| `1` | Usage error (unknown verb, bad flag). |
+| `2` | Prerequisite missing (no preferences, no paName, no librarian definition, no `claude` on PATH). |
+| `3` | Transport / IO failure (claude exited non-zero). |
+
+## Operational discipline rules
+
+1. **One claude invocation per run.** The runner has no "invoke claude
+   multiple times" API. Bigger sweeps go in the prompt; they do not
+   become more spawns.
+2. **No shell interpolation.** Every `spawn()` call passes arguments as
+   an array with `shell:false`. User-supplied data (observation filenames,
+   paths with spaces) flows through untouched — a malicious name cannot
+   become a shell command.
+3. **Chokepoint for every external effect.** `src/runner.mjs` is the only
+   module that spawns processes or reads wall-clock time. Tests replace
+   it with a scripted fake to exercise every flow without touching the
+   filesystem, the network, or claude.
+4. **No git, ever.** Distill must not spawn `git` of any kind — that
+   discipline is the structural fix for the racy pre/post-flight pattern.
+   The regression test `regression: distill spawns NO git commands at any
+   point` exists specifically to enforce this; if a future maintainer
+   re-introduces a git call, that test will fail.
+
+## Project layout
+
+```
+packages/core/
+  bin/distill              Node shebang shim. One line.
+  docs/tools/distill.md    This file. The contract.
+  src/distill/
+    cli.mjs                Arg parsing (node:util.parseArgs), verb routing,
+                           exit-code translation.
+    run.mjs                Orchestrator. One function per step of the sweep.
+    prereqs.mjs            Repo root, paName, librarian def, claude-on-PATH.
+    staging.mjs            Counts agents/*/staging/*.md (depth ≤ 2, no _archived).
+    prompt.mjs             DISTILL_PROMPT + claudeArgs(). Pure strings.
+    runner.mjs             Chokepoint — the only module that spawns processes
+                           and reads the clock. Takes a spawner factory so the
+                           tests can inject a fake.
+  test/distill/
+    fixtures/              Synthetic repo trees (clean, empty, missing-pieces).
+    *.test.mjs             node:test.
+```
+
+(`src/git.mjs` and `test/git.test.mjs` were removed in the 2026-05-11
+sync refactor — they tested porcelain-Z parsing that is no longer
+needed.)
+
+## Tests
+
+```
+node --test packages/core/test/distill/*.test.mjs
+```
+
+Tests use dependency injection over mocking libraries. Real git, real
+claude, and real filesystem mutations (outside of a temp dir) never
+appear in the suite.
+
+Coverage:
+
+- `staging.test.mjs` — staging counter with and without `_archived/`.
+- `prereqs.test.mjs` — every error path on the prerequisite ladder, plus
+  the four-step librarian-definition resolution order (explicit opt >
+  full override > bundled + supplement > bundled alone).
+- `run.test.mjs` — empty staging (audits `noop-empty-staging`),
+  dry-run, happy path, claude failure (audits `fail-claude`), two
+  regression guards that fail if a future change re-introduces any
+  `git` invocation, and the librarian-definition composition contract:
+  full-override back-compat (byte-for-byte, supplement ignored),
+  bundled + supplement composition with the operator-wins precedence
+  statement, whitespace-only supplements treated as absent, and dry-run
+  reporting of source paths + byte sizes under each resolution outcome.
+- `cli.test.mjs` — `--help`, `-h`, no-args, unknown verb, unknown flag.
+
+## The tooling standard
+
+This tool follows [the tooling standard](../standards/tooling.md)
+(§1 identity, §2 Node-only, §3 zero deps, §4 structure, §5 CLI,
+§6 exit codes, §7 chokepoint, §8 testing, §11 camelCase JSON, §15 audit-record,
+§16 gitignored operational artefacts).