dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/lfg/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: lfg
+description: "Take a request all the way to done, hands-off, through the right Compound Engineering skills. A code change ends as an open pull request, pushed without stopping. Use only when the user explicitly asks for autonomous end-to-end work or invokes lfg directly. Use ce-plan, ce-work, ce-debug, or ce-commit-push-pr for work the user reviews step by step."
+argument-hint: "[feature, bug, issue reference, or plan path; optionally assign planning and/or implementation to a model or harness]"
+---
+
+**Outcome.** The request reaches the end state its shape calls for, produced by the Compound Engineering skill whose job that is, with everything unresolved recorded where the user will see it. Most requests end with that skill's result and no branch. A change to the code is the one shape with more steps of its own: it ends in an open pull request whose URL you hold, with CI decided, after being implemented, simplified, reviewed with the eligible findings applied and the rest recorded, any durable learning captured, committed, and pushed. Merging stays with the user unless they granted it for this run.
+
+**Work source.** On the routes that change the code, nothing is implemented without a work source verified this run, and only two things qualify: an implementation-ready plan, which `ce-work` implements; or a `fixed` return from `ce-debug`, where the fix is the implementation. The plan is one the session identifies, as `references/intake.md` defines. Never search the plans directory for a candidate or act on a file you discovered. Never plan from scratch over an existing plan.
+
+**Route by what the request is.** Match the request to the skill whose job it is; the host's skill list is the catalog. Read `references/intake.md` before choosing; it alone defines the routes, their precedence, what each child skill is passed, and how each return is read. In short:
+
+- A plan path, or a plan `ce-plan` wrote this session, takes the plan route.
+- A concrete report of failing or wrong behavior goes to `ce-debug`; reproducing it is that skill's job, not intake's.
+- A change that hangs on a judgment the user did not settle goes to `ce-pov` first, and only a verdict that supports the change continues; a judgment with nothing to build ends at the verdict.
+- Product shape with more than one plausible reading goes to `ce-brainstorm` when a human is present, and to `ce-plan` in pipeline mode when not.
+- A request whose result is not a code change goes to the skill that owns that result (`ce-explain`, `ce-prototype`, `ce-pov`, `ce-ideate`, and so on); that invocation is the whole run: return its result and end.
+- Any other change to the code goes to `ce-plan`.
+
+When unsure, take the route that asks more of the evidence.
+
+**Interaction.** Ask the user only through `ce-brainstorm`, and only when a human is present. Everything else proceeds without waiting: reversible work is done and shown for the user to correct afterward, and only an irreversible action outside what they granted (a merge they did not grant, a force-push, deleting data) stops instead. `lfg` runs from schedulers, loops, and nested orchestrators. The one other question is the routing disambiguation `references/stage-routing.md` defines: when the conversation assigns planning or implementation to a model or harness, read that file before routing; it alone carries the carrier strings and the sanitization.
+
+**Stop, and say why, when** any of these holds:
+
+- The work source cannot be produced: planning returned blocked, the diagnosis found no safe fix, the fix would be divergent, `ce-pov` did not support the change, or a stage assignment cannot be passed on.
+- A child return is anything but complete and evidenced.
+- A settled decision is invalidated.
+- A project-defined shipping process falls short.
+
+A stop leaves nothing pushed that was not already pushed.
+
+Resolve every skill named here against the host's available-skills list and invoke that exact entry; some hosts namespace it (`compound-engineering:ce-plan`). Read `references/task-visibility.md` before starting: it defines the stage view published through the platform's task-tracking capability, the chat narration, and the completion rule that a step is done only after it ran, a child skill's return resumes the next numbered step in the same turn, and the turn does not end before DONE or a stop.
+
+## The run (routes that change the code)
+
+1. **Produce the work source** per `references/intake.md`. On the plan route, read `references/plan-brief.md` first; it alone defines the settled-decisions brief and the artifact-root rule. Any explicit `status: blocked` return, including `settled-decision-invalidated`, stops the run. Blocked status outranks an existing artifact and is never retried. Only absence of both a blocker and a plan file `ce-plan` reported writing this run invokes `ce-plan` a second time with the same arguments, reusing the composed brief verbatim; the plan must then pass the readiness check in `references/plan-brief.md`. On the plan route the `plan_model:<alias>` carrier rides beside the request when a planning-stage directive resolved. Record the work source for every later step. LFG never launches `/goal` directly; `ce-work` implements and returns control.
+
+2. **Read `references/work-return.md` first**, then invoke the `ce-work` skill with `mode:return-to-caller <plan-path-from-step-1>`. On the defect route this step does not run: `ce-debug` already implemented and committed, and `references/debug-return.md` was its gate. Only a valid `status: complete` may advance; every other status or malformed return stops the pipeline.
+
+3. **Read `references/review-followup.md` now**; it governs steps 3 through 7. Invoke the `ce-simplify-code` skill with `mode:pipeline` on the branch diff; skip only the invocation for a docs-only or roughly sub-10-line change.
+
+4. Invoke the `ce-code-review` skill with `mode:agent plan:<plan-path-from-step-1>`; on the defect route omit `plan:`. A `settled_conflict` finding whose evidence shows the settled decision cannot work (infeasible, wrong-thing, or destructive) stops the pipeline as blocked, with the finding reported, before the shipping precondition.
+
+**Shipping precondition (every push from step 5 on).** Run `git remote` once. No remote means local-only: make every commit the steps call for, but skip every push, PR create/edit, and CI-watch action, including step 10 in full. That is terminal, not an error.
+
+5. **Apply and persist review fixes** as that file defines. Do not proceed to the residual handoff, run browser tests, or output DONE while eligible review fixes remain only in the working tree uncommitted.
+
+6. **Autonomous residual handoff**: whenever an unapplied actionable finding, a `settled_conflict` stamp from step 4, or a proceeded-and-flagged `settled_decision_conflicts` entry from step 2 exists, record it durably per that file: in the PR body, or in tickets or the DONE report when no PR will exist. Skip only when none of the three exists. Do not output DONE until the residuals are durable. Never block DONE on tracker filing failures once the report states them. Do not prompt the user.
+
+7. Invoke the `ce-compound` skill with `mode:non-interactive` when the run produced durable reasoning the code, tests, and plan do not carry; that file states the full condition. `Documentation skipped` is success; running here puts the learning in the PR at open.
+
+8. Invoke the `ce-test-browser` skill with `mode:pipeline`.
+
+9. **Read `references/shipping.md` first**; it governs steps 9 through 11. Then invoke the `ce-commit-push-pr` skill with `mode:pipeline branding:on`.
+
+10. Watch the PR to CI-decided with `ce-babysit-pr mode:pipeline <pr-url>` when an open PR exists, as `references/shipping.md` decides. Do not reimplement CI-watching here.
+
+11. Output `<promise>DONE</promise>` after the close-out in `references/shipping.md`.

