muse-crew 0.13.2 → 0.14.0

package/docs/decisions/workflow-core.md

@@ -0,0 +1,234 @@
+# Decision history: workflow core
+
+Relocated from workflow source comments during H5 (2026-09-18). The workflows keep only the relied-upon invariant inline; the full decision history lives here.
+
+<a id="verdict-reask"></a>
+## Verdict re-ask
+
+Invariant: a verdict-step report that fails extractVerdict gets up to two bounded re-ask calls; the re-ask agent transcribes, never decides; exhaustion keeps fail-closed behavior.
+
+Applies to: standard, bugfix, chore.
+
+```
+// Verdict re-ask (bug cd18ccc2): a verdict-step report that fails
+// extractVerdict is not failed immediately. Stochastic verdict-line
+// non-compliance (the agent did the work but omitted or garbled the VERDICT
+// line) gets up to two bounded follow-up agent() calls whose only job is to
+// read the preserved report and emit exactly one VERDICT line. The verdict
+// is still extracted mechanically by extractVerdict — the re-ask agent
+// transcribes, never decides the phase outcome. Each attempt uses a fresh
+// stable-key suffix so a cached failure can never replay deterministically.
+// Exhaustion keeps the existing fail-closed behavior. This is structure, not
+// prompt hardening: no instruction text was stern-ified to get here.
+```
+
+<a id="park-contract"></a>
+## Park contract + terminal cleanup
+
+Invariant: parking is one atomic parktask action; a failed park reports failed (retryable); terminal cleanup releases the lock and reclaims only fully-merged work.
+
+Applies to: standard, bugfix, chore.
+
+```
+// Park the task for human attention and end the run. "blocked" is never
+// manually authored — the dashboard derives it mechanically from unmet
+// dependencies — so a workflow outcome that needs a human parks the task
+// instead. Parking is one atomic dashboard action (parktask): the parked
+// state and the explanatory note land in one transaction, never half.
+// The dispatcher skips parked tasks; a human moving parked→todo
+// mechanically resets the retry counters. Returns the workflow result
+// envelope the launcher sees. If the park call itself fails, the run
+// reports "failed" (retryable) so the next tick re-attempts the park —
+// a lost park is never reported as parked.
+// Terminal cleanup: the run's last act at every park/fail boundary. A run
+// that parks or fails must not leak its worktree, branch, or merge lock.
+// The lifecycle's terminal-cleanup releases the lock unconditionally and
+// reclaims the worktree+branch ONLY when the task branch is fully merged
+// into main (then it is redundant); unmerged work is preserved for the
+// human by design. Fire-and-forget with one bounded retry — the merge-lock
+// lease expiry and the orphan sweep are the backstop for a dead transport.
+```
+
+<a id="closeout-envelope"></a>
+## Closeout transport envelope
+
+Invariant: the work agent returns the runtime's native transport envelope with no schema; the verdict is extracted mechanically by extractVerdict — never by an agent.
+
+Applies to: standard, bugfix, chore.
+
+```
+  // Work agent returns the runtime's native envelope {"status": "ok",
+  // "result": "<prose>"} with no schema. The runtime requires JSON output;
+  // the envelope is its own documented shape, so there is nothing for the
+  // agent to improvise. The workflow receives the prose report as a plain
+  // string. The verdict is still extracted deterministically from the report
+  // text by extractVerdict below — never by an agent.
+```
+
+<a id="extract-verdict-contract"></a>
+## extractVerdict contract
+
+Invariant: the verdict is the LAST VERDICT: PASS/FAIL line in the report; extraction is mechanical and deterministic.
+
+Applies to: standard, bugfix, chore.
+
+```
+  // The verdict is the LAST VERDICT: PASS/FAIL in the report (contract: end
+  // your report with the verdict). This ignores literal VERDICT strings echoed
+  // from the worker's instructions (which contain quoted examples). Fail
+  // closed if: no verdict found, the last verdict is not in the trailing 100
+  // chars (verdict must be at the end), or conflicting verdicts appear in the
+  // trailing 200 chars. Word boundary prevents "PASSING" matching as PASS.
+```
+
+<a id="rework-attempt-key"></a>
+## Rework attempt key
+
+Invariant: rework attempts are keyed deterministically; the count is a parameter because chore names it differently.
+
+Applies to: standard, bugfix, chore.
+
+```
+// replay-key scoping for bug 1b8bb875 — runtime keys agent() calls by explicit key per workflow process; on in-process rework a re-executed phase must mint fresh keys; uses the same -r<N> suffix as the phase loop; pure function of inputs, no clock, no randomness (determinism contract). The count is a parameter because chore.js names the counter reworkCount while standard.js/bugfix.js name it totalReworkCount.
+```
+
+<a id="ux-doctrine-mirror"></a>
+## UX doctrine mirror
+
+Invariant: workflows mirror the UX doctrine map inline (relative-import support unverified); prompts read UX_DOCTRINE_PATH.
+
+Applies to: standard, bugfix, chore.
+
+```
+// UX doctrine page: the shared UX bar for this run's surface, resolved
+// mechanically — every phase prompt reads UX_DOCTRINE_PATH, never a
+// hardcoded filename. Canonical map: lib/ux-doctrine.js (mirrored here as a
+// one-liner because the workflow runtime's relative-import support is
+// unverified; tests pin the mirror). Null on unclassified surfaces: no
+// shared page, and prompts say so instead of naming the wrong one.
+```
+
+<a id="replay-key-scoping"></a>
+## Replay-key scoping
+
+Invariant: runtime keys agent() calls by explicit key per workflow process; on in-process rework a re-executed phase mints fresh keys with the -r<N> suffix.
+
+Applies to: standard, bugfix, chore.
+
+```
+// replay-key scoping for bug 1b8bb875 — runtime keys agent() calls by explicit key per workflow process; on in-process rework a re-executed phase must mint fresh keys; uses the same -r<N> suffix as the phase loop; pure function of inputs, no clock, no randomness (determinism contract). The count is a parameter because chore.js names the counter reworkCount while standard.js/bugfix.js name it totalReworkCount.
+```
+
+<a id="transport-retry"></a>
+## Transport retry
+
+Invariant: the work-agent agent() call can throw even when the agent did the work; retry boundedly with fresh keys before failing closed; re-entry is safe.
+
+Applies to: standard, bugfix, chore.
+
+```
+// Transport retry: the work-agent agent() call can throw even when the agent
+// did the work. Stochastic envelope non-compliance (bare prose instead of
+// the native {"status":"ok","result":"..."} envelope) trips the runtime's
+// JSON-candidate heuristic when the prose contains a {...}-looking
+// substring — canary 39457ee9's QA report quoted the change's own
+// {/* ... */} JSX comment, the runtime tried to parse it as JSON, threw,
+// and the workflow discarded a complete VERDICT: PASS report as "no output".
+// The verdict re-ask covers an unreadable verdict inside a RECEIVED report;
+// this covers the report never arriving. The assignment is retried boundedly
+// with fresh keys (never a cached replay) before failing closed. Re-entry is
+// safe: lifecycle scripts answer REUSED for existing worktrees/branches, the
+// retry trailer tells the agent to check existing state first and report
+// rather than duplicate completed side effects, and the rework path already
+// re-runs Build after rejection — Build re-entry is an established pattern.
+```
+
+<a id="honest-classification"></a>
+## Honest classification
+
+Invariant: classify work-agent calls that yield no usable output honestly.
+
+Applies to: standard, bugfix, chore.
+
+```
+  // Honest classification of a work-agent call that yielded no usable
+  // report, with the per-attempt evidence preserved in the session notes.
+  // Two distinct cases:
+  // - agent() THREW: the runtime discarded output it could not machine-read
+  //   (e.g. prose tripping the JSON-candidate heuristic). The raw output is
+  //   gone — the workflow never received it — so the surviving error text is
+  //   recorded here instead. (An earlier comment claimed the raw output was
+  //   "preserved in the run record"; that was false — nothing preserved it —
+  //   and the claim is removed.)
+  // - agent() RETURNED EMPTY without throwing: the child produced nothing
+  //   usable. Each attempt's outcome is the evidence.
+  // attempts: [{threw, error, outcome}, ...], in order.
+```
+
+<a id="oneshot-recovery"></a>
+## One-shot recovery
+
+Invariant: the dispatcher sets input for one-shot recovery routing.
+
+Applies to: standard, bugfix, chore.
+
+```
+// One-shot recovery routing: the dispatcher sets inputs.next_phase when it
+// routes this run via an explicit recover-task redirect. The value is
+// consumed (cleared) atomically by the successful self-claim below:
+// claim-task takes expected_next_phase and clears the matching next_phase in
+// the same transaction as the winning session insert, so no platform death
+// can slip between claim and consumption and replay the routing. A stale or
+// superseded routing survives — only an exact match clears.
+// what the dispatcher routed on.
+```
+
+<a id="discarded-reason"></a>
+## Discarded reason
+
+Invariant: the runtime threw the output away; reason is discarded.
+
+Applies to: standard, bugfix, chore.
+
+```
+  // reason: "discarded" (the runtime threw the output away - it could not be
+  // machine-read), "empty" (agent() returned without throwing but produced
+  // nothing usable), "no-tools" (the worker's TOOL CHECK reported
+  // artifact_tools: missing), or "no-transport" (the worker's TOOL CHECK
+  // reported shell_transport: unavailable).
+  // The trailer tells the retry what to expect, not just to try again.
+```
+
+
+<a id="h5-probe-blocked"></a>
+## H5 import probe: blocked, extraction refused (2026-09-18)
+
+Invariant: workflow scripts carry no imports; shared logic is mirrored inline, never imported.
+
+Applies to: standard, bugfix, chore.
+
+```
+# H5 (2026-09-18): the Phase 1 plan was probe-gated on the workflow runtime
+# resolving relative imports of a sibling lib/ module. The probe could not
+# be run: no platform launch capability exists in the build environment
+# (workflow_launch is a platform capability, not a shell command; no local
+# launcher exists), and a local node ESM check would prove nothing about the
+# platform runtime — so it was refused, not faked. Outcome: PROBE-BLOCKED.
+# Extraction without the probe would ship an unverified import into a
+# launch-gated script — a worse defect than the size defect. The failover
+# was measured in-file subtraction: delete dead buildVisualCapturePlan and
+# relocate decision-history narration to docs/decisions/ (this file),
+# keeping inline only the relied-upon invariant. The import question stays
+# an OPEN PLATFORM FINDING; helper extraction (and the Phase 2 publish-block
+# unification) is sequenced follow-up once the runtime's module support is
+# proven by a real launch.
+# Probe outcome, recorded 2026-09-18: the helper-extraction probe was
+# refused as unverified — workflow scripts have no module system
+# (typeof require === "undefined" on the platform runtime), so extraction
+# would have shipped an unverified mechanism into a launch-gated script.
+# The relocation-to-docs/decisions/ failover above was used instead.
+# Sequencing: the next publish-path change must be preceded by the Phase 2
+# publish-phase unification (or equivalent subtraction). bugfix.js sits at
+# 244,349 bytes — 1,411 bytes of headroom under the 245,760-byte target —
+# so an ad-hoc cut under gate pressure is not a plan.
+```

