dotln-executor

Imported from DylanBWood/DotLn (.claude/skills/dotln-executor/SKILL.md). Install upstream with npx skills add DylanBWood/DotLn --skill dotln-executor. Copyright stays with the author.

Operator controls precede workflow: analysis: pauses for diagnosis/direction; operator override: suspends DotLn gates for authorized recovery, regardless of harness/repo state. Preserve pending work; invent no dispatch or passing check. Exit with either prefix plus off. Codex: node scripts/operator-control.mjs analysis|override|off|status needs no build or Git. Host permissions apply. Read product 07 §Operator recovery controls for the broader recovery candidate. Process Cost: At entry/handoff run node scripts/harness.mjs usage <session>. Report available total, source, scope and cutoff; unavailable counters are unknown and never block completion. Final counters stay in ignored receipts and the response. Compare equivalent outcomes including work and waiting; name tradeoffs, invent no counts. Goal Alignment: Read docs/product/07-execution-guide.md#Goal-aligned decisions. Before material choices, record mission/critical-path contribution and comparisons with all eight system traps, Naive Interventionism and NoOp. Revisit changed evidence/scope; judge outcomes at handoff. Scale detail to consequence. scope expand: adds scope and receipt; conversation only: answers without pausing work. Keep effect limits; only explicit pause/stop interrupts. Neither appends an event. When an explicit operator scope expansion changes a judged order's text, record its authorization in that order's structured decisions and run npm run plan -- amend-order WO-NNN WO-NNN-DNNN "operator authorization and bounded scope". This binds the approved bytes in the existing planning log; it neither grants scope nor discharges a refutation hold. Run the planning check and repair encountered failures within authority instead of repeatedly carrying an inherited failure into review. Plan fan-out against the root session's remaining docs/control/budgets.json subagentCap budget (default 20; null disables) before the first spawn and state that plan in the response. Count descendants in the same plan. Batch review and refutation over groups of items: one agent judges several items, never one agent per item per pass. Check harness usage <session> for observed counts and unknown remainder; Codex has no spawn hook, so keep an explicit session count and apply this rule as role text. Reuse agents before spawning more; unknown coverage is not a fresh budget. Without effective readback, keep the operator-selected model and effort with --source operator-attested; use unknown only for a value nobody supplied. Codex briefings automatically report the active thread model, effort and CLI version, independently of token-counter availability. Never replace a supplied value with unknown or invent effective readback. After an authorized product-document edit, run npm run publication:check; this grants no editing authority to a read-only role. For resume: status or resume: times, resolve cwd and Git root, run the matching read-only command, report its observation, and stop. The remaining input and implementation procedure is for next or fix. Resolve physical cwd and Git root before changing files or running Git commands. Work only in the selected worktree; one writable coding agent owns it. Run npm run resume --silent -- status --json; use its canonical selected order, phase, report paths, and legal actions. A stale Markdown projection is repaired only by the next legal transition. Adjacent Repair: During resume: next or resume: fix, prefer a bounded repair to an encountered adjacent bug; neither pre-existing origin nor omission from the original assignment is by itself a reason to defer. Choose within the effective authority and the existing scope guard. Decision Receipts: Record each material decision in the established durable decision surfaces with its observed evidence, chosen option and rationale, rejected options with reasons, and a reversal condition for a deferred choice. This support supplies documentation, not a preference for intervention or a new approval step. Follow-up Queue: After diagnosing an adjacent bug and identifying a concrete fix, add its cause, intended fix, paths, checks and priority to the worktree queue through npm run adjacent -- apply --file <request.json>; use npm run adjacent -- list for its current revision and order. Finish the current item or reach a safe boundary before starting the next. Apply operator vetoes, reprioritization, scope changes, known-issue dispositions and deferrals to another work order or planning session; a scope change requires a fresh announcement. Operator Check-In: Before starting the next queued item, reach a safe tool boundary, offer a reasonable opportunity for steering through available asynchronous input or a turn boundary, process available operator messages, and reread the queue. Record the observation as actor-attested; never invent an inbox readback. Do not cancel an in-flight command to poll or wait indefinitely for approval. A changed queue invalidates the previous check-in. Intent to Act: On entry, tell the operator in chat 'I intend to' followed by the concrete initial action and scope. Before each next queued action, announce its scope and order and record the actual announcement against the item's current revision. Proceed within existing authority after current work and a reasonable steering opportunity unless the operator vetoes or redirects; this is not a routine permission request. Status may name artifacts for other roles. Load a report only when this role's Read directives or the active order's citations select it; a path in status is metadata, not a read directive. Skills supply procedure, never authority or phase state. Preserve the operator's intent; work-order model and effort are recommendations, and attestations record actual supplied values. Never invent effective-session readback. Never guess: an unobserved value is unknown, untested or blocked; each claim names its source or what is missing. Read: @work-order Read: @citations Read source and existing tests relevant to the order before changes. Scope those reads to @subject-files; unresolved paths remain a named input requirement. State-changing resume commands require one-invocation outside-sandbox approval in Codex; inspect the exact command, package mapping, and lifecycle-script diff first. status, times, briefing, and next need no Git escalation. In Claude Code the session hook records the dispatch named by the operator's phrase (next, fix, verify, final-review) before this procedure loads, delivers that command's briefing, passes a phrase whose dispatch is already recorded with the same briefing and receipt projected read-only by npm run resume -- briefing (a resumed Codex session runs that command itself), and reports a dispatch that is not legal in the current phase without rejecting the prompt. Prompt submission always remains open: setup, runtime and state failures are advisory, never a reason to deny access to Claude or Codex. It admits the dispatch exactly as the ordinary command: a live evidence gate or another session's writer reservation refuses it before any lifecycle change, and the terminal shows a one-line receipt naming the recorded dispatch and the equipped supports. Run no dispatch the harness recorded. Never repeat a recorded transition to repair a checkpoint warning. No branch commits before final review. Never reset, restore, clean, drop a stash, or discard intake. Preserve work through the canonical checkpoint and named recovery procedure if rollback is needed. Read: @subject-files Read: package.json Run npm run work-orders -- index after dispatch. Executor completion refreshes the index automatically; other roles refresh it after recording a result. The canonical evidence command refreshes owned projections before checking. Write durable product decisions to the cited product docs and docs/evidence/WO-NNN/decisions.md, naming the operator dispatch, evidence, alternatives and reopening condition. Run npm run meta to refresh the decisions index. The ledger is for operator ideation and planning synthesis only. For an order filed before 2026-09-09, a ledger-entry duty is discharged by its decisions file and index row; the work-order index marks this substitution. Record a correction the same day: what was misread, what was meant and what changed. Decided means sourced, not frozen; an order's non-goal fences that order alone. For status or times, run the matching read-only command and report its observation; stop without a transition. For next, follow the emitted path in the delivered briefing (Codex runs npm run resume -- next itself). If closed, report other in-flight orders; only when none remain, give the exact printed worktree-start handoff. For fix, the dispatch is recorded and its briefing delivered with the phrase (Codex runs npm run resume -- fix first); read the original order and its named failure source. Preserve those obligations and apply the equipped Adjacent Repair support to encountered defects. A premature repair may reopen only while the unresolved failure source remains. Read: @failure-report Implement the complete bounded deliverable and its write-backs. Prepare its classified release with npm run release -- prepare --local; bump only changed components with their compatibility impact and retain all publication controls. Run checks that establish the work order's claims. Executor and verifier choose when npm test is useful; lifecycle transitions never require a test gate. Completion runs git diff --check inline and validates report/attestation presence; missing gate rows, output-read observations, usage and planning handoffs advise. Review current authored outputs and record evidence with source and cutoff. Reports, indexes and release text may be completed after a passing gate without invalidating code identity. One registered writer owns a worktree on any branch. Never write gate inputs or its success record during a live npm test; stop your own gate with node scripts/harness.mjs evidence --stop when necessary. Every other permission judgment delegates to the host. Read current authored outputs; generated or oversized outputs use their generation/check evidence. Codex and Copilot can use explicit begin/observe/delivered and node scripts/harness.mjs read-output <path> --offset 0 --length 8192, without claiming automatic read receipts. Copilot: inspect canonical status, run npm run resume -- briefing after an already-recorded dispatch, otherwise run the legal dispatch once; prompt-context delivery is unobserved. Completion releases its writer; explicit scripts/operator-control.mjs recovery remains available. Usage is recorded when available and unknown otherwise; it never blocks handoff. A defect met and not fixed must be recorded in docs/evidence/WO-NNN/decisions.md with a named follow-up in its structured decision JSON followup string (or a reopens object for an existing decision), and cited by the report; fix it within the boy-scout bound or board it up there, never leave it only as a report sentence. Completion flags: --harness <harness> --harness-version <version> --model <model> --effort <level> --source <source>. Supply each field; unknown is admitted. Versions, models and effort are logged, never refused. ultra and ultra code record xhigh, mode subagents and raw spelling. Never invent effective-session readback. Codex briefings report current-session model, effort and CLI version from the active thread; use that readback when available. Copilot readback reports CLI-selected values, not effective effort; retain supplied operator attestations and never derive the harness from the model. Finish all authored output, index preparation, review and usage observations before recording npm run resume -- implementation-ready <actor-flags> or npm run resume -- repair-complete <actor-flags>. These commands refresh the final index and automatically release the current Codex session's writer reservation after recording the result; Claude also releases at Stop. Read the resulting projections without another write. A repair is unfinished until repair-complete records. Report evidence, attestation, and limits; leave verification and final review to their separate dispatches. Never leave the writer reserved at handoff or ask the operator to release it.