package/skills/lfg/references/debug-return.md

@@ -0,0 +1,25 @@
+# Reading ce-debug's structured return (LFG defect route)
+
+On the defect route, `ce-debug mode:return-to-caller` is the work source and the implementation at once: it reproduces, root-causes, fixes with test-first discipline, verifies, and commits on a feature branch without pushing. This file defines how to read its return, which returns advance, what each later step substitutes for the plan path it would otherwise receive, and the one case that stops.
+
+## What advances
+
+Only `status: fixed` advances to step 3. `diagnosed-no-fix`, `needs-human`, and `blocked` stop the run with the return's `root_cause`, `residuals`, and blockers reported verbatim; nothing has been pushed. A malformed return, or a `fixed` return whose fix-owned files show no change on the branch, stops the run as blocked.
+
+## What `status: fixed` must carry
+
+Require `status`, `root_cause`, `changed_files`, `head_sha`, `branch`, `pre_fix_scope`, `verification_evidence`, `residuals`, `issue_of_record`, `behavior_change`, and `standalone_shipping_skipped: true`. Empty arrays are valid for `residuals`; `issue_of_record` is `null` when the input carried no ticket.
+
+`verification_evidence` follows the same shape `ce-work` returns: when `behavior_change: true` it must name the regression test used, existing tests inspected, tests added/changed or used unchanged, the red failure or characterization observed before the fix, the verification run, and any deliberate test exception. Do NOT decide the test strategy inside LFG; the evidence is `ce-debug`'s contract. A `fixed` return with `behavior_change: true` and evidence missing or too vague to tell how the fix was proven stops the run as blocked, reporting the missing fields. There is no recovery invocation on this route: `ce-debug` has no reconciliation path, and a second run would reinvestigate.
+
+## Ship only what the user offered
+
+The user asked for this fix. They did not offer whatever else the branch and the tree already carried: uncommitted files the fix does not touch, or commits beyond the base that are not already under review in an open pull request for this branch. `pre_fix_scope` in the return tells you what was there before the fix; it is the only record, because the fix commit is on top of it now. Before any step in this run pushes, a review-fix commit included, decide whether everything that push would publish is offered: the fix, what this run itself added, and prior work an open PR already holds. When it is, ship as usual and keep the dirty files out of every commit. When it is not, or you cannot tell, hold: commit the fix locally, let no step publish, record leftover findings where a reader will find them without a PR, and say what was held back and that `ce-debug` invoked directly fixes inline on a branch the user is still working on.
+
+## What later steps receive instead of a plan path
+
+- **Step 3, `ce-simplify-code`:** pass `changed_files` as the scope, never the branch diff, so the pass cannot reach work the user did not offer; pass `root_cause` as the structure the simplification must keep, so the fix is not simplified away; pass `mode:pipeline` and each test `verification_evidence` names as proving the fix as its own `proof-test:<path>`.
+- **Step 4, `ce-code-review`:** no `plan:` argument. Its requirements check is additive by its own contract and it infers intent from the commits; pass the `root_cause` summary as review context. The review has no fix-only scope and reads the working tree, so it may report on files the user did not offer; step 5 applies a finding only to `changed_files` and this run's own edits, and reports the rest as residuals.
+- **Step 6 and step 9:** the settled-decisions brief was never composed on this route, so no settled-decisions provenance line is rendered. Pass `root_cause` and `issue_of_record` to `ce-commit-push-pr` as PR-description context, so the PR body carries the diagnosis and links or closes the ticket, and name the files that must stay out of the commit.
+- **Step 7, `ce-compound`:** the same counterfactual applies; a debugged root cause is the most common shape of a durable learning.
+- **Step 11, close-out:** the next-work offer reads a plan and is not made.

package/skills/lfg/references/intake.md

