dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-work/references/input-triage.md

@@ -0,0 +1,50 @@
+# Input Triage
+
+Read this before classifying the invocation, discovering a plan, or deciding whether normal implementation may begin. It covers resolving the source, parsing the mode token and its optional carriers, recognizing a recovery request, classifying plan readiness, discovering the latest plan, and deciding how a bare prompt enters. Return to the main `SKILL.md` flow: the resolved source, the execution class, which side runs the shipping steps (this skill standalone, or the caller), and any typed engine or recovery binding. Do not perform implementation writes here.
+
+## Input Document
+
+The **input document** for this run is the input this skill was invoked with — present in the current prompt or conversation, whether the user provided it directly or a calling skill passed it (e.g. `lfg` in `mode:pipeline`, which passes a plan path). It may be a plan or spec path, a `mode:` token followed by a path, or a bare work prompt. This reference calls it `<input_document>`; if nothing was provided, treat `<input_document>` as blank.
+
+Invocation origin is not observable or relevant: apply the same source-resolution rules whether the user invoked `ce-work` explicitly or the host selected it automatically.
+
+## Artifact Root
+
+This skill discovers plans under `<root>/plans/`. Resolve `<root>` when you first compose a `<root>/` path (per the block below), never before you need it. A write to `<root>/...` and a read of `<root>/solutions/` both count as composing a `<root>/` path, so either one triggers resolution; only a run that touches no `<root>/` path at all -- a scratch-only or no-repo flow -- skips it; pass the resolved path to any subagent, not the config.
+
+<!-- ce-docs-root:start -->
+**Resolve the CE artifact root `<root>` before composing any artifact path.**
+
+- **Read** `docs_root` from `<repo-root>/.compound-engineering/config.yaml` only (`<repo-root>` = `git rev-parse --show-toplevel`). Do not read it from `config.local.yaml`. Unset -> `<root>` is `docs`, exactly as before.
+- **Validate** a set value: a repo-relative directory whose real, symlink-resolved path stays inside the repo and is neither the repo root nor under `.git/`. Otherwise stop with an error naming `docs_root` and the value -- never fall back to `docs`.
+- **Use** `<root>` as the sole artifact location: create it if absent, compose each path as `<root>/<subdir>` with this skill's own subdirectory, and never also read `docs`.
+<!-- ce-docs-root:end -->
+
+## Recovery and Control Grammar
+
+**Recovery activation comes first.** Before normal plan, path, blank-input, or bare-prompt classification, interpret whether the user is semantically asking to resume, inspect status, reap, or clean up an existing external implementation run and has supplied its run id. This is intent recognition, not verb-only matching. Validate the id with the controller's safe-id contract: `^[A-Za-z0-9._-]{1,128}$` and at least one non-period character. When this direct recovery intent is present, read `references/cross-model-execution.md`, use that run id as authoritative for the requested controller operation, and return the observed state or blocker. Recovery must not dispatch a new worker, select a new route, fall through to latest-plan discovery, or run the shipping steps of either mode. When every unit is already cleaned, **completed recovery is read-only reconciliation**: Do not rerun test, build, format, install, generation, or `verify-run`; report the stored unit and plan-wide verification receipts. If recovery intent is clear but the run id is missing, request the id instead of guessing or classifying the text as new work.
+
+**Otherwise, parse a leading mode token.** If `<input_document>` begins with `mode:return-to-caller` (or the legacy aliases `mode:caller-owned-tail` / `caller:lfg`), strip that token before anything else and enter **Return-to-Caller Mode**: implement and locally verify only, then return the structured summary defined in `references/return-to-caller.md` instead of running the standalone shipping tail (final simplify, review, PR, CI). Before the plan path, accept up to two optional carriers (extra tokens that carry a binding or a run id) in this fixed order: first one compact JSON object prefixed exactly `implementation_engine:`, then one run id prefixed exactly `implementation_run:`. Fully validate and normalize both before any workspace action. The engine object must contain exactly four fields: `mode` is `prefer` or `require`; `target` is `codex`, `claude`, `grok`, `cursor`, `composer`, `opencode`, or `antigravity`; `model` is a string pin or `null`; and `source` is a non-empty caller-visible provenance string. The run carrier is accepted only for return-to-caller recovery and must satisfy the safe-id contract above. Reject malformed JSON, missing/extra fields, invalid field types or values, an unsafe run id, an out-of-order carrier, or a duplicate carrier. The entire remaining string is the plan path. A mode token or carrier with no following path is an error; report it instead of treating control data as a bare prompt. Without either optional carrier, the original `mode:return-to-caller <plan-path>` form is unchanged and standing configuration remains eligible.
+
+When `implementation_run:<safe-id>` is present, recovery wins over ordinary input classification: read `references/cross-model-execution.md`, use `resume --run-id <safe-id>` as the authoritative entrypoint, and return the normal Return-to-Caller summary after reconciliation. Preserve the supplied `implementation_engine` binding when present. Do not resolve a different route, redispatch, reimplement, rerun completed verification, or start a second run of the shipping steps the caller owns.
+
+When a valid `implementation_engine:` binding is present without recovery, **pre-controller discovery is read-only**. Do not run baseline, test, build, format, install, or generation commands in the canonical checkout before resolving the binding and initializing the external controller: those commands can create ignored or untracked artifacts before the controller records its clean starting point. Limit triage to reads such as metadata, source, configuration, branch, status, and command-availability probes. If a non-read probe is genuinely required to decide whether the route can start, run it only with artifact suppression and prove the canonical Git snapshot is byte-for-byte unchanged before continuing; otherwise stop with a route blocker.
+
+**Resolve a session-carried plan before blank or bare-prompt classification.** When the current request is continuation language such as "proceed" and the conversation identifies exactly one current plan for this work — a plan/spec path or an in-conversation brief from `ce-plan` — that was authored, selected, or accepted, treat it as `<input_document>`. A brief enters as a bare prompt with `source_kind: prompt`. If multiple session plans are plausible, ask which one; do not choose by recency. Do not replace a concrete new work request with an unrelated earlier plan. This rule depends only on visible conversation state, never on whether invocation was explicit or automatic.
+
+## Source Classification
+
+Determine how to proceed based on what was provided in `<input_document>` after any mode token is stripped.
+
+**Plan document** (input is a file path to an existing plan or specification): resolve the canonical document before classification. Follow an explicit supersession notice to its canonical path only when the linked document's contents establish that it represents the same requested work; otherwise stop for clarification. Then inspect its contents, using a section map for long documents. Metadata describes the artifact; an old readiness label is not execution authority.
+
+- A non-code deliverable, including `execution: knowledge-work`, follows `references/non-code-execution.md` instead of the code workflow.
+- A Product Contract without enough implementation direction needs `ce-plan` enrichment. An approach-only or answer-seeking document is not an implementation plan.
+- Proceed only when the intended code work, scope, and verification are sufficiently defined and no launch-blocking question remains. For unified plans, inspect the Product Contract, Planning Contract, Implementation Units, Verification Contract, and Definition of Done. Judge legacy plans and saved briefs by the same sufficiency condition without requiring unified headings.
+- Verify material existing prerequisites for the active work against the repository before implementation. If the plan depends on something that is unavailable or contradicts current code, resolve it within the agreed scope or return the blocker; do not invent a substitute that changes the contract. Explicitly planned additions need not exist yet. Deferred implementation details remain the executor's work.
+
+Then continue using the reader strategy in `references/work-intake.md`. Do not require a metadata repair before working from an otherwise sufficient plan.
+
+**Blank invocation latest-plan discovery:** when `<input_document>` is blank, glob `<root>/plans/*.md` and `<root>/plans/*.html` and inspect the newest candidate's contents using the same canonical resolution and classification. If same-basename format siblings have no clear canonical path, ask which to use. Do not silently skip a newer incomplete or non-code artifact to execute an older plan; ask for an explicit path or `ce-plan` enrichment.
+
+**Bare prompt** (input is a description of work, not a file path): read `references/work-intake.md` and follow its scan-and-route steps. Trivial work (1-2 files, no behavioral change) must skip only the task list, then pass the mandatory engine-before-write gate in `SKILL.md` (resolve the engine before the first write) before implementing directly, with no unit execution loop. Do not treat an unclear prompt as permission to hand work to an external worker. If discovery cannot state a concrete goal, bounded scope, and authoritative verification, clarify or route to `ce-plan` before sending any work to a cross-model worker.