Outside-write grants for executor: system-temp, session-scratch; system-temp is os.tmpdir(); use the DotLn scratch path printed at role dispatch (Codex: node scripts/harness.mjs scratch). Native scratch and /tmp need a separate grant when outside system-temp. Sources are in the manifest. Literal /dev/null redirects discard output; other device mutations need grants.

DotLn has five refusals (WO-135, WO-139, WO-144): it reserves one writer per worktree on any branch, including main; refuses writes to gate inputs or the success record during a live npm test; on planning/ branches refuses repository writes outside docs/ and root Markdown; refuses observable subagent admissions beyond docs/control/budgets.json subagentCap (default 20; null disables); and refuses known outside-project write destinations without a containing root granted by the active role or equipped support. Literal redirects are judged on any program; expansions such as $PWD and a program's own effects remain unobserved under host permissions; grant failures admit with one advisory and preserve the other refusals. Descendants count at their first attributable tool call; unresolved direct/child overlap is a reported minimum, and unobserved agents remain unknown. Inspect the writer with node scripts/harness.mjs writer --show; stop this session's gate with node scripts/harness.mjs evidence --stop; use operator override: for authorized recovery. Claude hooks enforce these five refusals at observed boundaries; Codex carries the duties and grants as role text without automatic enforcement. Copilot reuses the Claude registration: scripted denials hold with allow-all; missing tool-call and child identity leave subagent accounting advisory; WO-146 evidence records interactive qualification. Other tool and completion judgments are advisory and host permissions decide. The separate Codex compaction adapter restores an owned unfinished task and permits one continuation after premature stopping; it never dispatches a role or changes writer ownership.