@@ -0,0 +1,30 @@
+# Intake: choosing the route (LFG step 1)
+
+Read this before choosing the route. It defines the routes, their precedence when more than one matches, what each child skill is invoked with, how its return is read, which routes end the run at the child's result, and what is never a work source. The body's work-source and stop clauses still apply; this file supplies what they cannot decide alone.
+
+## What the session identifies
+
+The work source starts from what the invocation and the conversation carry: a feature description, an issue reference, a plan path, a plan `ce-plan` wrote earlier in this session, a brainstorm artifact, or a handoff the user resumed. A file that exists in the plans directory but that nothing in the session names is not identified. `ce-work`'s blank-invocation intake discovers the newest plan on disk; `lfg` never invokes `ce-work` blank, so that path is unreachable from here. When nothing identifiable was given, the route is the plan route with an empty description, which `ce-plan` answers by asking what to plan when a human is present and by returning blocked when none is.
+
+## Routes, in precedence order
+
+Classify from the request and bounded inline reads of what it names, only as far as needed to choose. Grounding depth belongs to the child skills: `ce-plan` and `ce-brainstorm` already read the repository and call `ce-explain` on their own condition. Take the first route that matches.
+
+1. **Plan path.** The request asks for a plan to be carried out or continued, and names it: a unified plan artifact path, a brainstorm artifact, or a plan `ce-plan` already wrote this session. A request that only mentions a plan while asking for something else (`explain <plan path>`, `is this plan sound?`) is routed by what it asks for, not by the path it carries.
+   - A requirements-only artifact, or a path to a plan from an earlier session: invoke `ce-plan` with it, prefixed by the settled-decisions brief `references/plan-brief.md` defines. `ce-plan` enriches or resumes it, checks drift and settled-decision conflicts, and reports it this run. That reported path is the work source.
+   - An implementation-ready plan `ce-plan` wrote in this session: the work source is that plan; step 2 invokes `ce-work` on it directly. `ce-work`'s intake verifies readiness and prerequisites by content and returns blocked when the plan is not sufficient, which stops the run.
+2. **Defect.** A concrete report of failing or wrong behavior that the request asks to have fixed. A request for the diagnosis alone (`explain why this test fails`, `diagnose #123`) is route 5, and `ce-debug` invoked there under its own contract ends the run with the diagnosis. Whether the failure reproduces is `ce-debug`'s question, not intake's; an intermittent or environment-specific failure is still a defect. It usually arrives as an issue reference (`ESP-1234`, `#123`, an issue URL), a stack trace, a failing test path, or a description of broken behavior. A reference alone is not proof: read enough of the ticket to see that it describes a defect; a ticket describing a feature takes route 1 or 6. Invoke `ce-debug` with `mode:return-to-caller <bug>`, passing the reference through unchanged so `ce-debug` treats it as the issue of record. Read `references/debug-return.md` before reading its return; that file is the gate. Only a `fixed` return is a work source, and steps 3 onward run from it in place of a plan.
+3. **Judgment on the way to a change.** The request asks for a change to the code and that change depends on a decision the user did not settle: adopting or replacing a named external technology, choosing among supplied approaches, a "should we" attached to a build. A request that asks only for the judgment (`should we adopt Redis?`, with nothing to build) is route 5, and the run ends with the verdict. Invoke `ce-pov` with the question and the decision it informs. Adopt, Trial, or a position that supports the request continues to route 4 or 6 with the verdict carried as cited evidence in the brief's direction and open areas, never as a settled decision. Reject, Hold, Not-our-problem, a position against the request, or a Blocked result stops the run with the verdict and its evidence.
+4. **Product shape unsettled.** More than one product behavior is a plausible reading, or a product question no evidence settles. When a human is present (a person can answer in this session: the run is not headless and carries no `mode:pipeline`; how the host asks, a question tool or numbered chat options, does not matter), invoke `ce-brainstorm` with `mode:return-to-caller <feature description>`. Its return carries `status`, `result_kind`, `artifact_path`, `brief`, `resolve_before_planning`, and, when a grounding scout ran, `grounding_path`; pass that path to `ce-plan` on either continuation so planning starts from the verified evidence. A non-empty `resolve_before_planning` stops the run with those items. An `artifact` result enters route 1 as a requirements-only artifact. A `brief` result enters route 6 as the feature description, with its `key_decisions` carried in the settled-decisions brief. When no human is present, take route 6: `ce-plan` in pipeline mode records an unresolved product fork as an explicit assumption in the plan, which the PR body then carries.
+5. **A result that is not a code change.** Match the request to the Compound Engineering skill whose description owns that result, and invoke it with the request as given. Examples: `explain the architecture of X` is `ce-explain`; a throwaway prototype to settle how something should work, look, or feel is `ce-prototype`; a judgment with nothing to build is `ce-pov`; an open field of ideas is `ce-ideate`; a session handoff is `ce-handoff`. The examples are not the list; the host's skill catalog is. When no Compound Engineering skill owns the result, say so and end. A prototype exists to be experienced by a person, so that route runs only when a human is present (the same condition route 4 uses); headless, stop and say the prototype needs a person rather than invoking a skill that must refuse. That invocation is the whole run: end with its result, with no branch, no work source, none of the steps after intake, and no DONE promise, which belongs to the code-change steps. Invoking means running that skill's own procedure from its file; answering in its place, however well, is not the route. The prototype ends the run only when the prototype is what was asked for. When the request also asks for the winner built, the choices `ce-prototype` returns to its caller are user-directed decisions: carry them in the brief and continue to route 6 with the request. A question that arrived with an issue reference or a plan path is still a question, and route 1 already excludes it; the route is decided by what is asked for, not by what is attached.
+6. **Plan.** Everything else that changes the code. Invoke `ce-plan` with the feature request, sanitized per `references/stage-routing.md` when a routing directive was present, and the settled-decisions brief when the conversation carries settled decisions. The `plan_model:<alias>` carrier rides beside the request when a planning-stage directive resolved. `ce-plan`'s reported plan is the work source once it passes the readiness check in `references/plan-brief.md`.
+
+When unsure between two routes, take the one that asks more of the evidence: brainstorm over plan when a human is present, `ce-pov` before either when a change hangs on an unsettled judgment, `ce-debug` when the report is concrete and asks for a fix, and a prototype only when the request asks for one rather than for the thing itself.
+
+## What every child receives, and what none receives
+
+Every child skill receives only its own input: the sanitized request or path, the brief when one exists, and the carrier its stage accepts. No child receives the routing directive as product content. On route 3, `ce-pov`'s verdict reaches `ce-plan` as evidence, not as a `session-settled:` decision, because the settled-decisions design allows only user-directed and user-approved provenance and an agent never settles its own recommendation.
+
+## Recording the route
+
+Narrate the chosen route in one line before invoking the child, naming the request shape that decided it. On the task surface `references/task-visibility.md` defines, a route not taken is not listed; the chosen route's child skill owns the surface while it runs.

package/skills/lfg/references/next-work-handoff.md