package/skills/ce-work/references/non-code-execution.md

@@ -0,0 +1,23 @@
+# Non-Code Execution (Knowledge-Work Carve-Out)
+
+Loaded from Phase 0 Input Triage when the plan carries `execution: knowledge-work`. The plan is a **production plan** for a non-code deliverable (a synthesized document, a study artifact, a research write-up) — typically produced by `ce-plan`'s approach-level flow. Execute it to produce the deliverable. This is an uncommon case: the normal code lifecycle does not apply and is not started here.
+
+## What this skips
+
+Do **not** run any of the code-shipping steps; they do not fit knowledge work:
+
+- No branch/worktree setup (Phase 1 Step 2).
+- No task-list-from-implementation-units, no execution-strategy/subagent dispatch keyed on `Files:`.
+- No Test Discovery, no test-scenario completeness, no system-wide test check.
+- No incremental code commits, and none of `references/shipping-workflow.md` (no PR, no CI).
+
+## Execute the production plan
+
+1. **Read the plan fully.** It is a decision artifact describing *how* the deliverable gets made: which sources to read, how to mine each, how they combine, the shape of the deliverable, and any forks the user already confirmed. Honor those decisions.
+2. **Read the sources the plan names** — the actual inputs (PDFs, transcripts, docs, links). Treat user-named resources as authoritative; read them rather than working from memory. If a named source is missing, say so plainly rather than substituting.
+3. **Synthesize and produce the deliverable** following the plan's intended shape and the confirmed forks. This is the work the approach-plan deliberately deferred.
+4. **Save and report.** Write the deliverable to a durable, repo-tracked location — default to a sensible `docs/` subpath (or a path the user named at the checkpoint) — and report its absolute path so the user can find it. Whether to git-commit vs. leave it written is the user's call; offer, don't force.
+
+## Stay scoped to non-code deliverables
+
+The carve-out is for knowledge-work output. If producing the deliverable legitimately requires emitting code (a script, a config file, a data-transform), send that specific sub-step back through the normal code path so its safeguards (Test Discovery, review, commit hygiene) still apply. Do not silently produce code under the carve-out. The deliverable itself stays non-code.

package/skills/ce-work/references/return-to-caller.md

@@ -0,0 +1,33 @@
+# Return to Caller
+
+Read this when input triage enters Return-to-Caller Mode, and read it again immediately before returning. Input triage owns and validates the invocation grammar (`references/input-triage.md` parses the mode token and carriers). This file defines every field of the summary you return, the evidence rule for `status: complete`, how a repeated run recovers without reimplementing, and the standalone work you must not do here: simplify, review, PR, CI, and babysitting.
+
+In this mode `ce-work` performs implementation and local verification only — including mid-implementation Phase 2 "Simplify as You Go" — then returns a structured summary instead of running the standalone shipping tail (final simplify, review, PR, CI). It still makes the canonical commit for each completed unit, as Phase 2 directs; the caller commits only what remains. The summary is the last thing this mode writes. It ends this skill, not the turn. The caller runs in this same session, and its next step follows the summary.
+
+Return:
+
+- `status`: `complete`, `blocked`, or `failed`
+- `plan_path`
+- `changed_files`
+- `u_ids_attempted`
+- `u_ids_completed`
+- `verification_results`
+- `verification_evidence`: one entry per attempted behavior-bearing unit, plus any non-behavioral unit where tests were intentionally skipped. Each entry states the unit/task, `behavior_changed`, `existing_tests_inspected`, `tests_added_or_changed`, tests used unchanged, red failure or characterization observed when applicable, verification commands/results, and any exception reason. For units executed by subagents, this entry is assembled from each worker's returned evidence, not reconstructed from the diff — the red-before-implementation observation exists only in the worker's report.
+- `implementation_engine_binding`: the resolved one-run `mode`, `target`, `model`, and `source`, or `null` when native execution was selected without a binding
+- `requested_route` and `actual_route`: target plus harness/intermediary identity, kept separate when fallback or same-family substitution occurred
+- `requested_model` and `actual_model`: the model that was requested and the model identity the route's receipt reports as served (`unverified` when the route supplies no trustworthy receipt)
+- `requested_effort`: the reasoning effort requested for the external worker, or `null` when none was requested or execution was native
+- `fallback_reason`: `null` when none, otherwise the observed route-unavailable or substitution reason
+- `run_id`: durable external run identifier, or `null` for native execution
+- `source_kind` and `source_digest`: what the controller recorded as the implementation source (`plan` plus its digest in Return-to-Caller Mode; standalone bare-prompt runs use `prompt`)
+- `unit_receipts`: route, model, detached-process, integration, verification, canonical-commit, and cleanup state for each attempted unit
+- `plan_checkpoint`: the disclosed checkpoint commit when the selected plan was the only canonical dirt, otherwise `null`
+- `blockers`
+- `recovery_path`: the run/workspace location the controller preserved and checked, when recovery remains; otherwise `null`
+- `settled_decision_conflicts`: conflicts with `session-settled:`-labeled KTDs or Key Decisions encountered during implementation — each entry names the labeled entry, the evidence, and how it was routed (proceeded-and-flagged vs blocker); empty when none
+- `behavior_change`: whether behavior-bearing code changed
+- `standalone_shipping_skipped: true`
+
+Return `status: complete` only when behavior-bearing work has verification evidence or a deliberate exception. Before returning it, re-open the plan and re-check its active units, Verification Contract, and Definition of Done against the diff, because context may have been compacted to a summary that dropped detail. Remove code left over from approaches that did not pan out. If a previous return-to-caller run implemented code but omitted evidence, a later same-plan return-to-caller run should use the idempotency check to inspect the existing work, complete the evidence, and return without reimplementing.
+
+Engine selection (`references/execution-engines.md`) still applies in this mode, but only for implementation. Whichever engine runs must not open a PR, run the standalone shipping steps, or skip the checks the caller controls.