package/docs/publish-unknown-recovery.md

@@ -0,0 +1,113 @@
+# Publish-unknown recovery (blocker 15, 2026-09-18)
+
+When a standard/bugfix Publish parks with "Publish outcome unknown", the
+artifact-edit trigger went out fire-and-forget and no receipt came back —
+async was planned for, receipt-less was not. The unknown-recovery loop
+closes that gap without re-issuing blindly.
+
+## The note is the state machine
+
+Recovery state lives in the task's `note` events, keyed on machine-written
+`publish: <transition>` markers. Deterministic code (`lib/crew-api.js`) owns
+every transition; the cron tick (Step 4.4) is only the ferry between the
+deterministic steps. The initial park note is the workflow's
+"Publish outcome unknown …" note (no `publish:` marker — the scan matches it
+explicitly); every transition after that is machine-written.
+
+State diagram (latest `publish:` note wins; history is the retry budget):
+
+```
+"Publish outcome unknown" park
+  (< 30m) ──waiting──> scan: waiting (leave alone)
+  (>= 30m) ──scan──> publish: unknown-recovery-claimed <expiry>   (1h lease)
+       │
+       ├─ tick runs lib/classify-publish-absence.js, then
+       │  record-unknown-classification (CAS on the claim expiry):
+       │
+       ├─ verified ──────────> publish: verification-requested <commit>
+       │                        (content IS present; Step 4.5 verifies;
+       │                         ledger: unknown-resolved)
+       ├─ provably-dropped ──> publish: dropped <commit>
+       │                        (queues the retry protocol, next tick)
+       ├─ applied-not-built / ambiguous ──> publish: ambiguous <commit>
+       │                        (terminal; ledger: unknown-classified)
+       ├─ superseded ────────> publish: superseded <commit>  (terminal)
+       └─ deferred ──────────> (no note; the claim expires; the next scan
+                                re-claims and re-classifies)
+```
+
+Retry protocol (Step 4.4, for `publish: dropped` with a free budget):
+
+```
+publish: dropped
+  ── tick: HEAD == commit? no ──> publish: retry-superseded (terminal)
+  ── tick: acquire merge lock publish-retry:<task> (600s); held ──> stop, retry next tick
+  ── tick: re-read content in the lock (classifier)
+       ├─ not provably-dropped ──> record-retry-recheck routes it
+       │    (verified → verification-requested; ambiguous → terminal;
+       │     superseded → terminal; deferred → no-op)
+       └─ provably-dropped ──> publish: retry-intended <commit> <ts>
+            ── trigger (same child shape as the first attempt)
+            ├─ ARTIFACT_EDIT_REFUSED ──> publish: retry-refused (terminal)
+            └─ no refusal ──> publish: retry-issued <commit>
+                 ──> publish: verification-requested <commit> not-before=<ts+20m>
+                     (Step 4.5 skips not-before entries until the window passes)
+                 ──> one -retry1 ledger entry (best-effort)
+            ── release the merge lock (every path)
+```
+
+Crash recovery (fail closed, never re-trigger blind):
+
+- `publish: retry-intended` without `retry-issued` → the next scan mirrors
+  `verification-requested` with `not-before=intended+20m`. The trigger may
+  or may not have gone out; content verification is the arbiter.
+- `publish: retry-issued` without a mirrored request → the next scan writes
+  the missing mirror.
+- Exactly one retry per task, enforced from note history: the scan emits
+  `retry_due` only when no `publish: retry-issued` exists in the task's
+  history — including a retry for an earlier unknown attempt on a reworked
+  task. When the budget is spent, the drop is terminal: `publish: ambiguous`.
+
+## Commands
+
+- `scan-publish-unknown` — the cron scan (Step 4.5 of the old numbering).
+  Returns `{ waiting, due, retry_due, mirrored, skipped }`. `due` entries
+  ferry the classifier inputs: `commit`, `trigger_ts` (from the `submitted`
+  ledger entry — never a time window), `park_ts`, `slug`, `repo_path`,
+  `base` (provenance `source_commit`, else the empty tree), and
+  `claim_expiry` for the record CAS. `retry_due` entries ferry the retry
+  inputs (`commit`, `attempt`, `slug`, `repo_path`, `base`, `ledger_path`).
+- `record-unknown-classification --json '{task_id, claim_expiry, decision}'`
+  — routes the classifier's decision; CAS on the claim expiry (a stale tick
+  records nothing).
+- `record-retry-recheck --json '{task_id, decision}'` — routes the retry
+  protocol's in-lock content re-read; CAS on latest being `publish: dropped`.
+- `resolve-publish-unknown` — the manual one-shot for a single parked task
+  (unchanged; the audit-window contract, not the classifier).
+
+## Classifier (lib/classify-publish-absence.js)
+
+Decides, from the task's repo and the platform's on-disk state, whether the
+dropped edit is proven:
+
+- `verified` — the content IS present (the platform applied it; the receipt
+  was the only thing lost). Never re-issue.
+- `provably-dropped` — the old source is live AND the manifest shows no
+  build since the trigger. Only this decision may retry.
+- `applied-not-built` — the new source is live but no build ran (the
+  trigger reached the platform but the build didn't). Ambiguous outcome,
+  terminal: a retry would double-apply.
+- `ambiguous` — the content check is inconclusive. Never retry blind.
+- `deferred` — not yet quiesced; re-check next tick.
+- `superseded` — HEAD moved past the attempt's commit. Terminal.
+
+The classifier's verified path requires the CURRENT manifest to be a new
+build identity: `built_at` advanced past the trigger AND `content_sha256`
+differs from the pre-trigger baseline the workflow snapshots into the
+submitted ledger entry (design §1.9 — defeats a replayed manifest). When
+the baseline is unavailable the classifier falls back to the time-based
+advance check and notes it; the Step 4.5 verifier (`lib/verify-publish.js`)
+is the strict gate and fails closed without a baseline before stamping.
+Build-in-flight is checked twice bracketing the content read via manifest
+state change (no mtime heuristics), and the suite carries add-only and
+removal-only regression fixtures.

package/docs/visual-verdict.md

@@ -98,13 +98,12 @@ Triggered by the Capture phase when the task is experiential and no
 baseline evidence is recorded yet. The workflow logs
 `baseline: requested (attempt N)` and parks; the parent then:
 
-1. Run the deterministic capture plan:
-   `buildVisualCapturePlan(taskTitle, taskDescription, "baseline", captureTargets)`
-   — desktop 1440x900 top, desktop 1440x900 target-centered, mobile 390x844
-   target-centered, hover, keyboard focus, active/pressed where applicable,
-   plus console error count, the ARIA tree of the target region, and any
-   horizontal overflow. Capture targets come from the Map step's
-   `capture_targets:` line; if none, fall back to the task description.
+1. Run the deterministic capture plan — desktop 1440x900 top, desktop
+   1440x900 target-centered, mobile 390x844 target-centered, hover,
+   keyboard focus, active/pressed where applicable, plus console error
+   count, the ARIA tree of the target region, and any horizontal overflow.
+   Capture targets come from the Map step's `capture_targets:` line; if
+   none, fall back to the task description.
 2. Save the captures under `$CREW_HOME/task-evidence/<task-id>/baseline/`.
 3. Log the task note event:
    `baseline: captured <space-separated evidence refs>`

package/lib/AGENTS.md

@@ -24,8 +24,10 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `ux-doctrine.js` — UX-surface doctrine page resolution (2026-09-17): the canonical map from `environment_type` to the crew's shared UX bar (`artifact` → `docs/artifact-ux.md`, `terminal` → `docs/terminal-ux.md`; null/unknown → no page). Pure and deterministic: `doctrinePage(env)`, `doctrinePath(crewHome, env)`, `doctrinePageExists(crewHome, env)`; CLI `--page <env>` / `--path <crewHome> <env>`. Workflows mirror the map inline (one line — the workflow runtime's relative-import support is unverified) and tests pin the mirror against this file.
 - `serve-artifact.js` — local server for a built TS space for experiential QA (2026-09-14): serves `<space-dir>/client/dist` statically and dispatches POST `*/actions` to the compiled server actions with a locally-built Ctx. Prints `READY port=<n>` then serves until killed. Read-only w.r.t. the space directory. Fidelity: the served client and action handlers are the artifact's own built code; the Ctx is locally built (privileged handlers run from the space's own `server/dist/privileged.js` when present; blobs are stored in a per-run temp dir and served back at `/__blobs/<key>`); environment is inherited from the caller. It is not the hosted runtime — tasks that cannot be judged under it must report `NOT POSSIBLE: <reason>`.
 - `readback-disk.js` — deterministic publish content sensor (2026-09-16): reads the on-disk tree the artifact is built/served from and emits the machine-readable findings block (`FILE:`/`ADDED:`/`REMOVED:`/`END_FILE`) that `verify-publish.js` judges. The primary sensor — the LLM-inspector path (`build-readback-request.js`) is manual-fallback only since `artifact_inspect` was removed by the platform 2026-09-14.