@@ -0,0 +1,96 @@
+# Next-work handoff
+
+Use this only at LFG closeout, after the current pipeline has finished or
+stopped for good. Its purpose is to offer continuity into a separately planned
+area without silently extending the completed plan or current session.
+
+## Establish whether an offer is warranted
+
+Start from the canonical plan path retained from LFG step 1. Locate a Product
+Contract section carrying the semantic role `work-relationships`:
+
+- Markdown: `<!-- ce-section: work-relationships -->`
+- HTML: `data-ce-section="work-relationships"`
+
+The visible heading is not part of this protocol. For an older unmarked plan,
+use a semantic fallback only when one Product Contract section clearly names
+the area this plan covers, one or more future areas intended for separate
+planning, and their relationships. Do not infer eligibility from an exact
+heading, a generic list of non-goals, or a roadmap-like wish list. If the
+section's meaning is ambiguous, make no offer.
+
+An offer is warranted only when the completed work is explicitly one part of a
+larger body of separately planned work and at least one future area remains
+unplanned. Exclude an area that is already planned, completed, absorbed into
+the just-finished work, or no longer supported by current evidence. A residual
+implementation, review, PR, or merge task belongs to the current run's remaining
+shipping work; it is not a next brainstorm candidate and does not by itself
+suppress a valid future-area offer.
+
+## Recommend the next area
+
+Reason over the remaining candidates instead of taking the first bullet. Prefer
+the area that, based on the plan and what the pipeline learned:
+
+1. has explicit user or plan priority;
+2. can be meaningfully brainstormed now;
+3. is enabled by the completed work;
+4. unlocks the most downstream work;
+5. reduces foundational uncertainty; or
+6. especially benefits from fresh implementation knowledge.
+
+These are judgment criteria, not a points system. Do not choose by document
+order, apparent ease, wording similarity, or a dependency the plan does not
+support. Recheck the candidate against the current delivery result before
+offering it.
+
+- **One justified winner:** name it and give the shortest concrete reason it is
+  next.
+- **Real tie:** say current evidence does not justify choosing between the tied
+  areas. Offer a selection-focused handoff whose next session decides which one
+  coherent area to brainstorm.
+- **No ready candidate:** make no offer.
+
+## Offer, then stop
+
+Place the offer before LFG's `<promise>DONE</promise>`. Keep it non-blocking and
+do not invoke `ce-handoff` yet.
+
+For one winner, use this shape in natural prose:
+
+> The clearest next area is **<area>** because <reason>. If you want to continue
+> it in a fresh agent session, I can create a `ce-handoff` for that brainstorm.
+
+For a real tie, name the tied areas and offer a fresh-session handoff focused on
+choosing the next coherent area. The pipeline still ends with the DONE promise;
+the offer is optional continuity, not another LFG step.
+
+## If the user later accepts
+
+Only after explicit acceptance, resolve `ce-handoff` against the host's
+available-skills list and invoke `create` with a compact, labeled next-work
+brief. LFG owns the recommendation: it has already chosen, so do not ask
+`ce-handoff` to rediscover or rank candidates. Include:
+
+- **Next-session objective:** brainstorm one coherent next area and produce a
+  requirements-only unified plan.
+- **Recommended area:** the winner, or the tied candidate set when the session
+  must choose.
+- **Why next:** the evidence-based selection rationale.
+- **Authoritative prior plan:** the repo-relative canonical plan path.
+- **Relationship to completed work:** the explicit depends-on, enables, shares,
+  or independent relationship.
+- **Actual delivery state:** what finished and what remains in the current run's
+  shipping steps, such as implemented, PR open, CI decided, or not merged.
+- **Carry-forward decisions:** only prior decisions that constrain the next
+  area.
+- **Assumptions to revalidate:** provisional relationships or facts that the
+  fresh brainstorm must not inherit as settled.
+- **Other candidates not selected:** each alternative and why it was not chosen,
+  when that context prevents repeated selection work.
+- **Artifact boundary:** create a separate requirements-only unified plan for
+  the next area, cite the prior plan, and do not extend or edit the prior plan.
+
+Keep the brief short, and point at files rather than copying them. Do not paste
+the prior Product Contract into it; the plan remains authoritative and the
+handoff explains what the next session needs to decide.

package/skills/lfg/references/plan-brief.md

@@ -0,0 +1,36 @@
+# Step 1: artifact root and settled-decisions brief (LFG)
+
+## Artifact root
+
+Resolve `<root>` when you first compose a `<root>/` path, never before you need it. LFG composes only one such path: the `<root>/plans/` location where step 1's GATE checks that the plan was written. A run that stops before that check never composes a `<root>/` path and never resolves a root. Two examples: a routing-carrier blocker (a stage assignment LFG cannot pass on, as `references/stage-routing.md` defines), or a report that the task is non-software.
+
+<!-- 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 -->
+
+## Readiness check
+
+An explicit `status: blocked` return is terminal even when `artifact_path` names a readable plan. Report its `phase`, `blocker`, and `recovery_path`, and its `artifact_path` when present. A plan file existing on disk is not a reason to retry planning or to move on to implementation.
+
+The plan the GATE checks is the path `ce-plan` reported writing this run. A file already under `<root>/plans/` that `ce-plan` did not report is not a written plan, however closely it matches the feature. This gate belongs to the plan route. An implementation-ready plan `ce-plan` wrote earlier in this session bypasses `ce-plan` per `references/intake.md`; `ce-work`'s intake verifies that plan by content, and its blocked return stops the run. When the return has neither a blocker nor a reported path, invoke `ce-plan` the single allowed second time; never accept a stale file instead.
+
+Inspect the returned plan before continuing past step 1's GATE. It must describe code implementation with sufficient scope, direction, and verification, and no launch-blocking question or finding. A Product Contract without implementation planning, an approach-only or answer-seeking output, or a non-code deliverable (`execution: knowledge-work`) stops the pipeline. An old readiness label cannot override the contents. `ce-work` owns verification of the active work's repository prerequisites; this gate does not duplicate that investigation.
+
+## Settled-decisions brief
+
+Compose this brief from the invoking conversation and pass it with the sanitized feature request when you invoke `ce-plan`.
+
+The brief contains:
+
+- direction (1-2 lines);
+- settled decisions, each with four required fields: the decision, its provenance class (`user-directed` or `user-approved`), the rejected alternative, and a one-line reason;
+- open areas, including any `ce-pov` verdict the intake route consulted, cited as evidence with its grade and reason, never as a settled decision;
+- a standing line asking `ce-plan` to report any conflict it finds with these decisions.
+
+If you cannot state an entry's rejected alternative, demote it to a directive or an open area. Include only decisions about the feature being shipped. When in doubt, demote: having `ce-plan` reconsider a decision is the safe direction; carrying in a stale decision as settled is not. When there is nothing to carry, no settled decision and no `ce-pov` evidence, skip composition entirely and invoke `ce-plan` exactly as it is written in the body, with no empty brief.
+
+The brief is temporary: once `ce-plan` writes the plan, the plan's labeled KTDs are the record. A step-1 retry reuses the composed brief verbatim; never recompose it.