package/skills/ce-work/references/review-findings-followup.md

@@ -0,0 +1,82 @@
+# Apply Code Review Findings (after `ce-code-review`)
+
+Load this reference when `ce-code-review` has finished and **ce-work** (or another caller) should apply fixes before the Residual Work Gate.
+
+`ce-code-review` is invoked here with `mode:agent`, so it is **review-only** in this context — it reports findings and writes artifacts and does not mutate the checkout, commit, push, or file tickets. **The caller decides which fixes to apply and how.** Standalone review is also report-only unless local apply was explicitly authorized.
+
+## Consume the completed review (do not re-run it)
+
+This reference loads **after** review has run. In the ce-work shipping flow, step 3a already invoked `ce-code-review`; this apply step **consumes that output**. Do not start a second review, which would waste reviewer dispatches and risk overwriting the artifact the Residual Work Gate reconciles.
+
+Reuse the review output already in hand:
+
+- Parsed JSON (`status`, `actionable_findings`, `findings`, `artifact_path`, `run_id`) **or** the markdown Actionable Findings summary captured by the caller
+- Run artifact dir: `<artifact-path>/` (`review.json`, per-reviewer JSON for `why_it_matters`)
+
+If `status` is `failed`, stop shipping and report `reason`. If `degraded`, note partial reviewer coverage before applying anything.
+
+### Fallback — invoke `ce-code-review` only for cold callers
+
+Only when the caller reached this file **without** already running review (no review output in hand): invoke `ce-code-review` once, then proceed to apply. Do not invoke when the caller already ran review (e.g., ce-work shipping step 3a).
+
+Invoke the skill explicitly. Do not treat a casual "review my changes" prompt as a substitute unless the harness routed it to `ce-code-review`.
+
+```
+ce-code-review mode:agent plan:<plan-path> base:<merge-base-or-ref>
+```
+
+- `mode:agent` — JSON output (`review.json` + primary JSON response) for programmatic parsing; same review pipeline as default.
+- `plan:` — when Phase 1 used a plan file (requirements completeness).
+- `base:` — when the diff base is already resolved on the current checkout; omit when reviewing a PR number/URL or standalone current branch.
+- Do **not** pass deprecated `mode:autofix`.
+
+For human-facing shipping, invoke `ce-code-review` without `mode:agent` if markdown tables are preferred. It still reports only unless the invocation explicitly authorizes local apply. Capture the Actionable Findings and artifact dir before caller-owned apply.
+
+## Inputs for apply
+
+- `actionable_findings` from JSON, or the Actionable Findings section from markdown
+- Full finding detail when needed: `review.json` / artifact `findings`, or `{reviewer}.json` for `why_it_matters` and `evidence`
+- Stable finding `#`: reuse it in commits, in the record of unapplied findings (PR section or tracker ticket), and in subagent prompts
+
+## Check findings before applying fixes
+
+The calling agent decides which findings are valid and which fixes it has permission to apply. Verify each finding against the evidence and the requested outcome. Reject incorrect claims, problems with no supporting evidence, and preferences whose benefit does not justify the change. Record why they were rejected; do not carry them forward as unfinished work.
+
+Apply justified fixes within the agreed scope when they can be reversed. Use project evidence and conventions to choose technical fixes; a design choice does not automatically need a user decision. Neither `confidence`, `autofix_class`, nor a concrete `suggested_fix` proves benefit or grants permission. If a significant problem has no suggested fix, investigate it before deciding to defer it.
+
+Defer a fix when essential evidence is unavailable, the user must choose a product preference, the work would expand the agreed scope, or the calling agent lacks permission. Passing tests do not prove an unverified safety property or authorize changing an agreed requirement. At the Residual Work Gate, explain what decision is needed and what depends on it.
+
+Read the relevant source or assign a subagent to investigate a specific question. Use `ce-pov` only when an important, specific choice needs an independent assessment beyond ordinary inspection. Reviewer disagreement alone is not enough. Give it the subject, known constraints, and locations of supporting evidence. Use its answer or explanation of missing context to inform your decision. Neither gives permission to edit or automatically start a panel of models.
+
+## Execution — orchestrator reviews and groups findings, then applies or delegates
+
+The lead agent decides which findings to act on, groups the work, reviews the diffs, runs tests, and checks what remains at the Residual Work Gate. It may investigate a small question directly; delegate broader research rather than loading every cited file. Subagents confirm that the evidence still matches the code before applying fixes within the agreed scope. They return any unresolved decisions with supporting evidence.
+
+
+### Where each fix runs
+
+Dispatch file-grouped subagent batches when fixes need code you have not read, or when fixes on disjoint files form a real parallel wave. Apply every other fix in this context: one whose code is already in your context from this session's work, or a small region you can read without materially growing this context. The lead agent stays active through tests, commits, and the handoff, so loading many cited files here is the cost delegation avoids.
+
+**Batching (primary rule: group by file):**
+
+1. Sort applicable findings by severity (P0 first).
+2. **Group by `file`.** All eligible findings on the same file → **one subagent** (it loads the file once and works through its `#` list in severity order).
+3. **Parallel waves:** batches with **disjoint file sets** may run in parallel (same worktree / shared-directory rules as `ce-work`'s execution strategy in `references/execution-strategy.md`).
+4. **Same file, many findings:** keep one subagent per file. If the prompt would exceed a comfortable size (~8 findings), split into **serial** subagent passes on that file (first batch highest severity, then next batch after merge or after the prior agent returns).
+5. **Cross-file coupling:** do not merge unrelated files into one subagent just to reduce agent count; file grouping is the default. Only co-batch multiple files when findings explicitly reference the same small related change (rare); when in doubt, separate by file.
+
+**Subagent prompt (per batch):** the assigned findings only (`#`, severity, file, line, title, `suggested_fix`, `requires_verification`; add `why_it_matters` from `{reviewer}.json` in the run artifact when useful), plus:
+- Work through assigned `#` in severity order; at each `file:line`, skip with a one-line reason if evidence no longer matches
+- Follow the review and permission rules above; choose technical fixes from project evidence and return decisions that still need the user
+- Do not re-run `ce-code-review`
+- Shared-directory fallback: do not stage or commit; return which `#` were applied or skipped and which files changed
+
+**After inline fixes and after each wave:** orchestrator reviews diffs (scope = assigned `#` only), runs tests (`requires_verification: true` on any applied finding → at least targeted tests; multi-file → broader suite), commits (`fix(review): apply findings #…`) unless worktree-isolated subagents merge per Phase 1. Repeat until all batches complete.
+
+### Summary (required)
+
+Report which `#` you applied inline and which batches you dispatched, `#` applied vs skipped, artifact path, verification results, and justified work still unresolved. Save the reasons for rejected claims with the review evidence. A skipped low-value suggestion is not a deferred concern to repeat in the handoff.
+
+## Handoff to Residual Work Gate
+
+Any justified finding still unresolved after this pass is **residual work**. Proceed to the Residual Work Gate with an updated count. Do not re-invoke `ce-code-review` solely to re-apply the same findings unless the diff changed materially after fixes.

package/skills/ce-work/references/shipping-workflow.md

@@ -0,0 +1,89 @@
+# Shipping Workflow
+
+This file contains the shipping workflow (Phase 3-4). It is loaded when all Phase 2 tasks are complete and execution transitions to quality check.
+
+## Phase 3: Quality Check
+
+1. **Run Core Quality Checks**
+
+   Run the project's full test suite and its configured lint command on the finished change before simplification and review.
+
+2. **Simplify** (conditional; separate from code review)
+
+   Before code review, apply the project’s simplification threshold when one is specified. Otherwise invoke **`ce-simplify-code`** with `mode:pipeline` at **>=30 substantive changed code lines**. Count human-authored code, not total diff lines. Skip when the diff is purely mechanical (formatting, dependency bumps, lint-only fixes, generated artifacts) or when substantive code stays under the threshold even though the total diff is larger.
+
+   This step refines reuse, quality, and efficiency on the **current diff** so any later review sees cleaner code. It is not a substitute for code review.
+
+   Pass `plan:<path>` or a scope hint when the plan or user narrowed what changed, and `proof-test:<path>` for each test the evidence record names as proving the work. If the skill is unavailable on the harness, skip or do a brief manual pass for obvious duplicate/dead code — code review (step 3) still runs regardless.
+
+3. **Code Review**
+
+   Review the diff with **`ce-code-review`**, the plugin's portable review skill, as the single path. It sizes itself. Do not classify lite versus full; pass `depth:full` only when the plan, the task, or the user explicitly asked for a deep review. There is no harness-specific review detection. It behaves identically on every harness. A host catalog entry named `review` is not this step.
+
+   **Completion gate (standalone shipping).** Shipping is **not done** until exactly one of: (1) a **completed review receipt** from an actual `ce-code-review` invocation — `mode:agent` JSON with **`status: complete`** plus `artifact_path` or `run_id`, or default-mode markdown containing Actionable Findings, Coverage, and Verdict — or (2) an **explicit skip phrase** in the shipping summary: `Code review: skipped (mechanical diff)`, `Code review: skipped (ce-code-review unavailable)`, or (interactive only) `Code review: harness-native fallback`, each with a one-line reason. Silent omit is invalid. Do **not** accept `status: failed`, `degraded`, or `skipped` as a completed receipt even when `artifact_path`/`run_id` is present; treat those as review unavailable and follow the unavailable path below. **Never substitute** mental self-review, "external / prior findings already applied," or ad-hoc skimming. A host review command alone is **not** a substitute when `ce-code-review` can load; it only counts after the unavailable path below, via the `harness-native fallback` phrase.
+
+   **Skip dedicated review only for a purely mechanical diff**: formatting, dependency-version bumps, lint-only fixes, generated artifacts (the same class step 2 skips for simplify), including multi-file mechanical-only diffs (e.g. package + lockfile, formatter across files). **Not mechanical:** behavior-bearing edits (single- or multi-file), control-flow / error-class / tests-for-behavior changes, or applying external or prior review findings. Note the exact skip phrase above. Everything else gets reviewed.
+
+   **Review is not fix — two steps:**
+
+   **3a. Review (read-only).** Invoke `ce-code-review` through the host's normal skill-invocation mechanism with `mode:agent` (add `plan:<path>` when known; `base:<ref>` when the diff base is resolved). Skill invocation means loading the cataloged skill definition and following it through that mechanism; `ce-code-review` does not require a separate executable, runner, or binary. Pass **`depth:full`** when the plan, the task, or the user explicitly asked for a full / deep / thorough review; that is the one escalation signal `ce-code-review` cannot infer from the diff alone. Do not pass `mode:autofix`. Parse the JSON and retain the receipt only when `status` is `complete` (plus `artifact_path` / `run_id`).
+
+   **3b. Apply fixes (the caller applies them, not `ce-code-review`).** Load `references/review-findings-followup.md`: check findings against the evidence and agreed scope, then apply justified fixes inline or in subagent batches grouped by file, as that reference decides. The orchestrator merges, tests, and commits. Then proceed to the Residual Work Gate.
+
+   **If the top-level `ce-code-review` attempt cannot produce a completed receipt:** Preserve the review requirement by entering this branch only when the cataloged skill definition fails to load, or an attempted top-level invocation has terminated without a usable completed receipt and no recovery remains inside `ce-code-review`. Evidence comes from the definition load or the top-level terminal outcome; intermediate internal events never establish caller-owned unavailability. A missing dedicated runner, executable, or binary is not evidence when the definition loads, so proceed through 3a and let `ce-code-review` own its recovery. In an **interactive** session, run the harness-native review if the session catalog lists one (use that entry's listed path; it is not a Compound Engineering skill), fix inline, and note `Code review: harness-native fallback` with a one-line reason (that phrase is what satisfies the completion gate; a silent mental review does not). In a **non-interactive** session (autonomous pipeline, or no native review available), skip the dedicated step, note `Code review: skipped (ce-code-review unavailable)`, and add an explicit manual diff scan to Final Validation. Never silently ship a non-mechanical change with no review of any kind.
+
+4. **Residual Work Gate** (REQUIRED when `ce-code-review` ran and left justified unresolved findings)
+
+   Compare the review's Actionable Findings with the fixes applied and the requested outcome. Close rejected claims; they are not unfinished work. Continue authorized fixes needed for completion without asking again for permission.
+
+   If an unresolved problem prevents the requested outcome or shows that an agreed decision cannot work, do not accept it as a leftover risk. Resolve it within existing permission, or return `status: blocked` with the missing evidence or user decision, the consequence, and a recommendation. Autonomous runs return the blocker rather than assume consent. Group related decisions that need the user.
+
+   Leave an action outside the required outcome unapplied when evidence or permission is missing. Continue independent work that is already authorized. Remaining concerns that do not prevent completion do not need a menu asking what to do next. Before Final Validation, record each justified concern, why it is deferred, and which review raised it. Use the authorized PR's `## Unapplied review findings` section, or follow `references/tracker-defer.md` when authorized to record it in the issue tracker. If neither destination is authorized or available, return the concerns in full and state they are recorded nowhere else. Recording a concern does not give permission to act on it.
+
+   Skip the gate when there are no justified remaining concerns or dedicated review was skipped. A reported count alone does not decide whether to stop.
+
+5. **Final Validation**
+
+   Before shipping, re-open the plan and re-check its active units, requirements, Verification Contract, and Definition of Done against the diff, because context may have been compacted to a summary that dropped detail. The change is ready when:
+   - every task is complete, and every `Deferred to Implementation` question was resolved;
+   - Testing addressed: tests and lint pass, and new or changed behavior has test coverage or a recorded reason it needs none;
+   - each plan requirement (`Requirements`, or legacy `Requirements Trace`) is satisfied by the work;
+   - code from approaches that did not pan out has been removed from the diff;
+   - UI work built from a Figma design matches it;
+   - when the review step recorded `Code review: skipped (ce-code-review unavailable)`, a manual scan of the diff found nothing that blocks shipping.
+
+## Phase 4: Ship It
+
+1. **Prepare Validation Context**
+
+   Do not try to launch a dedicated CE evidence-capture workflow. Modern harnesses provide their own browser, screenshot, terminal recording, and artifact capture tools; use those directly only when the user asks or when the artifact already exists.
+
+   Note whether the completed work has observable behavior (UI rendering, CLI output, API/library behavior with a runnable example, generated artifacts, or workflow output), and summarize any manual validation performed. If the user supplied evidence (URL, markdown embed, local artifact path), pass it to `ce-commit-push-pr` as PR-description context.
+
+2. **Commit and Create Pull Request**
+
+   **Ship-handoff gate.** Before loading `ce-commit-push-pr` or `ce-commit`, confirm the Phase 3 code-review completion gate is satisfied (completed review receipt **or** exact skip / harness-native-fallback phrase). If neither is present, stop and run step 3 (or write the legitimate skip); do not push "and review later." Pass the receipt summary (`status: complete` + `artifact_path`/`run_id`) or the skip phrase into the shipping summary and PR-description context, alongside the unapplied review findings.
+
+   **Do not publish what the user did not offer.** `ce-commit-push-pr` pushes the whole branch and its PR spans every commit on it. Check the pre-work scope Phase 1 Step 2 recorded: if the branch carries pre-existing commits that are not on the remote (or Step 2 could not tell), and those commits are not already in an open PR for this branch, load `ce-commit` instead: commit the work locally under any `exclude:` paths, say in one line what stayed local and why, and say that you will push and open the PR on request. Do not ask first; a local commit is reversible and one word gets the rest. Otherwise:
+
+   **Project-defined shipping process wins.** If the project's active instructions already in your context name a process that handles the shipping handoff (committing, pushing, and opening the PR), such as a named skill or command (e.g. a `/create-pr` skill), a stacking tool, or documented steps, use that process instead of the default below. Conventions the default already honors (commit-message format, PR title style, PR template) are not a process and do not trigger this. Presence of a skill directory alone is not a directive; the instruction has to say so. Hand the process the same context this step would hand `ce-commit-push-pr` (plan summary, testing notes, evidence, review receipt, unapplied review findings). If it cannot take a piece, state that in the shipping summary. When this run recorded `Code review: skipped (mechanical diff)`, also hand it the condition that a mechanical diff needs no post-PR watch; the process decides how it honors that. The `exclude:` paths are a constraint, not context: if the process cannot keep them out of the commit, do not run it; use the default below, which can. The ship-handoff gate and the publish rule above hold whichever process runs. Precedence: the user's stated preference for this run > the project-defined process > the default. Absent a project-defined process:
+
+   Load the `ce-commit-push-pr` skill with `branding:on` to handle committing, pushing, and PR creation. When this run recorded `Code review: skipped (mechanical diff)`, also pass `babysit:off` (a mechanical diff needs no post-PR watch) and name that in the PR-description context. Pass `exclude:<paths>` naming every file from Phase 1 Step 2's pre-work scope that this run did not commit (untouched WIP and any leave-uncommitted files alike), so the skill's dirty-file scan leaves the user's work out of the shipping commit. This explicit signal records that the Compound Engineering workflow produced the work; the skill handles convention detection, branch safety, logical commit splitting, adaptive PR descriptions, and PR attribution. If the session already stated how the PRs are arranged (a PR stack, and any parent PR or branch to stack on), pass it on that invocation.
+
+   When providing context for the PR description, include:
+   - The plan's summary and key decisions
+   - Testing notes (tests added/modified, manual testing performed)
+   - Evidence context from step 1, so `ce-commit-push-pr` can decide whether to ask about capturing evidence
+   - Figma design link (if applicable)
+   - Code-review receipt (`status` + `artifact_path`/`run_id`) or the exact skip phrase from the completion gate
+   - Any findings accepted in the Phase 3 Residual Work Gate, rendered verbatim as a dedicated `## Unapplied review findings` section: one checkbox bullet per finding (`- [ ] <severity> — <file:line> — <title>`, `suggested_fix` beneath when present) so the reviewer ticks what they close, plus the review run context
+
+   If the Residual Work Gate filed residual findings as tracker tickets, back-fill the opened PR's URL into those tickets once it exists. This is best-effort, so that each ticket links to the PR carrying the finding.
+
+   If the user prefers to commit without creating a PR, load the `ce-commit` skill instead, and only after the same ship-handoff gate passes.
+
+3. **Notify User**
+   - Summarize what was completed
+   - Link to PR (if one was created)
+   - Note any follow-up work needed
+   - Suggest next steps if applicable

package/skills/ce-work/references/tracker-defer.md

@@ -0,0 +1,150 @@
+# Tracker Detection and Defer Execution
+
+This reference covers how residual actionable findings are filed in the project's tracker. Loaded by caller workflows (for example `ce-work` Residual Work Gate, or `lfg` residual handling), not by `ce-code-review`, which stops after the report.
+
+---
+
+## Execution Modes
+
+Tracker-defer has two execution modes. The caller selects one; the detection, fallback chain, and ticket composition are shared. A "sink" below is any place a finding can be durably filed.
+
+### Interactive mode
+
+Used by `ce-work` Residual Work Gate and similar caller flows when the user chooses to file tickets. All user-facing prompts are asked:
+
+- First Defer of the session with a generic (non-named) label confirms the effective tracker choice.
+- Execution failures prompt with Retry / Fall back to next sink / Convert to Skip.
+- Labels in the routing question name the tracker when `named_sink_available` is true, and use generic wording when a fallback is in use.
+
+### Non-interactive mode
+
+Used by autonomous callers like `lfg` that must not prompt. All blocking questions are skipped; the fallback chain is executed silently in order. Behavior:
+
+- No confirmation on the first generic-label Defer; proceed directly.
+- On execution failure, automatically fall to the next tier without prompting. Record the failure.
+- On total chain exhaustion (every tier failed or no sink available), return findings in the `no_sink` bucket so the caller can record them somewhere else (e.g., inline them in a PR description).
+- Return a structured result: `{ filed: [{ finding_id, tracker, url }], failed: [{ finding_id, tracker, reason }], no_sink: [{ finding_id, title, severity, file, line }] }`.
+
+The caller decides how to show the result to the user. The non-interactive mode treats "no sink available" as a data-producing outcome, not a prompt trigger.
+
+---
+
+## Detection
+
+The agent determines the project's tracker from whatever documentation is obvious. Primary source: the project's active instructions and conventions already in its context — no need to open or name specific instruction files. Read a file directly only when the relevant instructions aren't already in context: a subdirectory-scoped instruction file governing the area you're working in, or when you're a fresh subagent that wasn't given the project's instructions. Supplementary signals (when primary documentation is ambiguous): `CONTRIBUTING.md`, `README.md`, PR templates under `.github/`, visible tracker URLs in the repo.
+
+A tracker can be reached through an MCP tool (e.g., a Linear MCP server), a CLI (e.g., `gh`), or a direct API. All are acceptable. The detection output is a tuple with two availability flags. One is for the named tracker specifically and drives label confidence in Interactive mode. The other is for the full fallback chain and drives whether Defer is offered at all:
+
+```
+{ tracker_name, confidence, named_sink_available, any_sink_available }
+```
+
+Where:
+- `tracker_name` — human-readable name ("Linear", "GitHub Issues", "Jira"), or `null` when detection cannot identify a specific tracker
+- `confidence` — `high` when the tracker is named explicitly in documentation (or via a linked URL to a specific project/workspace) and is unambiguously the project's canonical tracker; `low` when the signal is thin, conflicting, or implied only
+- `named_sink_available` — `true` only when the agent can actually invoke the detected tracker (MCP tool is loaded, CLI is authenticated, or API credentials are in environment); `false` when the tracker is documented but no tool reaches it, or when no tracker is found at all. Drives label confidence: inline tracker naming requires this to be `true`.
+- `any_sink_available` — `true` when any tier in the fallback chain (named tracker or GitHub Issues via `gh`) can be invoked this session. Drives whether Defer is offered in Interactive mode, and drives the `no_sink` bucket in Non-interactive mode.
+
+Detection is reasoning-based. Do not maintain an enumerated checklist of files to read. Read the obvious sources and form a confident conclusion; when the obvious sources don't resolve, the label falls back to generic wording and the agent confirms with the user before executing (Interactive mode only).
+
+---
+
+## Probe timing and caching
+
+Availability probes run **at most once per session** and **only when Defer execution is imminent**. Never speculatively at review start, never per-Defer, never per-walk-through-finding. The cached tuple is reused for every Defer action in the same run.
+
+Typical probe sequence:
+
+1. Consult the project's instructions already in context for tracker references — don't open or name specific instruction files; read one directly only when the relevant instructions aren't in context (subdirectory scope, or a fresh subagent). If nothing found, set `tracker_name = null`, `confidence = low`.
+2. **Probe the named tracker when one was found.** For GitHub Issues, run `gh auth status` and `gh repo view --json hasIssuesEnabled`. For Linear or other connector/MCP-backed trackers, first discover available tools via the platform's tool-discovery primitive (e.g., `ToolSearch` in Claude Code) rather than assuming absence from an unloaded tool, then verify the discovered tool is responsive. For API-backed trackers, verify credentials wherever the platform exposes them (environment, connector auth, or a documented secrets location), not only shell env vars. Set `named_sink_available` from the probe result.
+3. **Probe the GitHub Issues fallback to compute `any_sink_available`.** Even when the named tracker was found and probed, `gh` matters for the `no_sink` bucket decision so that a run with no documented tracker but working `gh` still offers Defer.
+   - If `named_sink_available = true`: `any_sink_available = true` (no further probes needed).
+   - Otherwise, probe GitHub Issues via `gh auth status` + `gh repo view --json hasIssuesEnabled` (skip if already probed in step 2). If it works, `any_sink_available = true`.
+   - Otherwise, `any_sink_available = false`.
+
+When Interactive mode's routing question is skipped entirely (R2 zero-findings case), no probes run. When the cached tuple is reused across a session, any `named_sink_available = true` from the session's first probe stays cached — do not re-probe per Defer.
+
+---
+
+## Label logic (Interactive mode)
+
+- When `confidence = high` AND `named_sink_available = true`: the routing question's option C and the walk-through's per-finding Defer option both include the tracker name verbatim. Example: `File a Linear ticket per finding`, `Defer — file a Linear ticket`.
+- When `any_sink_available = true` but either `confidence = low` or `named_sink_available = false` (a fallback tier is working instead): the labels read generically — `File an issue per finding`, `Defer — file a ticket`. Before executing the first Defer of the session, the agent confirms the effective tracker choice with the user using the platform's blocking question tool.
+- When `any_sink_available = false`: option C is omitted from the routing question, option B (Defer) is omitted from the walk-through per-finding options, and the agent tells the user why in the routing question's stem.
+
+Non-interactive mode skips label decisions entirely; it acts silently on the detected sink.
+
+---
+
+## Fallback chain
+
+When the named tracker is unavailable or no tracker is named, fall back in this order. Prefer the project's detected tracker; use `gh` only when no named tracker was found or the named one is unreachable.
+
+1. **Named tracker** (MCP tool, CLI, or API the agent can invoke directly, identified via Detection above)
+2. **GitHub Issues via `gh`**: when `gh auth status` succeeds and the current repo has issues enabled (`gh repo view --json hasIssuesEnabled` returns `true`)
+3. **No sink** — findings remain in the review report's residual-work section (Interactive mode) or are returned in the `no_sink` bucket for the caller to route (Non-interactive mode). The agent does not re-display them somewhere that does not persist, such as chat.
+
+Previously this chain included a third in-session fallback tier. That tier was removed because in-session tasks do not survive past the session and therefore do not meet the "durable filing" intent of a Defer action. When no durable tracker exists, the correct behavior is to leave findings in the report (Interactive) or return them to the caller (Non-interactive).
+
+---
+
+## Ticket composition
+
+Every Defer action creates a ticket with the following content, adapted to the tracker's capabilities:
+
+- **Title:** the merged finding's `title` (schema-capped at 10 words).
+- **Body:**
+  - Plain-English problem statement — reads the persona-produced `why_it_matters` from the contributing reviewer's artifact file at `<artifact-path>/{reviewer}.json`, using the same `file + line_bucket(line, +/-3) + normalize(title)` matching agent mode uses (see SKILL.md Stage 6 detail enrichment). Falls back to the merged finding's `title`, `severity`, `file`, and `suggested_fix` (when present) when no artifact match is available — these fields are guaranteed in the merge-tier compact return.
+  - Suggested fix (when present in the finding's `suggested_fix`).
+  - Evidence (direct quotes from the reviewer's artifact).
+  - Source: a link to the PR carrying this change when one already exists at filing time; otherwise the branch and head commit SHA, so the ticket points at the code even before a PR is opened. When the same run opens a PR after the ticket is filed, back-fill the PR link into the ticket (best-effort; never block shipping on the update).
+  - Metadata block: `Severity: <level>`, `Confidence: <score>`, `Reviewer(s): <list>`, `Finding ID: <fingerprint>`.
+- **Labels** (when the tracker supports labels): severity tag (`P0`, `P1`, `P2`, `P3`) and, when the tracker convention supports it, a category label sourced from the reviewer name.
+- **Length cap:** when the composed body would exceed a tracker's body length limit, truncate with `... (continued in ce-code-review run artifact: <artifact-path>/)` and include the finding_id in both the truncated body and the metadata block so the artifact is discoverable.
+
+The finding_id is a stable fingerprint composed as `normalize(file) + line_bucket(line, +/-3) + normalize(title)` — the same fingerprint used by the merge pipeline.
+
+---
+
+## Failure path
+
+When ticket creation fails at execution (API error, auth expiry mid-session, rate limit, malformed body rejected, 4xx/5xx response):
+
+**Interactive mode:** report the failure inline and ask the user using the platform's blocking question tool.
+
+Stem:
+> Defer failed: <tracker name> returned <error summary>. How should the agent handle this finding?
+
+Options:
+- `Retry on <tracker>` — re-attempt the same tracker once more (useful for transient errors)
+- `Fall back to next sink` — move this finding's Defer to the next tier in the fallback chain (e.g., from Linear to GitHub Issues)
+- `Convert to Skip — record the failure` — abandon this Defer, note the failure in the completion report's failure section, and continue the walk-through or bulk flow
+
+**Non-interactive mode:** do not prompt. Automatically fall through to the next tier. If every tier fails, record the finding in the `failed` bucket of the structured return and continue. If the chain exhausts with no sink ever available, the finding ends up in the `no_sink` bucket.
+
+When a high-confidence named tracker fails at execution, the cached `named_sink_available` is set to `false` for the rest of the session. Subsequent Defer actions fall straight through to the next tier without retrying a confirmed-broken sink. `any_sink_available` is only downgraded to `false` when every tier has been confirmed broken; a failed Linear call that succeeds via `gh` keeps `any_sink_available = true`.
+
+When no such tool is in the list, a real question call errors, or the platform has no blocking question tool, fall back to presenting numbered options in the host's chat and waiting for the user's reply (Interactive mode only).
+
+---
+
+## Per-tracker behavior
+
+Concrete behavior per tracker at execution time. The agent may invoke any of these through the appropriate interface (MCP, CLI, or API); the choice depends on what is available in the current environment.
+
+| Tracker | Interface | Invocation sketch | Body format | Labels |
+|---------|-----------|-------------------|-------------|--------|
+| Linear | MCP (preferred) or API | Create issue in the project/workspace identified by documentation; assign to the reporter if the MCP tool exposes user context | Markdown | Severity priority field if the MCP exposes it; otherwise include severity in body |
+| GitHub Issues | `gh issue create` | Repo defaults to the current repo. Use `--label` for severity tag when labels exist; omit `--label` if the repo has no label fixture. Fall back to a label-less issue on first failure. | Markdown | `--label P0` / `--label P1` / etc. when labels exist |
+| Jira | MCP or API | Create issue in the project identified by documentation; Jira's markdown dialect differs from GitHub's — use plain text in the body when MCP does not handle conversion | Plain text when MCP does not handle markdown | Severity priority field |
+| No sink available | — | Interactive: Defer option omitted, findings remain in the report's residual-work section. Non-interactive: findings returned in the `no_sink` bucket for caller routing. | — | — |
+
+When uncertain, prefer "drop with explicit user-facing notice" over "pass through silently and hope." A Defer that produces no durable artifact and no user message is data loss.
+
+---
+
+## Cross-platform notes
+
+The question-tool name varies by platform. In Interactive mode, use the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Fall back to numbered options in the host's chat only when no such tool is in the list, a real question call errors, or the runtime mode does not expose one. Never silently skip the question.
+
+Non-interactive mode is platform-agnostic: it never prompts, so the platform's question tool is not relevant.

package/skills/ce-work/references/work-intake.md

@@ -0,0 +1,51 @@
+# Work Intake
+
+Read this when Phase 0 classifies a bare prompt, and again at Phase 1 before reading a plan or building the task list. Phase 0 (Input Triage) classifies the input, and `SKILL.md` resolves the engine before the first write; this file supplies what those steps read.
+
+## Bare-prompt scan and routing
+
+**Scan the work area**
+
+- Identify files likely to change based on the prompt
+- Find existing test files for those areas (search for test/spec files that import, reference, or share names with the implementation files)
+- Note local patterns and conventions in the affected areas
+
+**Assess complexity and route**
+
+| Complexity | Signals | Action |
+|-----------|---------|--------|
+| **Trivial** | 1-2 files, no behavioral change (typo, config, rename) | Proceed to Phase 1 step 2 (environment setup) and implement directly under the body's Trivial rule. Apply Test Discovery if the change touches behavior-bearing code |
+| **Small / Medium** | Clear scope, under ~10 files | Build a task list from discovery. Proceed to Phase 1 step 2 |
+| **Large** | Cross-cutting, architectural decisions, 10+ files, touches auth/payments/migrations | Unless `ce-plan` already sized this prompt in this session, inform the user this would benefit from `ce-brainstorm` or `ce-plan` to settle scope and decisions, and honor their choice. When proceeding, build a task list and continue to Phase 1 step 2. When implementation reveals a decision the user would weigh, stop before the write and ask, or return the finding |
+
+## Read the plan and clarify
+
+- For unified plans, size your read. A short plan (lightweight or requirements-only, a screen or two) can be read in full. For a long implementation-ready plan, do **not** read the whole document first; it is expensive and unnecessary. Build a section map, then read only what the active unit needs: metadata, then `Goal Capsule`, `Verification Contract`, `Definition of Done`, the `Implementation Units` heading list, and only the active U-ID section plus referenced R/F/AE/KTD excerpts and any Product Contract Key Decision whose `Governs R…` links name those Rs (that reverse link is how a product decision's `session-settled:` label reaches you). Read appendices or unrelated U-IDs only when the active unit cites them. To build the map: in **markdown** scan headings (`rg -n '^#{1,3} ' <plan>` — top-level sections plus `### U<N>.` units); in **HTML** scan the `<h1>`–`<h3>` heading elements and their anchor ids. Match on the stable section names and unit IDs (`Goal Capsule`, `Verification Contract`, `### U<N>.`, …) and ignore HTML wrapper tags; do not match on a format-specific pattern.
+- For legacy plans, read the work document completely. Both formats (`.md`, `.html`) carry the same section names and IDs; HTML just wraps them in semantic elements (`<section>`, `<article>`, etc.).
+- If the plan includes sections such as `Implementation Units`, `Work Breakdown`, `Requirements` (or legacy `Requirements Trace`), `Files`, `Test Scenarios`, or `Verification`, use those as the primary source material for execution
+- Check for `Execution note` on each implementation unit — these carry the plan's natural-language execution direction for that unit (for example, start from failing proof, characterize legacy behavior, or prefer smoke/runtime verification). Note them when creating tasks, but do not reduce them to keyword matching.
+- Check for a `Deferred to Implementation` or `Implementation-Time Unknowns` section — these are questions the planner intentionally left for you to resolve during execution. Note them before starting so they inform your approach rather than surprising you mid-task
+- Check for a `Scope Boundaries` section — these are explicit non-goals. Refer back to them if implementation starts pulling you toward adjacent work
+- Review any references or links provided in the plan
+- If the user explicitly asks for TDD, test-first, characterization-first execution, or a specific verification style in this session, honor that direction even if the plan has no `Execution note`
+- If anything is unclear or ambiguous, ask clarifying questions now
+- If clarifying questions were needed above, get user approval on the resolved answers. If no clarifications were needed, proceed without a separate approval step — plan scope is the plan's authority, not something to renegotiate
+- **Do not skip this** - better to ask questions now than build the wrong thing
+
+## Create the task list
+
+- Use the platform's task-tracking capability when available (`TaskCreate`/`TaskUpdate`/`TaskList` in Claude Code, `update_plan` in Codex, `todo_write` in DeepSeek Harness, or the equivalent on other harnesses) to break the plan into actionable tasks. If none is available, continue normally without simulating a task list in chat
+- Derive tasks from the plan's implementation units, dependencies, files, test targets, and verification criteria
+- When the plan defines U-IDs for Implementation Units, name each task from a brief, outcome-led form of the unit's Goal and append the stable U-ID (e.g., "Add parser coverage (U3)"). Never use a bare U-ID or lead with the identifier; the user should understand the work before the traceability label. Aim for five words or fewer before the ID
+- When the full unit list is visible, do not repeat ordinal counts such as "unit 1 of 5" in every task. Add an ordinal only when the harness exposes the current task without the surrounding list and the count materially improves orientation
+- Carry each unit's `Execution note` into the task when present
+- For each unit, read the `Patterns to follow` field before implementing — these point to specific files or conventions to mirror
+- Use each unit's `Verification` field as the primary "done" signal for that task
+- Do not expect the plan to contain implementation code, micro-step TDD instructions, or exact shell commands
+- Include dependencies between tasks
+- Prioritize based on what needs to be done first
+- Keep tasks specific and completable
+
+## Do not re-scope the plan into human-time phases
+
+The plan's Implementation Units define the scope of execution. Do not estimate human-hours per unit, propose multi-day breakdowns, or ask the user to pick a subset of units for "this session". Agents execute at agent speed, and context-window pressure is handled by fresh workers (`references/execution-strategy.md`), not by phased sessions. If a plan-file input is genuinely too large for a single execution, say so plainly and suggest the user return to `ce-plan` to reduce scope. Do not invent session phases as a workaround. For bare-prompt input, Phase 0's Large routing already handles oversized work.

package/skills/ce-work/references/workspace-setup.md

@@ -0,0 +1,27 @@
+# Workspace Setup
+
+Read this after input triage identifies code work and before any branch move, implementation edit, worker dispatch, or commit. It covers choosing a writable checkout, clarifying the plan, placing the branch, recording what was already in progress before work began, handling a unit that must edit an already-dirty file, and setting up the task list. Return to the main `SKILL.md` flow: the canonical checkout, the branch, the pre-work paths and commits, the exclusions, and the task state.
+
+## Writable Checkout
+
+Repo-local implementation writes require a writable checkout. Before treating the current working directory as the project, confirm it is a git checkout you can edit. If this session has no writable checkout, but the user named a repository and the harness exposes a remote repo-work surface with a writable checkout, run the implementation work on that surface and treat that checkout as the canonical workspace for verification, commits, and handoff. Otherwise skip repo-local writes and report that no writable checkout is available; do not synthesize file changes from a non-repo scratch directory.
+
+## Prepare the Work
+
+1. **Read Plan and Clarify** _(skip for a bare prompt)_ — read `references/work-intake.md` for how to size the read, what to pull from the plan, and when to stop and ask. Treat the plan as a decision artifact, not an execution script: ask anything unclear before implementing rather than after. **Do not edit the plan body during execution** — progress lives in git commits and the task tracker, and legacy `- [ ]` / `- [x]` marks or a `status:` field are not state.
+
+2. **Setup Environment**
+
+   Two things must hold before the first edit: the work lands on a feature branch, and nothing the user did not offer up gets committed or published by this run. Neither is a question for the user. A branch move is a one-command undo, so do it and say so in one line.
+
+   **Branch.** Determine the default branch from `origin/HEAD`. If that is unavailable, use the host's repository-metadata capability; when the available interface is GitHub CLI, run `gh repo view --json defaultBranchRef`. Otherwise use `main` or `master` when one exists. Read the current branch with `git branch --show-current`.
+
+   If you are on the default branch, detached, or cannot tell, create a feature branch named from the plan or work description. When a remote default exists, run `git fetch origin <default>` first. Base the new branch on the fetched `origin/<default>` when `HEAD` has no commits beyond it; base it on `HEAD` when local commits must stay visible to the idempotency check and the shipping check, or when there is no remote. After the branch move, run `git branch --show-current` again and treat that result as authoritative. When branch safety remains uncertain, use a spare branch and never make incremental commits on the real default.
+
+   Otherwise continue on the invoked branch without renaming it or asking. Use a worktree only when the user asked for one this session (`ce-worktree`), and commit on the default branch only when the user explicitly authorized that in this session.
+
+   **Pre-work scope.** Before editing, record `git status --short --untracked-files=all` (the user's in-progress files) and whether `HEAD` carries commits not on the remote default (`git log origin/<default>..HEAD`; "unknown" without a remote). Nothing in that set is yours to commit or publish. It rides along on the branch move untouched: no stash, no question, no effect on naming. Enforce this without asking the user to choose:
+   - Incremental commits stage only work-owned files and are path-limited, so untouched WIP never enters a commit; the standalone handoff passes every pre-work file this run did not commit as `exclude:<paths>`, and ships locally via `ce-commit` when pre-existing unpushed commits are on the branch (`references/shipping-workflow.md`).
+   - A unit that must edit a file that was already dirty is the one case a commit cannot separate. Ask once, at the first commit that would include such a file, and cover every such file in that one question: commit those files with the user's edits included, or leave them uncommitted (an exclusion for the rest of the run, named in the final summary as unshipped). In Return-to-Caller Mode do not ask and do not edit the file — return `status: blocked` naming it, so the user's WIP stays intact and commit-or-stash-and-rerun is a clean recovery.
+
+3. **Create Task List** _(skip if triage already built one or routed as Trivial)_ — use the platform's task-tracking capability when available (`TaskCreate`/`TaskUpdate`/`TaskList` in Claude Code, `update_plan` in Codex, `todo_write` in DeepSeek Harness, or the equivalent elsewhere), and follow `references/work-intake.md` for how tasks are derived, named, and ordered. If no such capability exists, continue without simulating a task list in chat.