+- `publish-content.js` — shared ESM content-primitives for publish verification (2026-09-18, blocker 15): diff parsing (`parseDiff`), findings parsing (`parseFindings`), old-tree occurrence counting (`makeOldCounter`), and the discriminating-line / collision-exemption logic (`discriminatingLines`). Unifies `verify-publish.js` and the unknown-recovery classifier on one judgment so the two paths can never disagree about what a diff proves.
+- `classify-publish-absence.js` — deterministic six-way classifier for publish-parked UNKNOWN outcomes (2026-09-18, blocker 15): decides from durable signals only — the pre-trigger manifest baseline (captured by the workflow into the submitted ledger entry; design §1.9) vs the current manifest's `built_at`/`content_sha256`, `git diff <base> <commit>` discriminating lines against the on-disk source tree, and HEAD vs the publish commit. Outcomes: `provably-dropped` (source shows pre-edit state, manifest NOT advanced past the trigger, HEAD == commit, aged past quiesce — retry once), `verified` (manifest advanced past the trigger AND content_sha256 differs from the pre-trigger baseline — a new build identity, not a replayed manifest; falls back to the time-based advance check with a note when the baseline is absent, and the Step 4.5 verifier fails closed without a baseline), `applied-not-built` (platform build-emission failure; no retry — the 2026-09-12 re-trigger hazard), `ambiguous` (any inconclusive shape — no retry by design), `deferred` (build in flight — manifest changed during the content read, or built within the settle window — or park below quiesce; not a verdict, retry later), `superseded` (HEAD != commit — never retry the old commit). Retry budget is consumed by the classification itself, never by the edit attempt. Never reads the wall clock except for recovery timing; addition-only and removal-only diffs are vacuously satisfied on their empty side.
 - `build-readback-request.js` — builds the LLM-inspector read-back `verbatim_request` from the merge commit's diff (2026-09-14): carries the merged diff as the expected change and asks for an independent read of the artifact's actual source. Retained as the manual fallback; the deterministic `readback-disk.js` is the primary sensor.