package/skills/lfg/references/review-followup.md

@@ -0,0 +1,78 @@
+# Pre-ship quality steps (LFG steps 3–7)
+
+These are the quality steps that run after implementation and before shipping. On the defect route the implementation was `ce-debug`'s fix; `references/debug-return.md` names what each step below receives in place of the plan path. `ce-code-review` is review-only. LFG applies eligible fixes itself, then commits.
+
+## The shipping precondition, in these steps
+
+When the repo has no remote, the run finishes locally. That is a final state, not an error: never retry a push or hunt for a remote. Step 5 still makes every commit it calls for; only the pushes and the records that would live on the PR are dropped. With no PR to hold the unapplied findings, step 6 files them as tracker tickets and the DONE report states the rest. Never write them to a committed file nobody will read.
+
+## Step 3 — simplify before review
+
+Simplification runs before review so the code-review in step 4 covers the simplified code. Let `ce-simplify-code` resolve the branch-diff scope itself; it preserves behavior and runs the test suite. Pass the plan path from step 1 as context about structure the simplification must keep, not as the simplification scope (the branch diff remains the scope); on the defect route pass the debug return's `root_cause` and `changed_files` instead, so the fix is not simplified away. On either route, pass each test `verification_evidence` names as proving the work (the regression or red-before-fix test, characterization coverage, or an existing test used unchanged) as its own `proof-test:<path>`, so the simplification leaves those tests untouched. Add a one-line constraint: KTDs labeled `session-settled:` describe structure the simplification must preserve, so deliberate duplication stays duplicated.
+
+Do not commit in this step. `ce-simplify-code` leaves its changes in the working tree; step 4's review scopes the working tree (uncommitted changes included), and step 9's `ce-commit-push-pr` commits whatever remains. Committing here would sweep any still-uncommitted `ce-work` edits into a misleading `refactor` commit and could stall on a tree that never goes clean.
+
+## Step 4 — invoke `ce-code-review`
+
+Load `ce-code-review` from the host catalog's listed path. A host skill named `review` is not this step; do not invent `skills/review/SKILL.md` under this plugin.
+
+```
+ce-code-review mode:agent plan:<plan-path-from-step-1>
+```
+
+Read the **Actionable Findings** summary and artifact path. Do not pass `mode:autofix`.
+
+Pass the plan file path from step 1 so `ce-code-review` can verify requirements completeness. On the defect route there is no plan: omit `plan:` and pass the `root_cause` summary as review context; the requirements check is additive by `ce-code-review`'s own contract and review still covers the diff. Also read any findings stamped `settled_conflict` (each names the conflicting KTD). Stamped findings that are matters of preference do not stop the pipeline (they are report-only), but they must reach step 6's record of unapplied findings.
+
+`mode:agent` is report-only **by design**: it reports findings but never edits the tree, and LFG applies the eligible ones in step 5. When narrating progress to the user, frame this as "review found X -> applied X in step 5," not as "code review did not auto-fix." A report-only review followed by an LFG-applied fix is the intended contract, not a gap.
+
+Capture parsed JSON (`status`, `actionable_findings`, `findings`, `artifact_path`, `run_id`) or the markdown Actionable Findings section. If `status` is `failed`, stop and report `reason`.
+
+## Step 5 — apply and persist review fixes
+
+### What to apply
+
+Apply a finding in the working tree only when **all** of the following hold:
+
+1. **`suggested_fix` is present** — concrete change shape from the reviewer.
+2. **`confidence` is `100`, or `75` with cross-persona agreement noted in the report** — do not apply anchor-50 findings.
+3. **The fix is mechanical** — one coherent change; no change to a contract, permission, or security stance; no new public API shape; no behavior change that needs product sign-off.
+4. **Evidence still matches the code** at the cited `file:line` before editing.
+
+Do not treat `autofix_class` as permission to auto-apply.
+
+### What not to apply
+
+- `autofix_class: manual` without a clear mechanical `suggested_fix`
+- `autofix_class: advisory` — report-only
+- `gated_auto` findings that change behavior, contracts, auth, or permissions
+- Anything that needs a design conversation
+
+### Execution
+
+1. Filter `actionable_findings` (or markdown Actionable Findings) with the bar above.
+2. Apply eligible fixes in the working tree in severity order (`#` stable from the review).
+3. Run targeted tests when `requires_verification: true` on any applied finding.
+4. If `git status --short` shows changes, stage only review-driven files and commit `fix(review): apply review findings`. Then push before step 6 **when a remote is configured** (per LFG's shipping precondition) and, on the defect route, when everything the push would publish is work the user offered (`references/debug-return.md`). To push: if an upstream exists, run `git push`. If no upstream exists but a remote is configured (common on a fresh feature branch), pick a writable remote at run time: prefer `origin` when present, otherwise run `git remote` and choose the first configured remote. Then run `git push --set-upstream <remote> HEAD`. If there is no remote at all, do not push; the local commit suffices. If no eligible fixes were applied, say so explicitly and skip the commit.
+
+## Step 6 — residual handoff
+
+Residuals are the findings left over: actionable findings **not** applied in step 5. They are not leftovers from an autofix inside `ce-code-review`. Use the Actionable Findings summary / artifact from step 4.
+
+Two further triggers also require step 6, both outside the apply path: step 4 emitted any `settled_conflict`-stamped findings, or step 2's return carried proceeded-and-flagged `settled_decision_conflicts` entries. These are the findings where the work diverged from a settled decision, and this step is where they get written down somewhere that lasts.
+
+A residual at this point is undecided, not accepted debt. Step 5 declined it because it needs judgment, and the pipeline does not merge unless the user granted it, so the human reviewing the PR supplies that judgment: fix it in this branch, dismiss it, or file it to carry past merge. The record therefore goes where that reviewer already looks, the PR body. The pipeline files no tickets for these; one ticket per finding, decided by nobody, is how a run of small nits floods a tracker.
+
+**When a PR will exist (a remote is configured):** compose a `## Unapplied review findings` section, one checkbox bullet per item so a human ticks it when they close it:
+
+- For each unapplied actionable finding: `- [ ] <severity> — <file:line> — <title>`, plus the reviewer's `suggested_fix` on the next line when present.
+- For each `settled_conflict`-stamped finding from step 4: the same bullet plus the conflicting KTD the stamp names — included even though the finding is report-only.
+- For each proceeded-and-flagged `settled_decision_conflicts` entry from step 2: a bullet with the KTD, the evidence, and how it was routed.
+
+Close the section with the review run context (`run_id`, `artifact_path`). Hand the section to step 9 as PR-description context; `references/shipping.md` says where step 9 passes it into `ce-commit-push-pr`. Step 9 writes the body, so nothing here edits the PR directly, and nothing posts a PR comment for these.
+
+**When no PR will exist (no remote):** load `references/tracker-defer.md` in **non-interactive mode** with the same items, collect `{ filed: [...], failed: [...], no_sink: [...] }`, and state every `failed` and `no_sink` item verbatim in the DONE report. The report is the only record those get.
+
+## Step 7 — compound before shipping
+
+Invoke `ce-compound` with `mode:non-interactive` when the run produced durable reasoning that the final code, tests, and plan or diagnosis do not carry, and losing it would plausibly cause recurrence or substantial rediscovery. The plan or `root_cause`, the review residuals, and the fixes applied in step 5 are the evidence for that judgment. `ce-compound` writes into the repository's tracked learnings store on the branch and asks nothing; `Documentation skipped` is a successful outcome, not a stop. Step 9 commits and pushes whatever it wrote with the rest of the change, so the learning is in the PR at the moment it opens and CI runs against a head that contains it. Do not run it after the babysit result: a push after "CI decided" leaves an unwatched head.

package/skills/lfg/references/shipping.md

@@ -0,0 +1,65 @@
+# Shipping (LFG steps 9–11)
+
+The shipping steps are the last stretch of the run: commit, push, PR, CI, and close-out. LFG's SKILL.md defines the shipping precondition (the `git remote` check) and the two invocation strings. This file defines everything else: which handoff runs, what LFG passes into it, what it does with the result, and how the run closes out.
+
+## Step 9 — a project-defined process may replace the default handoff
+
+The goal is the remaining work committed, pushed, and in an open PR whose URL you hold.
+
+The project's active instructions may name a process for that handoff: a named skill or command, a stacking tool, or documented steps. Commit or PR-title conventions do not count, because the default already honors them, and a skill directory alone is not a directive. When such a process is named, run it non-interactively with the same plan path and context below instead of the default. It is done only when the work is pushed and you hold the URL of an open PR containing it, either one the process opened or a PR that already exists for the branch. If it cannot run headlessly, is unavailable, or ends short of that state, stop as **blocked** naming the process. Do not fall through to the default or to step 10.
+
+## Step 9 — what LFG passes into the default
+
+Pass the recorded plan path from step 1 into the `ce-commit-push-pr` invocation, along with any proceeded-and-flagged `settled_decision_conflicts` entries from step 2, so the PR body can include its settled-decisions provenance line and its note that work proceeded under a flagged conflict. On the defect route there is no plan and no brief: pass the debug return's `root_cause` and `issue_of_record` as PR-description context instead, per `references/debug-return.md`, so the PR body carries the diagnosis and links or closes the ticket. Also pass step 6's `## Unapplied review findings` section, when one exists, as PR-description context to be rendered as a dedicated section verbatim. That section is the record of unapplied findings; a run that opened a PR without it has lost them.
+
+This commits any remaining changes, pushes the branch, and opens a pull request, non-interactively because of the `mode:pipeline` token. If it prints a `New concepts:` trailer after the PR URL, record the concept name(s) for step 11. If a PR already exists for the branch (check with `gh pr view --json number,url,state 2>/dev/null`), skip PR creation but still commit and push any uncommitted changes. Pipeline mode leaves an existing PR body alone by default, so the description context above would be lost there; after the push, invoke `ce-commit-push-pr mode:pipeline` again in its description-update mode on that PR with the same context, so the record reaches the reviewer without a confirmation prompt.
+
+**Per the shipping precondition, when no remote is configured, do NOT invoke `ce-commit-push-pr` or a project-defined shipping process.** The default's commit step pushes unconditionally (`git push -u origin HEAD`), so a literal invocation would still hit the impossible push. Instead commit the files this run changed, by name (the work source's files, the review fixes, and any captured learning), and skip the push and PR creation entirely. Never `git add -A`: a file that was already dirty before the run, or one the defect route's `pre_fix_scope` lists, stays uncommitted and is named in the report.
+
+## Step 10 — stack handoff from step 9
+
+If step 9's `ce-commit-push-pr` completed a stack-mode submit and handed off `ce-babysit-pr` on the **bottom open non-draft** PR with `posture:stack-ready` or `posture:stack-land`:
+
+- Do **not** start a second bare `mode:pipeline` babysit on the current-branch URL. A second run can replace the stack-aware one with a run that watches only the current PR, or watch the wrong layer of the stack.
+- Prefer the structured result already returned from that handoff when it reflects a completed pipeline stop.
+- If step 9 only confirmed babysit **started** (or no structured result is available), re-invoke `ce-babysit-pr mode:pipeline <bottom-pr-url> posture:<same>` and wait for its pipeline completion — never treat "started" as DONE.
+- Record the bottom PR URL and posture for step 11's user-facing resume line.
+- Collect `{ status, fixes_applied, residuals }` and proceed to step 11.
+
+## Step 10 — the default babysit
+
+Otherwise invoke `ce-babysit-pr mode:pipeline <pr-url>` on the current open PR. It runs the bounded pipeline loop: it watches CI, repairs real (convergent) failures via `ce-debug mode:pipeline` without ever weakening, skipping, or mocking an assertion, resolves any review comments that arrived via `ce-resolve-pr-feedback mode:pipeline`, and stops when CI is decided or its budget (default 3 fix rounds) is hit. This replaces LFG's former hand-rolled CI loop; do not reimplement CI-watching here.
+
+Invoke it unconditionally whenever an open PR exists **and** step 9 did not already hand off stack babysit. That includes a run under a standing `auto_babysit: false`: that setting opts out of the open-ended watch handed off after a PR is opened, not of this bounded loop that produces the pipeline's "CI decided" result. A run whose CI looks likely-clean is not a reason to skip babysit and poll `gh pr checks` yourself. Green CI at one instant is not this step's goal: babysit also resolves review comments across the PR's life, so a passing check while advisory checks (e.g. Bugbot) are still pending or comments are unhandled is not "done" and never substitutes for the invocation.
+
+Collect its structured result (`{ status, fixes_applied, residuals }`).
+
+Merging is the user's unless they granted it for this run. When they did, pass the grant in the form `ce-babysit-pr` accepts: `posture:stack-land` on a managed stack. A single-PR grant has no pipeline carrier today, so on that path do not merge yourself; say in the close-out that the grant could not be carried and the merge is still theirs.
+
+## Step 10 — common result gate
+
+This check applies to whichever handoff produced the result. Keep the `needs-human` residuals it returned unchanged, with every field they carry. Before DONE, render the complete set under `## Needs your decision`, including each residual's quoted feedback, investigation, decision reason, options and tradeoffs, recommendation if any, and every open-thread link. A non-empty set means the run hands decisions to the user; it is never successful completion. A generic count or a PR link does not count as passing the set on. Unfixable CI still belongs in the babysitter's run-report comment, never a PR-body section.
+
+## Step 11 — close out
+
+Everything below happens before LFG outputs `<promise>DONE</promise>`. Write the close-out, the `## Needs your decision` framing, and any progress you narrate to the user through the `ce-noslop` skill; the residual entries themselves are rendered verbatim.
+
+### Rendering the user-runnable invocations
+
+For the two handoffs below, default to `/ce-explain <name>` / `/ce-babysit-pr <pr-url>`. Use `$ce-explain <name>` / `$ce-babysit-pr <pr-url>` only when the active host is Codex or explicitly documents dollar-prefixed skill invocation. Render only the invocation as inline code and output one form only.
+
+### New concepts
+
+If step 9 recorded a `New concepts:` trailer, first echo one line per concept: `New concept introduced: <name> — run <rendered ce-explain invocation> to go deeper.`
+
+### The open PR
+
+If an open PR exists, add one line pointing the user to the interactive watch-to-merge (pipeline mode stopped at "CI decided," not "merged"): `PR is moving — run <rendered ce-babysit-pr invocation> to watch it through review to merge.`
+
+When step 9/10 used a stack handoff, render that invocation for the **bottom open non-draft** PR URL with the same `posture:stack-ready` or `posture:stack-land` token — never a bare current-branch URL that would supersede stack scope.
+
+### The optional next-work offer
+
+On the defect route there is no plan: make no next-work offer. Otherwise inspect the plan recorded in step 1 for the semantic role `work-relationships`. Load `references/next-work-handoff.md` when that role exists, or when an older unmarked Product Contract appears to name the area this plan owns plus future separately planned areas and their relationships. That reference defines the cautious legacy semantic fallback, how to choose the candidate, and how the opt-in offer is worded. Do not match an exact visible heading, treat ordinary non-goals as future work, or invoke `ce-handoff` before the user explicitly accepts the offer. If neither semantic signal exists, do not load the reference and make no next-work offer.
+
+Then output the DONE promise.