anti-oscillation: Identify the category the operator is pointing at; stay inside it, neither widening nor shrinking it; when the boundary is genuinely unclear, ask one focused question instead of guessing in either direction; and pause to ask before any file action that goes beyond the literal correction. Example: a correction about committing opaque identifiers includes hashes; hostnames do not belong to that category. bounded-boy-scout-cleanup: Admit only host-reviewed adjacent low-risk cleanup within named paths and shared checks that keeps the diff legible; nominate the rest separately. concurrent-work-requires-worktrees: Resolve physical cwd and Git root and require exactly one registered writer per worktree on any branch, including main. correctness-over-sycophancy: Judge the current subject from consistent independent evidence and preserve disagreement as a failed or unsupported claim. fail-conservative-correction: On a typed correction, freeze destructive effects and scope expansion, preserve evidence, and require diagnosis; a false activation only tightens behavior. no-attribution: Disable automatic attribution and reject AI trailers, footers and session links at publication; preserve human coauthors and ordinary subject text. no-lint-type-disables-as-fixes: Compare source comment directives with the baseline and reject newly introduced suppressions while allowing unchanged historical directives and quoted examples. no-partial-completion: Only admit completed status when the required obligation set is discharged and no remaining work is reported. read-your-own-output: Bind each required output to a host-observed read of its current bytes before handoff; this witnesses delivery to the reader, not comprehension. verify-app-before-done: Require executed passing checks for every required application check at the current subject before the completion transition.