work

<!-- soleur-cloud-mode:start --> **Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud. <!-- soleur-cloud-mode:end --> <!-- grok-harness-invoke:start --> **Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read. <!-- grok-harness-invoke:end --> <!-- work-anti-bypass-protocol:start --> ## Anti-bypass protocol (load-bearing — especially Grok Build) You are the **implementation orchestrator** for standalone `soleur:work` and one-shot Step 3: - **FORBIDDEN:** Pushing a branch and reporting "done" without `soleur:review` → `soleur:compound` → `soleur:ship`. - **FORBIDDEN:** Treating `## Work Phase Complete` as a turn boundary when you own the pipeline (see Invocation Mode below). - **REQUIRED (Grok Build):** Invoke `soleur:review`, `soleur:compound`, `soleur:ship` via slash commands — never hand-roll ship steps. - **Deliverable:** merged PR (standalone) or return to parent one-shot (pipeline mode). See `plugins/soleur/lib/workflow-fidelity.ts` (`IMPLEMENTATION_TAIL`) and Phase 4 Invocation Mode below. <!-- work-anti-bypass-protocol:end --> **"PROPAGATED" IS A MEASUREMENT ACROSS EVERY SITE ASSERTING THE CLAIM — NOT AN OBSERVATION ABOUT THE ONE YOU EDITED.** Grep for the OLD claim after correcting it, never for the new one: a residual count over the new text is structurally blind to the sites still carrying the old. A superseded position survives precisely where prose review does not look — machine-readable frontmatter, an operative conclusion far from the edited paragraph, and a DIFFERENT document citing the old position as its own contrast case — so a corrected document containing an uncorrected field clears both the gates and the review. **A literal grep is the WEAKEST of the three sweeps, and PARAPHRASE is the mode with no coverage** — wrap-insensitivity handles a blockquote splitting a phrase, and neither handles a site that restates the claim in different words. Write the claim as a SENTENCE and grep its paraphrases; the highest-risk position is a `**Prevention:**` line, because that is the part a future session executes. **Why:** #7957 — a sweep that was wrap-insensitive across all 9,684 tracked `*.md` returned 0 for a file it had just corrected, while that file's `## Session Errors` still prescribed "wait for the completion notification" as the remedy for an error it names "Inferred a commit VERDICT". **Why:** #7349 — a legal record's controllership was corrected in prose while its YAML `controller:` field FIFTEEN LINES ABOVE still asserted the superseded position, along with the operative balancing conclusion and a sibling document; the signed-off audit had already recorded that propagation as DISCHARGED. Same shape as the measurement rule below, one level up: that rule protects a number's freshness, this one protects a correction's reach. See `knowledge-base/project/learnings/2026-08-12-every-blocking-finding-was-the-defect-class-the-pr-existed-to-close.md`. **VERIFY A MEASUREMENT ONCE, BEFORE IT PROPAGATES.** When a plan's sweep will write the same measured fact into more than one file, verify it at the granularity you are about to CLAIM it — before the first write, not after the last. A false measurement does not stay where you put it: downstream files, issue comments, and review agents all consume it as fact and build on it, so the cost of correcting it scales with how far it spread, and the correction itself has to be swept. **Why:** #7325 — "cx33 is available in hel1-dc2" was read off a FLEET-WIDE probe and written into 4 files and 2 issue comments. It is false per-datacenter. Six review agents read it and one built its top finding on it (recommending an amendment to a hard-rule exception), so the error had already propagated one level past the diff before a 15-second re-probe falsified it. Project every measurement onto the exact scope you will assert — per datacenter, per host, per environment — and re-probe rather than adjudicating between two readings of the record. **SINGLE-SOURCE THE RATIONALE BEFORE WRITING IT, NOT AFTER REVIEW SAYS SO.** Prose is review surface: every restated paragraph is re-read by every agent and can drift independently. Write the reasoning ONCE at the artifact that owns the decision (the ADR for the element, the resource for the resource) and make every other site a one-line pointer anchored on content, not a line number. **Why:** #7325 — ~300 lines of justification prose across 8 files became the bulk of the review surface for a one-literal change, and two copies of the same probe table DIVERGED INSIDE THE SAME PR (one said "flipped twice", the other "three times") before any reviewer saw them. The review's own conclusion was to delete one copy. A short rationale plus a pointer is both cheaper to review and structurally unable to drift. **A ROLE TEST BUILT FROM AN ABSENCE DOES NOT DISCRIMINATE, AND ITS FIXTURE WILL AGREE WITH IT.** When one artifact is rendered for two roles (a shared bootstrap, a shared workflow, a shared config), scope role-specific behaviour on a POSITIVE identity the role owns — and emit that identity as a field so the consumer can require it rather than infer it. Never scope on "the other role does not have X": you must then prove the negative, and the CI sandbox lacking X will pass the arm you labelled "the other role" while proving nothing about it. Fixture the role that HAS X, with every input present and only the identity differing. **Why:** #7695 gated a destructive-recut input on "is `/mnt/data` a mountpoint", commenting that the co-located web host has no `/mnt/data`; `cloud-init.yml` mounts the workspaces volume there, so the probe would have walked every user's repo tree hourly and shipped a store measurement from the wrong host into a gate whose clearance condition is `0`. See `knowledge-base/project/learnings/2026-09-02-i-built-a-host-discriminator-out-of-an-absence-and-fixtured-the-absence.md`. **A CARDINALITY PIN COUNTS THE CONTAINER, NEVER OCCURRENCES OF THE MEMBERS YOU EXPECT — and a `verbose`-gated line is a silent one under every redirect.** `grep -c '<known-a>|<known-b>' -eq 2` is satisfied by a list holding both known members AND a third you did not name; the property "exactly two directories are searched for a payload to execute" is the arity of the `for d in …; do` line itself, so count ITS words. Same session, second shape: a skip line gated on `verbose` (`[[ -t 1 ]]`) prints nothing under a test's redirect or `claude --bg`, so a HELD branch and an UNCONSIDERED one produce identical stdout and the diagnosis goes to the wrong block. Before reading a guard's logic, grep the SUT for `verbose`-gated lines on that path. **Why:** #8418 — `/srv/extra-plugins` appended to all three `go.md` fences stayed green under `-eq 2` over known spellings; A9's reaper printed nothing per-branch and cost a round on the wrong hypothesis. See `knowledge-base/project/learnings/2026-09-20-every-defect-in-my-fix-was-a-sentence-i-could-have-run.md`. **ASSERT THE VALUE THAT MUST NEVER APPEAR, AND PUT THE INSTRUMENT UPSTREAM OF EVERY ASSERTION.** When a change exists to guarantee a value never occurs, assert that negative directly over every arm and every field — a positive "is it the token I expect" is satisfied by the correct answer AND by any arm that never reaches the field. Give each suite an instrument self-test that drives its pass/fail helpers once each and refuses to continue unless both counters moved, and report assertion-count floors with `printf` + `exit 1`, never through the helper they backstop (ADR-193). **Why:** #7695 — 16 of 24 mutants survived a 250-assertion battery; three flipped `__UNREADABLE__` to the literal `0` that authorizes a destroy and stayed green, `if eval "$condition"` -> `if true` produced a byte-identical summary line, deleting the entire new block reported `232/232 passed, 0 failed` exit 0, and the sibling suite's floor called the very `fail()` one edit disarms. Same learning file. **THE WRAPPER THAT REPORTS A GATE IS ITSELF A GUARD, AND IT IS THE ONE NOBODY REVIEWS.** The suite under test gets mutation rows, assertion floors and an instrument self-test; the five-line bash that RUNS it and reports the verdict gets none, so the could-not-measure/measured-bad collapse survives there. Three rules: never take a verdict from a PARTIAL artifact, and never from the completion NOTIFICATION either — the notification is authoritative for LIVENESS (has it exited?), never for VERDICT (did it succeed?), and TWO INDEPENDENT mechanisms defeat the verdict reading. (i) Its exit code is that of the LAST command the shell EXECUTED, so a trailing `git log` for convenience becomes the verdict — measured in #7912 (filed as #7957): three commits notified `exit code 0` while `git commit` had returned 1. (ii) A run killed mid-`tsc` by the memory reaper ALSO notified `completed`, with no trailing command involved at all — so ending the string with the command that matters does NOT make the notification trustworthy; a missing verdict line is UNRESOLVED, never a pass. Write the real code yourself — `echo "RC=$?" >> log` IMMEDIATELY after the command whose status matters, before any convenience line, because `$?` binds to the immediately preceding command — and read that; a per-step line is not the runner's verdict either. Never pipe a command whose exit code IS the result (`cmd | tail` takes the pipe's status and destroys the evidence in the same stroke — redirect and read `$?`); and make "the loop ran" observable, because `grep -c` exits 1 on zero matches, so `0 failures` and `0 executions` render identically. Put long-lived logs in the worktree — `/tmp` is swept between turns and leaves the writer holding a deleted inode — but never COMMIT the raw stream: a committed run record is the verdict block only (a full lefthook stream was 1.26 MB in #8207, against a ≤25 KB norm; `knowledge-base/project/learnings/2026-09-15-my-legal-record-said-the-change-had-landed-inside-the-pr-that-lands-it.md`). **Why:** #7828 — a partial lefthook tail read as "rejected" started a SECOND concurrent `git commit` in one worktree (two writers, one index); `git commit | tail -25` reported success on a failed commit and destroyed the only copy of a 52-minute battery failure, which then had to be re-run; and a fleet loop reported `0 reds` without proving it executed. Seven process errors, one shape — the same shape the PR's own 38 findings existed to remove. #7912 hit the two-writers case AGAIN by a different route: the harness reaped the parent `git commit` and its lefthook kept running, so a retry made two writers on one index. Before any git-write retry, check this worktree for a surviving hook process — a reaped task does not imply a reaped process tree. See `knowledge-base/project/learnings/2026-09-07-every-instrument-i-built-to-check-my-own-work-could-not-tell-clean-from-never-ran.md`. **A FILE-SELECTED SUITE SET CANNOT SEE A REPO-GLOBAL RATCHET — expect any change that adds a test, a floor, a regex or an operator-facing message to move a counter, and fix the code rather than the baseline.** When the full gate is refused or contended, the sanctioned substitute is to run the suites covering your diff, chosen by grepping which ones REFERENCE the changed files. That selection is correct and has one structural blind spot: a ratchet counts a property across the whole tree and references nothing, so no file-based query can ever return it. The failure is therefore not carelessness and does not improve with effort — it recurs until the selection is widened by hand. These baselines ratchet DOWN only, so the remedy is always the code: reword the message, rewrite the regex, promote the file, regenerate the baseline the gate's own failure text prescribes. **Why:** measured three times in one session — #7997/PR #8023 shipped green on its selected suites while CI reddened on `guard-vacuity-floor`, `lint-diagnosis-claims` and `fixture-relative-assert`; PR #8092 then reddened `no-control-regex` (19→20) on a two-file diff whose own suites were 91/91; and PR #8177 left `INDEX.md`/`kb-tags.txt` stale, so `kb-search --tag` could not find the learning that documents this rule. None of those artifacts referenced a changed file AT SELECTION TIME — `guard-vacuity-floor` names one today only because promoting that suite was the remedy, which is why re-grepping later appears to refute this. See `knowledge-base/project/learnings/2026-09-14-i-tested-both-endpoints-and-left-the-wire-between-them-unpinned.md`. **REGENERATE A WHOLE-REPO RATCHET BASELINE ONLY AFTER THE MERGE COMMIT EXISTS — and name the SOURCE of every git restore.** A baseline is a committed artifact; a mid-merge index is transient state, and regenerating one from the other bakes the merge into the tree. During an unresolved merge `git ls-files` emits a conflicted path once per STAGE, so a whole-repo scanner counts that file three times and the drift it reports is arithmetic, not content: measured, [guard-vacuity-floor.test.sh](../../../../scripts/guard-vacuity-floor.test.sh) recorded 18 sites for a file with 6 — exactly 6 x 3 — and the commit message then explained the delta as "exactly the merged union", which was false in both directions (the union added ZERO sites). The sibling trap in the same recovery: `git checkout -- <file>` restores from the **INDEX**, so on a path you already `git add`-ed it is a no-op that looks like an undo — the edit survives and the absence of an error reads as success. Name the source (`git restore --source=HEAD --staged --worktree`) and verify by grepping for the thing you meant to remove. **Why:** #8539/PR #8560 — the review that existed to find guards narrower than their names shipped a baseline recording a state no tree ever had, into the commit fixing that class; CI caught it, and the local reproduction of that CI failure returned rc=4 REFUSED and had measured nothing. See `knowledge-base/project/learnings/2026-09-23-the-prose-stated-the-property-and-the-predicate-checked-a-subset.md`. **A GUARD RUN WITHOUT THE ARGUMENT THAT BOUNDS IT REPORTS A VERDICT ABOUT THE WRONG POPULATION — and it reads as reassuring in both directions.** Sibling to the rule above: that one is about which guards you SELECT, this one about how you INVOKE the ones you did. Two shapes, one root. (i) An anti-vacuity floor left below the count it now measures is pure slack, and slack in a floor is attack budget, not padding — the gap is exactly how many assertions can be deleted before the one guard that detects truncation notices, so raise the floor in the SAME edit that adds the row, never in a later tidy-up. (ii) A baselined linter invoked without `--baseline` re-reports its entire baseline as new findings; read the runner's own invocation (`grep run_suite scripts/test-all.sh`) rather than the script's name, because the bare form fails LOUD and wastes a triage round, while its mirror — a `--baseline` that silently absorbs a real regression — fails quiet. **Why:** #8386 shipped a stale floor twice in one session (`MIN_CASES=44` while 49 cases ran, then 49 while 53 ran — each raised only after a review round noticed), and `lint-shell-capture-exit.py` run bare reported "201 NEW finding(s) across 60 file(s)" against a tree whose real count was 0. See `knowledge-base/project/learnings/2026-09-20-my-probe-graded-itself-against-a-clock-its-grader-never-read.md`. **"THE DOCUMENTED API IS THE ONLY WRITE PATH" IS AN ASSUMPTION, NOT A FINDING — AND A HAZARD IS SETTLED BY A REVERSIBLE EXPERIMENT, NOT AN ARGUMENT.** Before declaring an operator step because a control-plane credential is dead, ask what OBJECT is being changed and enumerate every write path that reaches it — not just the API the ticket names. Then, when the automated path carries a lockout risk, design a throwaway probe that answers it in seconds instead of reasoning from documentation. **Why:** #7966 — both stored `SUPABASE_PAT`s returned 401, and I concluded the credential rotation was blocked on minting a new PAT; the operator's one-line question, not my analysis, surfaced that the object was a POSTGRES ROLE and that `ALTER ROLE postgres WITH PASSWORD` over the pooler connection already held needs no PAT at all. The hazard (Supavisor caching a stale upstream credential would strand the ONLY reachable path into the database, the direct host being IPv6-only) was refuted by creating a throwaway role and watching the pooler authenticate a principal it had never seen. See `knowledge-base/project/learnings/2026-09-10-every-assertion-i-wrote-to-prove-the-fix-could-be-satisfied-while-the-defect-was-live.md`. **A DATED record is APPEND-ONLY.** When a plan's sweep touches a probe table, ledger row, dated addendum or post-mortem, correct it by APPENDING a new reading/section that cites the old one — never by editing the old one's body or substituting a cell. Editing in place is what turns a correction into destroyed evidence, and the destroyed datum is disproportionately the one that supported your own claim. Use `## Addendum — YYYY-MM-DD (#N)` or `> **Superseded YYYY-MM-DD (#N):**`, and put the record in the ADR that OWNS the element rather than the one you happened to be reading. **Why:** #7309 — a repin overwrote ADR-143's dated `cx23 = YES — in stock` cell, then asserted "Both read NO here" four lines above it; that deleted `YES` was the only in-repo evidence for the PR's own headline claim, and restoring it made the argument stronger than the one that replaced it. See `knowledge-base/project/learnings/2026-08-06-i-deleted-the-measurement-that-was-my-own-evidence.md`. **BEFORE FIXING A DEFECT CLASS, GREP THE LEARNINGS FOR IT — AND IF IT RECURRED, THE FINDING IS THE PROPAGATION FAILURE, NOT THE DEFECT.** When the fix is a helper, the durable unit is the IMPORT, not the helper and not the write-up: a helper that must be re-derived per file will eventually be re-derived wrongly, and the wrong copy is disproportionately the one that does damage. Strip by PREFIX, never by a hand-listed set of names — a name list is a claim about which values the tool honours, and it is wrong the moment the tool adds one. **Why:** #7822 — a fixture spreading a raw `process.env` into `git commit` under lefthook committed onto the caller's live branch and CONSUMED an in-flight commit (`GIT_DIR` beats `cwd`, and beats `git -C` too). The identical mechanism was already documented five months earlier in the same directory (#1454), WITH two correct working copies in the tree; neither was importable, so neither propagated. The first fix hardcoded six `GIT_*` names — exactly what the prior learning's Prevention section said not to do, unread until after it was committed. Second harm: a case asserting "this directory is NOT a repository" inverts under the inherited variable and proves nothing while staying green. See `knowledge-base/project/learnings/2026-09-04-a-learning-two-working-copies-and-it-still-got-re-derived-wrong.md`. **A YAML `run: |` BLOCK APPLIES NO ESCAPE PROCESSING — VERIFY THE LINE AS THE RUNTIME WILL RECEIVE IT, NOT AS YOU WROTE IT.** A literal block scalar hands the command its bytes verbatim, so a doubled backslash reaches `sed` as a LITERAL backslash: `\\(` is not a capture group in BRE, and the expression silently matches nothing. Nothing rejects it — the step exits 0, the variable is empty, and every condition downstream of it goes false. The same block has two more traps: no line inside it may begin at column 0 (a heredoc terminator or a wrapped quote there ends the block), and a `templatefile()`-rendered one needs `$${…}` for braced shell expansions. So never grade one of these edits by reading it: parse the YAML, extract the command, and run it against a fixture whose correct answer you already know. **Why:** #7500 — a fix hardening `NIC_ALARM_VERDICT` against injection doubled the backslashes in its own anchored `sed`, so BOTH verdicts extracted empty on every run and all four filing conditions went false: the alarm would have filed nothing on any verdict. That is the #7242 "dark on exactly the verdicts it exists to raise" defect, reintroduced by the commit fixing a different defect in the same file, and it was caught by a reviewer re-reading the uncommitted tree rather than by any suite. See `knowledge-base/project/learnings/2026-09-08-every-field-my-alarm-trusted-came-from-the-region-it-did-not-trust.md`. # Work Plan Execution Command Execute a work plan efficiently while maintaining quality and finishing features. ## Introduction This command takes a work document (plan, specification, or todo file) and executes it systematically. The focus is on **shipping complete features** by understanding requirements quickly, following existing patterns, and maintaining quality throughout. ## Headless Mode Detection If `$ARGUMENTS` contains `--headless`, set `HEADLESS_MODE=true`. Strip `--headless` from `$ARGUMENTS` before processing the remainder as a plan path. Pipeline mode (file path detection) already covers all prompt bypasses for work's own prompts — `--headless` is only needed for forwarding to child skills in Phase 4. Strip `--max-<dim> N` args for `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" init` (merge-safe). **Pipeline tally (#9403):** `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" init` **here, at skill start** — before Phase-0.5 check 9's specialist auto-invokes and every tier spawn; `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" gate agent_rounds <N>` before each spawn batch (`<N>` = width), `bash "${CLAUDE_PLUGIN_ROOT}/scripts/pipeline-tally.sh" incr agent_rounds <N>` after, `show` at checkpoints. `STOP` → append `status: budget-capped` + `budget-capped: agent_rounds=<n>/<cap>` (from `show`) to `knowledge-base/project/specs/<feature>/session-state.md` and exit. `WARN`/`UNKNOWN` continue. ## Input Document <input_document> #$ARGUMENTS </input_document> <decision_gate>