package/skills/lfg/references/stage-routing.md

@@ -0,0 +1,49 @@
+# Per-stage routing carriers
+
+A carrier is the prefix string that passes a stage assignment (which model or harness should do that stage's work) to a child skill. LFG has two routable stages, each with its own carrier. This file defines how to detect an assignment, how to resolve its scope and strength, the carrier grammar, the ordered-fallback case, how to strip routing from the feature request, and how each carrier is passed when LFG invokes the child skill.
+
+LFG is otherwise hands-off and never stops to ask. The single question it may ask is the one in scope rule 3 below, and only on an interactive host.
+
+## What is routable
+
+Interpret whether the invoking conversation expresses **semantic intent to assign a pipeline stage** — planning or implementation — to a specific model or harness. This is judgment, not keyword or prompt-token matching: an explicit instruction such as "plan with fable" or "use Codex for implementation" creates an assignment, while a plain mention of Codex, Composer, Fable, or another model/harness in feature content, quoted material, comparison text, or a filename does not. Two pipeline stages are routable, each with its own carrier:
+
+- **Planning** routes to `ce-plan` as a `plan_model:<alias>` carrier. This names the **model** that authors the plan (model elevation) and nothing else. Example aliases: `fable`, `opus`. LFG has no way to pass a harness assignment to planning: an assignment that scopes a *harness* to planning ("plan with codex", "plan on cursor") is **not supported**. Stop and report it as a routing-carrier blocker (a stage assignment LFG cannot pass on) rather than encoding a harness name as `plan_model:<harness>`, which `ce-plan` cannot serve and would silently fall back to the session model. Only the implementation stage routes to a different harness.
+- **Implementation** routes to `ce-work` as an `implementation_engine` object (grammar below). This names the harness and model that write the code.
+
+## Resolve each directive by scope
+
+1. **Scoped directive** — the instruction names the stage ("plan with fable", "codex for implementation", "plan fable, codex work"). Route it to that stage's carrier. Multiple scoped directives may resolve at once, each to its own stage.
+2. **Unscoped directive** — a bare model/harness assignment with no stage named ("use fable", "with codex"). Bind it to the **implementation stage only**; never broaden an unscoped directive to planning or to every stage. Disclose the resolved binding in LFG's opening line before step 1 (e.g. "Routing implementation to Codex; planning stays on the session model.").
+3. **Unscoped and genuinely ambiguous, human present** — ask exactly **one** upfront question to bind the stage before step 1, then proceed hands-off. Ask only when all three hold: an unscoped directive could credibly belong to more than one stage, mis-binding would be materially costly, and the host is interactive (it exposes a blocking-question tool and is not a `disable-model-invocation`/headless run). In a `disable-model-invocation`/headless run, never ask; apply the implementation default and disclose it. The default path is mandatory: LFG runs from schedulers, loops, and nested orchestrators with no user to answer, so an unresolved directive must always fall to the disclosed default rather than block.
+
+Requirement strength is inferred from the whole instruction, not one word: "use Codex for implementation" is preference-strength (`prefer`); "only use Composer for implementation" is requirement-strength (`require`) because its meaning rejects native fallback.
+
+## Implementation carrier grammar
+
+When implementation resolves to one candidate, retain one transient `implementation_engine` object with exactly these four fields:
+
+- `mode`: `prefer` or `require`
+- `target`: exactly one of `codex`, `claude`, `grok`, `cursor`, `composer`, `opencode`, or `antigravity` — a **harness** name, never a model name
+- `model`: the explicit model pin, otherwise `null`
+- `source`: a caller-visible string saying where the binding came from, identifying the current LFG instruction
+
+A directive that names a bare **model** with no harness (e.g. "use fable", "with opus") is a model *pin*, not a target: encode it as the harness that serves that model family with the alias in `model`. A Claude-family model (`fable`, `opus`, `sonnet`, `haiku`) is `{"target":"claude","model":"<alias>"}`. Never put a model name in `target`. If you cannot map the named model to one of the harnesses above, that is a routing-carrier blocker, not a `null` binding that silently drops the user's instruction.
+
+When the implementation instruction instead names an ordered fallback list, do not truncate it to the scalar carrier (the single-candidate object above). Instead, retain the whole ordered assignment as current-task implementation intent and pass no `implementation_engine:` object. When LFG invokes `ce-work`, that still-active current-task assignment outranks configuration, and `ce-work` normalizes and preflights the candidates in order. This is context scoped to the implementation stage, not plan content. If the host cannot preserve that context across its skill invocation, stop with a routing-carrier blocker rather than silently dropping later candidates.
+
+## Sanitize product input
+
+Remove every routing directive from the feature request that enters planning, keeping the request otherwise unchanged. Never pass the `implementation_engine` object or any removed directive to `ce-plan`, `ce-doc-review`, `ce-code-review`, the settled-decisions brief, or any planning or review **product** input. The carrier is a routing instruction for one stage, not product content or a settled product decision. The `plan_model:<alias>` carrier is the one exception: it is structured routing data handed to `ce-plan` *alongside* the sanitized request, never woven into it. Do not construct a carrier from standing configuration here: when no explicit binding exists for a stage, `ce-work` and `ce-plan` each decide for themselves how to apply still-applicable session/project intent and standing per-checkout configuration.
+
+## Pass the planning carrier at step 1
+
+When a planning-stage directive resolved, prefix the `ce-plan` invocation with its `plan_model:<alias>` carrier. It is structured routing data beside the request, never woven into it, so `ce-plan`'s model elevation authors the plan on the chosen model even in pipeline mode.
+
+## Pass the implementation carrier at step 2
+
+Use `mode:return-to-caller <plan-path-from-step-1>` when no scalar transient carrier exists, including when a retained ordered current-task assignment is still active in context. When the scalar carrier exists, use the exact string-host form `mode:return-to-caller implementation_engine:<compact-json> <plan-path-from-step-1>`.
+
+Serialize its exact `implementation_engine.{mode,target,model,source}` data as compact JSON immediately after the `implementation_engine:` prefix (for example `implementation_engine:{"mode":"prefer","target":"codex","model":null,"source":"lfg-current-turn"}`). This is structured caller data in a portable string any host can pass through, not part of the plan path or implementation prompt. Pass no empty carrier when it does not exist. `ce-work` then resolves a retained ordered current-task assignment when present, otherwise applicable session/project intent and standing per-checkout configuration. LFG is an automatic, headless caller: it never prompts to weaken a requirement-strength route.
+
+The optional `implementation_run:<safe-id>` carrier is recovery-only. Never include it on the initial step-2 call. On the one evidence-reconciliation recovery, place it after the same engine carrier when one existed and before the unchanged plan path: `mode:return-to-caller implementation_run:<safe-id> <plan-path-from-step-1>` or `mode:return-to-caller implementation_engine:<compact-json> implementation_run:<safe-id> <plan-path-from-step-1>`. A safe id matches `^[A-Za-z0-9._-]{1,128}$` and contains at least one non-period character. Reject a malformed or duplicate run/engine carrier instead of launching work.

package/skills/lfg/references/task-visibility.md

@@ -0,0 +1,11 @@
+# Task visibility, narration, and completion
+
+Before step 1, use the platform's task-tracking capability when available to publish a short stage-level view of the remaining pipeline. Derive it from the user-meaningful outcomes of LFG's steps rather than mirroring all ten steps or exposing internal checks. Before invoking a child skill, replace or clear LFG's view so only the child skill's task surface is visible; after it returns, recreate or refresh LFG's remaining pipeline work before invoking the next child. Add a conditional step only when its condition is actually met. If no task-tracking capability is available, continue normally without simulating a task list in chat.
+
+## Chat narration
+
+Narrate the run in chat as it moves. Narration is chat prose, never entries on the task surface above. One line entering each step names the step and what it should produce; one line when it returns names what it actually produced (plan path, return status, fixes applied, PR URL). Close with a recap that stands on its own: what was built, how it was verified, what shipped, and any leftover findings. Print it alongside the close-out lines `references/shipping.md` defines, so a reader who sees only the final message has the full picture.
+
+## Completion discipline
+
+Report a step as done only after it actually ran and returned. Describing what a step would do, or what comes next, is not doing it; invoke it in the same turn. A child skill runs inline, and nothing resumes you when it returns. Its return ends the child, not the run: after writing or reading it, continue with the next numbered step in the same turn. Do not end the turn before `<promise>DONE</promise>` or an explicit GATE stop naming the blocker. Work merely described, or a step skipped outside its stated skip condition, makes DONE false.