-- `verify-publish.js` — mechanical publish verification judge (2026-09-14/16): certifies the read-back findings block against `git diff` (strict `FILE:`/`ADDED:`/`REMOVED:`/`END_FILE` parsing, every added line PRESENT / every removed line ABSENT, HEAD==commit supersession check) and only then stamps provenance. Binary files, mode-only changes, and fully-colliding added hunks fail closed as `unverifiable-content` (2026-09-16, critic findings 1/5) — they can never vacuously stamp. Content-mismatch, unreadable-result, superseded, and stamp failures exit 1 with `publish: verification-failed` and no stamp. Collision exemption (2026-09-15): a removed line occurring in the old tree strictly more times than the diff removes is exempt from ABSENT (zero discriminating power); computed from `git show <base>:<path>`, never the working tree.
+- `verify-publish.js` — mechanical publish verification judge (2026-09-14/16; shared primitives 2026-09-18): certifies the read-back findings block against `git diff` (strict `FILE:`/`ADDED:`/`REMOVED:`/`END_FILE` parsing, every discriminating added line PRESENT / every discriminating removed line ABSENT, HEAD==commit supersession check), then the design §1.9 manifest-freshness gate (current manifest `built_at` advanced past the trigger AND `content_sha256` differs from the workflow's pre-trigger baseline in the submitted ledger entry — a new build identity, not a replayed manifest; missing baseline fails closed), and only then stamps provenance. Diff parsing, findings parsing, and the collision-exemption rules come from the shared `lib/publish-content.js` (the unknown-recovery classifier's own judgment — one definition, never two). Binary files, mode-only changes, and fully-colliding added hunks fail closed as `unverifiable-content` (2026-09-16, critic findings 1/5) — they can never vacuously stamp. Content-mismatch, unreadable-result, superseded, and stamp failures exit 1 with `publish: verification-failed` and no stamp.
 - `update-watch.js` — deterministic automatic update watcher (2026-09-16, zero deps): `node update-watch.js --crew-home <path>` (missing arg → usage, exit 2; every other path exits 0). Watches the public npm registry (`npm view muse-crew version` pinned to `https://registry.npmjs.org/`) vs `crew-release.sh current` and files a `workflow: "upgrade"` task with `source: npm@<version>` when policy (`auto_update_crew`, `update_channel`) and channel gating allow; watches `git ls-remote origin HEAD` on the first `deploy_type=artifact` project vs `$CREW_HOME/.update-watch.json` and files a `workflow: "chore"` task carrying the mechanical dashboard-upgrade journey. Reads the `.crew-version` compatibility anchor at the new ref via `git fetch` + `git show <sha>:.crew-version` (never the working tree) and orders dashboard-led: a declared newer crew files the crew upgrade task FIRST and the dashboard task notes it follows the crew upgrade (declaration bypasses `update_channel`, not the `auto_update_crew=false` opt-out); a declared older crew skips the dashboard leg entirely as a human decision; a missing/invalid/unfetchable anchor fails open to the dashboard leg as today. Idempotency via the same state file (records at file time); check failures log to `$CREW_HOME/update-watch.log` and are never thrown. Safety: only files tasks — never deploys, never touches the artifact/config/scheduler. Run by the daily `crew-update-watch` cron through the `current` symlink (latest release); deliberately NOT in the lib-pinning `PIN_BASENAMES`.
 - `gitignore.js` — deterministic .gitignore management for crew-owned paths (2026-09-17): the crew touches exactly one user-owned file outside `.orchestration/` — the repo's `.gitignore`. `ensureGitignoreEntries(repoPath, entries)` creates the file when missing, appends missing entries (exact line match, no duplicates), preserves existing content byte-for-byte, and is idempotent. `describeGitignoreChange(repoPath, entries)` renders the exact diff for the setup consent conversation. Crew-owned entries: `.worktrees/`, `.orchestration/user/`. CLI: `--repo <path> [--dry-run]`.
 - `repo-orchestration.js` — repository-local `.orchestration/` scaffold (2026-09-17): `scaffoldRepoOrchestration(repoPath, crewRepoPath)` creates `$REPO/.orchestration/{workflows,identities,phases,user}/`, seeds workflows/identities/phases from the crew repo's platform defaults with no-clobber semantics (existing project customizations never overwritten), and writes a README in `user/` explaining it's for local config. Idempotent. CLI: `--repo <path> --crew-repo <path>`.