dw-sdlc 0.18.0 → 0.20.0

package/README.md

@@ -1,9 +1,10 @@
 # dw-sdlc
 
-The Gate and the agentic config of a repository. `.ai/agentic.config.json` declares how a repository
-works for an agent: its package manager, protected branches, env-file policy, commit convention, the
-Gate and who merges a pull request. The package ships the `dw-sdlc` bin that runs on that file, its JSON Schema, and the
-resolver of its layers.
+The bin and the config behind the [dw-sdlc](https://github.com/dominikwozniak/dw-sdlc) Claude Code plugins.
+`.ai/agentic.config.json` declares how a repository works for an agent: its package manager, protected
+branches, env-file policy, commit convention, the Gate and who merges a pull request. The package ships
+the `dw-sdlc` bin that runs on that file, the file's JSON Schema and the resolver of its layers. The Gate
+and the Ship script work in any repository, with or without the plugins.
 
 ## Install
 
@@ -13,17 +14,17 @@ Node 24 or later.
 pnpm add -D dw-sdlc
 ```
 
+Every release goes to npm from GitHub Actions by trusted publishing, and every version after 0.17.0
+carries provenance too. Trust evidence never drops from one version to the next, so a repository on
+pnpm's `trustPolicy: no-downgrade` takes each release. Dependabot offers one after the seven days of
+`minimumReleaseAge`; a repository that cannot wait names `dw-sdlc` in `minimumReleaseAgeExclude` under
+its own rule for exclusions.
+
 ## The Gate
 
-`dw-sdlc gate` runs the Steps under `gate.steps` in order from the repository root, then every Check
-under `gate.checks`. It prints one line per Step and per Check, and the last 50 lines of a command
-that fails; `--verbose` streams every command's output instead. A Step that creates, changes or
-deletes a file git tracks or would track fails the Gate as Drift, unless `gate.drift` is `"allow"`.
-It exits 0 when everything passes, 1 when a Step or a Check fails or a Step drifts, and 2 when the
-Gate cannot run. `--json` prints the result as one document. `--cache` skips the run when the
-working tree and the resolved Gate match the last green run in that checkout, so a pre-push hook
-costs nothing on an unchanged tree. `dw-sdlc check <name>` runs one Check alone, with the same
-lines, exit codes and document.
+`dw-sdlc gate` proves a change. It runs the Steps under `gate.steps`, the repository's own commands, in
+order from the repository root, stopping at the first that fails. Then it runs every Check under
+`gate.checks`, a named rule the package ships, none stopping the next.
 
 ```json
 {
@@ -35,90 +36,113 @@ lines, exit codes and document.
 }
 ```
 
-A Step is a command string, or `{ "command": "…", "hint": "…" }`; a `gate.checks.run` entry takes a
-`hint` beside `name` and `command`. When the Step or script fails, the Gate prints `hint: <text>` under
-its failure line, and `--json` carries `hint` on every Step and Check, `null` where there is none.
-
 ```json
 { "scripts": { "check": "dw-sdlc gate" } }
 ```
 
-Under `gate.checks`, a Check the package ships is `true` for its defaults or an object of its options.
-`comment-budget` holds each comment block in the JavaScript, TypeScript and shell (`.sh`) files under
-its `roots` to `maxProseLines` lines of prose, 3 by default.
-`disable-directives` fails every Disable directive in a comment that gives no reason: `oxlint-disable*`,
-`eslint-disable*`, `@ts-expect-error`, `@ts-ignore`, `rubocop:disable` and `noqa`. A reason follows `--`
-on the directive's line, follows an `@ts-` directive, or is a comment on the line above.
-
-`skill-sections` holds each README section a skill copies to its source. A part sits between two
-markers, each on its own line, and `dw-sdlc check skill-sections --write` fills an empty pair:
-
-```md
-<!-- README.md#errors -->
-<!-- /README.md#errors -->
-```
-
-The anchor is GitHub's, and the section runs from its heading to the next heading of its level or
-above, in the `README.md` beside the `skills` directory that holds the file, or beside the file
-outside one. The Check fails a part that differs from its section, a part whose anchor names no
-heading of the README, a part from a section no Primitive in `.ai/primitives.json` names among its
-docs, a marker without its pair, and a code fence that never closes above a marker, which hides it.
+It prints one line per Step and per Check, and the last 50 lines of a command that fails. A Step that
+creates, changes or deletes a file git tracks or would track fails as Drift, unless `gate.drift` is
+`"allow"`. A Step written as `{ "command": "…", "hint": "…" }` prints `hint: <text>` under its failure
+line; a `gate.checks.run` entry takes a `hint` beside `name` and `command`.
+
+| flag                | does                                                                              |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `--json`            | prints the result as one document; each Step and Check carries `tail` and `hint`  |
+| `--verbose`         | streams every command's output instead of the tail                                |
+| `--cache`           | skips the run when the tree and the Gate match the last green run in the checkout |
+| `--update-baseline` | after a green run, tightens the baseline of each Ratchet                          |
+
+| exit | means                                                                              |
+| ---- | ---------------------------------------------------------------------------------- |
+| 0    | everything passes                                                                  |
+| 1    | a Step or a Check fails, or a Step drifts                                          |
+| 2    | the Gate cannot run: an invalid config layer, a command not found, a missing input |
+
+`dw-sdlc check <name>` runs one Check alone, with the same lines, exit codes and document.
+
+### Checks
+
+Under `gate.checks`, a Check is `true` for its defaults, an object of its options, or `false`. The
+schema's description of each one names its options and defaults.
+
+| Check                | fails                                                                       | reads first               |
+| -------------------- | --------------------------------------------------------------------------- | ------------------------- |
+| `markdown-refs`      | a relative link or image whose path or heading anchor does not resolve      | nothing                   |
+| `temporal-language`  | a changelog phrase in a durable document, outside code                      | nothing                   |
+| `comment-budget`     | a comment block over 3 lines of prose in JS, TS or shell                    | nothing                   |
+| `disable-directives` | a linter or type-checker disable comment with no reason                     | nothing                   |
+| `agents-map`         | an `AGENTS.md` over budget, missing the Gate command or pointing at nothing | `AGENTS.md`               |
+| `primitives`         | a catalogue entry out of step with the tree, or a file no entry owns        | `.ai/primitives.json`     |
+| `routed-docs`        | a document under `docs/` no Task Router row or Primitive leads to           | the map, the catalogue    |
+| `markdown-budget`    | a markdown file over the byte budget of its glob                            | the files its globs match |
+| `decision-records`   | a decision record misnamed, misnumbered or without a valid status           | a records directory       |
+| `file-size-ratchet`  | a code file over its line limit that the baseline does not allow            | its baseline              |
+| `skill-sections`     | a README section a skill copies that differs from its source                | the catalogue             |
+
+Each Check's options and defaults:
+[its description in the schema](https://github.com/dominikwozniak/dw-sdlc/blob/main/packages/dw-sdlc/config/agentic.config.schema.json).
 
 ## The Ship script
 
-`dw-sdlc pr ship [<n>] [-R owner/name]` reads one pull request through an authenticated `gh` and
-answers the one Action it needs next, as a line or, with `--json`, one document. The exit code says
-whose turn it is: 0 done, 10 the agent's, 20 wait, 30 the dev's, 2 it cannot run. The script
-performs its own Actions: it updates a branch GitHub reports `BEHIND`, marks the head reviewed when the
-Review depth is `off`, marks a draft ready once nothing else holds it back, and squash merges a pull
-request that is green, reviewed and opened by the `gh` account, when the merge is its own. `--dry-run` performs nothing: it answers the first Action the
-script would perform as the dev's. It never deletes a branch; a merged pull request answers with
-the delete command for the dev.
-
-`pr.merge` in the committed `.ai/agentic.config.json` says who merges: the script under `auto`, the
-dev under `ask`, the default. `pr.review` says how closely a head no one has reviewed is read: the
-agent reviews it under `full`, one `sdlc-reviewer` subagent of the plugin does under `light`, and no
-one does under `off`. Under `auto`, the default, the script routes the depth from the changes:
-lockfiles alone `off`; a workflow file, more than 100 changed lines outside lockfiles, or a change
-too large to size `full`; the rest `light`. The local layer may tighten either and never loosen it;
-`--merge` acts as `auto` and `--review full|light|off` sets the depth for one call. A pull request
-the `gh` account did not open is always the dev's to merge.
+`dw-sdlc pr ship [<n>] [-R owner/name]` reads one pull request through an authenticated `gh` and answers
+the one Action it needs next, as a line or, with `--json`, one document. It performs its own Actions:
+it updates a branch GitHub reports `BEHIND`, marks the head reviewed at Review depth `off`, marks a draft
+ready once nothing else holds it back, and squash merges when the merge is its own. It never deletes a
+branch. `--dry-run` performs nothing.
+
+| exit | whose turn         |
+| ---- | ------------------ |
+| 0    | done               |
+| 10   | the agent's: act   |
+| 20   | nobody's yet: wait |
+| 30   | the dev's: park    |
+| 2    | it cannot run      |
+
+| key                | sets                                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------- |
+| `pr.merge`         | who merges: the script under `auto`, the dev under `ask`, the default                          |
+| `pr.review`        | the Review depth of an unreviewed head: `full`, `light`, `off`, or `auto` from the change size |
+| `pr.reviewCommand` | the slash command a `full` Review runs, `/code-review` by default                              |
 
 ```json
 { "pr": { "merge": "auto", "review": "full" } }
 ```
 
-`pr ship` answers `review`, its depth under `details`, until the head carries the commit status
-`dw-sdlc/review`, which `dw-sdlc pr reviewed <n> --head <sha>` posts after a clean review. A Review
-that leaves a Finding open posts it with `--findings`, in state failure, "read, findings open": the
-read mark. After the next push, `details.since` names the last head a Review read, clean or marked,
-so the Review after a fix reads the fix alone. `pr reviewed` posts nothing and exits 2 once a push
-moved the head, so a new head needs a fresh review. Under `off` the script posts that status
-itself, its description saying why, and goes on.
+The local layer may tighten `pr.merge` and `pr.review`, never loosen them. `--merge` acts as `auto` and
+`--review full|light|off` sets the depth for one call. A pull request the `gh` account did not open is
+always the dev's to merge. `light` spawns the `sdlc-reviewer` subagent of the
+[`sdlc` plugin](https://github.com/dominikwozniak/dw-sdlc/blob/main/plugins/sdlc/README.md#the-light-review).
 
-Three Reviews with no success between them end the loop: `pr ship` answers `park review-limit`
-instead of `review`, whose command, `dw-sdlc pr reviewed <n> -R <owner/name> --head <sha> --accept`,
-is the dev's. `--accept` posts the success described "accepted by the dev, findings open"; with
-`--findings` it exits 2. The limit is a constant, not a config key, and `--review <depth>` on a call
-buys one more Review past it.
+`dw-sdlc pr reviewed <n> --head <sha>` pins a Review to the head it read, as the commit status
+`dw-sdlc/review`: clean, Findings open with `--findings`, or accepted by the dev with `--accept`. The
+routing rules, the read mark and the limit of three unclean Reviews are in
+[How the Ship script merges a pull request](https://github.com/dominikwozniak/dw-sdlc/blob/main/docs/overview.md#how-the-ship-script-merges-a-pull-request).
 
 ## Commands
 
-| command            | what it does                                                                               |
-| ------------------ | ------------------------------------------------------------------------------------------ |
-| `gate`             | the Steps of `gate.steps` in order, then every Check under `gate.checks`                   |
-| `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks                  |
-| `primitives`       | the Primitives that own each path, or that a change removes, adds or extends               |
-| `setup`            | this machine's local config layer, the git excludes and the permission rules               |
-| `doctor`           | one PASS / WARN / FAIL line per machine check the guardrails rely on                       |
-| `config`           | the resolved agentic config, or one file validated against the schema                      |
-| `references sync`  | every declared Reference brought to its ref under `references/`                            |
-| `references setup` | the Router, its table and the ignore rules a repository needs to declare References        |
-| `pr ship [<n>]`    | the Action one pull request needs next, performing the script's own                        |
-| `pr reviewed <n>`  | a Review pinned to the head it read, as a commit status: clean, Findings open, or accepted |
-| `recap`            | the facts a Recap rests on and whether the session can be closed                           |
-
-`dw-sdlc <command> --help` gives each one's options.
+| command            | what it does                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------- |
+| `gate`             | the Gate: the Steps of `gate.steps` in order, then every Check under `gate.checks`                |
+| `check <name>`     | one Check of the Gate by its name, without the Steps and the other Checks                         |
+| `primitives`       | the Primitives that own each path, or that a change removes, adds or extends                      |
+| `setup`            | the Gate adopted where asked, this machine's local config layer, git excludes and permissions     |
+| `doctor`           | one PASS / WARN / FAIL line per machine check the `sdlc` plugin relies on                         |
+| `config`           | the resolved agentic config, or one file validated against the schema                             |
+| `references sync`  | every declared Reference, a repository cloned for reading, brought to its ref under `references/` |
+| `references setup` | the Router, its table and the ignore rules a repository needs to declare References               |
+| `pr ship [<n>]`    | the Action one pull request needs next, performing the script's own                               |
+| `pr reviewed <n>`  | a Review pinned to the head it read, as a commit status                                           |
+| `recap`            | the facts a Recap rests on, whether the session can be closed and what could come next            |
+| `sweep`            | Landed branches and clean worktrees removed, and what it keeps named                              |
+| `worker start`     | a Worker started on a Brief in a herdr terminal                                                   |
+| `worker ls`        | the Workers this Lead started and their states                                                    |
+| `worker report`    | a Recap delivered to the Lead, retried while it is blocked                                        |
+| `lead start`       | the next session started as a Lead in a herdr terminal of its own                                 |
+
+`dw-sdlc --help` lists them, and `dw-sdlc <command> --help` gives each one's options and exit codes. A
+Primitive is one unit a repository exposes to an agent, a module, a hook, a script, a config key or a
+skill, listed in `.ai/primitives.json`. A Recap, a Brief, a Worker and a Lead belong to the
+[`sdlc-sessions` plugin](https://github.com/dominikwozniak/dw-sdlc/blob/main/plugins/sdlc-sessions/README.md).
 
 ## The resolver
 
@@ -129,8 +153,8 @@ const { config, problems } = resolveConfig(process.cwd())
 ```
 
 `resolveConfig` merges the committed `.ai/agentic.config.json`, the machine's
-`.ai/agentic.config.local.json` and what it infers from the repository. `problems` names each layer
-that fails the schema; an invalid layer is dropped whole.
+`.ai/agentic.config.local.json` and what it infers from the repository. `problems` names each layer that
+fails the schema; an invalid layer is dropped whole, and the guards then run the strictest set.
 
 ## License
 

package/config/agentic.config.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/plugins/guardrails/config/agentic.config.schema.json",
+  "$id": "https://raw.githubusercontent.com/dominikwozniak/dw-sdlc/main/packages/dw-sdlc/config/agentic.config.schema.json",
   "title": "agentic.config",
-  "description": "How a repository works for an agent. `.ai/agentic.config.json` is committed; `.ai/agentic.config.local.json` overrides it on one machine and may tighten `guardrails` and `pr.merge` but never loosen them. A key neither file sets is inferred: the Node package manager from the lockfile, the `conventional` commit preset, and `gate.command` from the manifest's `check` script. Unknown top-level keys are tolerated so other tool families can share the file; the keys named here refuse unknown children.",
+  "description": "How a repository works for an agent. `.ai/agentic.config.json` is committed; `.ai/agentic.config.local.json` overrides it on one machine and may tighten `guardrails`, `pr.merge` and `pr.review` but never loosen them. A key neither file sets is inferred: the Node package manager from the lockfile and `gate.command` from the manifest's `check` script. Unknown top-level keys are tolerated so other tool families can share the file; the keys named here refuse unknown children.",
   "type": "object",
   "properties": {
     "$schema": {
@@ -92,7 +92,7 @@
       "type": "object",
       "properties": {
         "convention": {
-          "description": "The subject preset `pattern` falls back to. `ticket-key`: `[KEY-123] type: subject`, the tracker's key in brackets before a type from a fixed list. `conventional`: Conventional Commits; inferred when no layer sets either.",
+          "description": "The subject preset `pattern` falls back to. `ticket-key`: `[KEY-123] type: subject`, the tracker's key in brackets before a type from a fixed list. `conventional`: Conventional Commits. Never inferred: with no layer setting this or `pattern`, the subject goes unchecked.",
           "enum": ["ticket-key", "conventional"]
         },
         "pattern": {

package/dist/agentic-config.d.ts

@@ -125,8 +125,8 @@ export type ResolvedConfig = {
     };
     guardrails: Guardrails;
     commit: {
-        convention: CommitConvention;
-        pattern: string;
+        convention?: CommitConvention;
+        pattern?: string;
         trailer?: string;
     };
     gate: Gate;
@@ -136,14 +136,6 @@ export type ResolvedConfig = {
         setup: string[];
     };
 };
-/** The layers merged, before `commit.pattern` falls back to the preset its convention names. */
-type Merged = Omit<ResolvedConfig, "commit"> & {
-    commit: {
-        convention: CommitConvention;
-        pattern?: string;
-        trailer?: string;
-    };
-};
 export type Problem = {
     file: string;
     path: string;
@@ -210,13 +202,12 @@ export declare function repositoryRoot(dir: string): string;
 export declare function mainCheckout(root: string): string | undefined;
 /**
  * The bottom layer: the package manager the lockfile implies, the Gate command the manifest's `check`
- * script implies, plus the defaults every key falls back to. `commit.pattern` is left to
- * `resolveConfig`, which fills it from the convention when no layer sets one.
+ * script implies, plus the defaults every key falls back to. No commit convention: only a file sets
+ * one, and `resolveConfig` fills `commit.pattern` from it when no layer sets a pattern.
  */
-export declare function inferConfig(root: string): Merged;
+export declare function inferConfig(root: string): ResolvedConfig;
 /**
  * Local over committed over inferred, for the repository at `root`. A linked worktree reads a layer it
  * lacks from its main checkout, where a repository that keeps `.ai/` out of git has the only copy.
  */
 export declare function resolveConfig(root: string): Resolution;
-export {};

package/dist/agentic-config.js

@@ -207,8 +207,8 @@ function inferGate(root) {
 }
 /**
  * The bottom layer: the package manager the lockfile implies, the Gate command the manifest's `check`
- * script implies, plus the defaults every key falls back to. `commit.pattern` is left to
- * `resolveConfig`, which fills it from the convention when no layer sets one.
+ * script implies, plus the defaults every key falls back to. No commit convention: only a file sets
+ * one, and `resolveConfig` fills `commit.pattern` from it when no layer sets a pattern.
  */
 export function inferConfig(root) {
     return {
@@ -216,7 +216,7 @@ export function inferConfig(root) {
         baseBranch: "auto",
         packageManagers: inferPackageManagers(root),
         guardrails: cloneGuardrails(DEFAULT_GUARDRAILS),
-        commit: { convention: "conventional" },
+        commit: {},
         gate: inferGate(root),
         pr: { ...DEFAULT_PR },
         worker: { ...DEFAULT_WORKER },
@@ -307,10 +307,16 @@ function prLoosenings(base, local) {
         return [{ file: LOCAL_FILE, path: `pr.${key}`, message }];
     });
 }
-/** `commit.pattern` from the convention's preset when no layer set one; a set pattern wins. */
+/**
+ * `commit.pattern` from the convention's preset when no layer set one; a set pattern wins. Neither
+ * set, no pattern: the subject goes unchecked.
+ */
 function finalize(merged) {
-    const pattern = merged.commit.pattern ?? COMMIT_PATTERNS[merged.commit.convention];
-    return { ...merged, commit: { ...merged.commit, pattern } };
+    const { convention, pattern } = merged.commit;
+    if (pattern !== undefined || convention === undefined) {
+        return merged;
+    }
+    return { ...merged, commit: { ...merged.commit, pattern: COMMIT_PATTERNS[convention] } };
 }
 /**
  * Local over committed over inferred, for the repository at `root`. A linked worktree reads a layer it

package/dist/commands/doctor.d.ts

@@ -19,7 +19,7 @@ export type Probe = {
 export type RepositoryConfig = {
     config: {
         commit: {
-            convention: string;
+            convention?: string;
         };
     };
     problems: string[];

package/dist/commands/doctor.js

@@ -47,7 +47,11 @@ function checkJq(probe) {
     if (status === 0) {
         return { name: "jq", level: "PASS", detail: stdout.trim() };
     }
-    return { name: "jq", level: "FAIL", detail: "missing: every guard is silent without it. brew install jq" };
+    return {
+        name: "jq",
+        level: "FAIL",
+        detail: "missing: every guard is silent without it. https://jqlang.org/download/"
+    };
 }
 /** Every hook command string in a settings file, whatever the event and matcher. */
 function hookCommands(settings) {
@@ -219,7 +223,7 @@ function checkConfig(config, root) {
     return {
         name: "config",
         level: "PASS",
-        detail: `commit ${config.config.commit.convention}${borrowed.join("")}`
+        detail: `commit ${config.config.commit.convention ?? "unchecked"}${borrowed.join("")}`
     };
 }
 export function diagnose(inputs) {

package/dist/commands/setup.d.ts

@@ -27,8 +27,8 @@ export type SetupOptions = {
 export declare const summary = "adopt the Gate where asked, and write this machine's local config layer, the git excludes and the permission rules";
 /**
  * What the machine's layer points `$schema` at: the marketplace clone's schema as a `file://` URL, as an
- * editor cannot fetch the `$id` from a private repository and the clone, unlike the install cache, keeps
- * its path across plugin updates. Without a registered clone holding the schema, the `$id`.
+ * editor reads it offline at the installed version and the clone, unlike the install cache, keeps its
+ * path across plugin updates. Without a registered clone holding the schema, the `$id`.
  */
 export declare function schemaReference(claudeDir: string): string;
 export declare function setup(options: SetupOptions): Step[];

package/dist/commands/setup.js

@@ -69,8 +69,8 @@ function committedConfig(root) {
 }
 /**
  * What the machine's layer points `$schema` at: the marketplace clone's schema as a `file://` URL, as an
- * editor cannot fetch the `$id` from a private repository and the clone, unlike the install cache, keeps
- * its path across plugin updates. Without a registered clone holding the schema, the `$id`.
+ * editor reads it offline at the installed version and the clone, unlike the install cache, keeps its
+ * path across plugin updates. Without a registered clone holding the schema, the `$id`.
  */
 export function schemaReference(claudeDir) {
     const registry = readJson(join(claudeDir, "plugins", "known_marketplaces.json"));
@@ -168,8 +168,8 @@ function localConfig(root, claudeDir, convention, guardrails, worker) {
     if (worker !== undefined) {
         config.worker = worker;
     }
-    // Only one asked for, by `--convention` or the file's pin: inference always gives `conventional`, and
-    // pinning it here would override a convention the repository commits later.
+    // Only one asked for, by `--convention` or the file's pin: pinning one here would override a
+    // convention the repository commits later.
     if (convention !== undefined) {
         config.commit = { convention };
     }

package/dist/commands/sweep.js

@@ -9,7 +9,7 @@ import { isCommitLanded, isLanded } from "../landed.js";
 import { shellLine } from "../pr/decide.js";
 import { CannotRun } from "../pr/read.js";
 import { byHand, holdersOf, keptIn, lockAfterStop, lockHolder, outsideWorktrees, readTerminals, removeTerminal, stopsOf, sweepingTerminal, whyHeld } from "../sweep-terminals.js";
-import { dirtyFiles, must, pausedOperation, worktreesOf } from "../sweep-trees.js";
+import { branchesOf, dirtyFiles, pausedOperation, switchOff, worktreesOf } from "../sweep-trees.js";
 import { asked, git } from "../working-tree.js";
 import { lockVerdict } from "../worktree-lock.js";
 export const summary = "removes Landed branches and clean worktrees whose work has landed, names what it keeps";
@@ -26,7 +26,8 @@ config, else the branch origin/HEAD names) and removes, never forcing:
 It keeps, and names with the reason and the command to run yourself:
   a worktree that fails the set: the files that hold it with the forced removal, the paused operation, the
   lock's reason with git worktree unlock, a live Claude Code lock named by its pid, a HEAD that is not Landed;
-  the default branch, the base branch, a protected branch and a branch a kept worktree has checked out;
+  the default branch, the base branch, a protected branch and a branch a kept worktree has checked out; a
+  Landed branch the main checkout has checked out, clean and with nothing paused, with git switch to the base;
   a branch whose work is on no commit of the base, with the forced delete.
 It never changes anything on a remote: the fetch only writes remote-tracking refs. A removal git refuses is
 kept with git's words, and the sweep goes on.
@@ -91,11 +92,6 @@ function baseOf(root, head) {
     }
     return { name, ref };
 }
-function branchesOf(root) {
-    return must(root, ["for-each-ref", "--format=%(refname:lstrip=2)", "refs/heads"])
-        .split("\n")
-        .filter((name) => name !== "");
-}
 /** Why the worktree stays, with the dev's command when there is one, or null when its whole set passes. */
 function whyTreeStays(root, baseRef, tree, lock, holders) {
     const { path } = tree;
@@ -194,8 +190,9 @@ function judge(root, terminals) {
         }
         judged.add(name);
         const why = stays(name, footing);
+        const off = why?.dev === true && held.get(name) === checkout.path ? switchOff(root, base, name) : null;
         if (why !== null) {
-            kept.push({ kind: "branch", name, ...why });
+            kept.push({ kind: "branch", name, ...why, ...off });
         }
         else if (isLanded(root, base.ref, name)) {
             removed.push({ kind: "branch", name, reason: `Landed on ${baseName}` });

package/dist/doctor-plugins.js

@@ -146,7 +146,7 @@ export function checkSessions(probe, claude) {
     if (entry === undefined) {
         const detail = list === undefined
             ? "claude plugin list did not answer"
-            : `no ${SESSIONS_ID}, so no /sdlc-recap, /sdlc-brief or /sdlc-delegate. claude plugin install ${SESSIONS_ID} --scope user`;
+            : `no ${SESSIONS_ID}, so no /sdlc-recap, /sdlc-kickoff or /sdlc-delegate. claude plugin install ${SESSIONS_ID} --scope user`;
         return { name, level: "INFO", detail };
     }
     const version = typeof entry.version === "string" ? entry.version : "?";

package/dist/pr/decide.js

@@ -232,8 +232,10 @@ const ROWS = [
                 return { ...head, action: "mark-reviewed", actor: "script", details: after };
             }
             const { depth, source } = depthOf(pr, policy);
-            // The dev's own depth buys one Review past the limit; a Review under off needs none.
-            if (depth !== "off" && source !== "flag" && pr.marks.count >= REVIEW_LIMIT) {
+            // The dev's own depth buys one Review past the limit, and only one: the flag rides on every
+            // later call. A Review under off needs none.
+            const limit = source === "flag" ? REVIEW_LIMIT + 1 : REVIEW_LIMIT;
+            if (depth !== "off" && pr.marks.count >= limit) {
                 return reviewLimit(pr);
             }
             const byScript = depth === "off";
@@ -246,7 +248,8 @@ const ROWS = [
                     source,
                     // The agent may raise a routed depth to full, so auto names the command at any depth.
                     ...(depth === "full" || source === "auto" ? { reviewCommand: policy.reviewCommand } : {}),
-                    ...after
+                    ...after,
+                    ...(pr.scope === null ? {} : { paths: pr.scope })
                 }
             };
         }

package/dist/pr/read.js

@@ -205,16 +205,47 @@ function withCarried(pr) {
     return { ...pr, carried: sameChanges(ownChanges(pr, last.commit), ownChanges(pr, pr.head)) };
 }
 /**
- * `pr` and, when `sized` and a Review awaits a head that carries none, the files the Review would read:
- * the compare from the last commit a Review read, else from the base, to the head.
+ * The files whose own change differs between `from` and the head of `pr`, a rename under both names:
+ * what a fix touched, without the files a merge of the base brought in. Null when a compare cannot show
+ * the own changes whole.
+ */
+function ownScope(pr, from) {
+    const before = ownChanges(pr, from);
+    const after = ownChanges(pr, pr.head);
+    if (before === null || after === null) {
+        return null;
+    }
+    const moved = [
+        ...after.filter((change) => !before.includes(change)),
+        ...before.filter((change) => !after.includes(change))
+    ];
+    const names = moved.flatMap((change) => {
+        const [path, , previous] = JSON.parse(change);
+        return previous === null ? [path] : [path, previous];
+    });
+    return [...new Set(names)].toSorted();
+}
+/**
+ * `pr` and, when a Review awaits a head that carries none, its `scope` after a merge of the base, and
+ * when `sized`, the files the Review would read: the compare from the last commit a Review read, else
+ * from the base, to the head, kept to the scope when there is one.
  */
 function withChanged(pr, sized) {
-    if (!sized || pr.carried || pr.state !== "OPEN" || !awaitsReview(pr)) {
-        return { ...pr, changed: null };
+    if (pr.carried || pr.state !== "OPEN" || !awaitsReview(pr)) {
+        return { ...pr, changed: null, scope: null };
+    }
+    const scope = pr.lastRead?.merges === true ? ownScope(pr, pr.lastRead.commit) : null;
+    if (!sized) {
+        return { ...pr, changed: null, scope };
     }
     const from = pr.lastRead?.commit ?? pr.baseOid;
     const reply = compared(pr, from, pr.head, `the compare of ${from.slice(0, 7)}...${pr.head.slice(0, 7)}`);
-    return { ...pr, changed: parseOrCannotRun(() => changedOf(reply)) };
+    const changed = parseOrCannotRun(() => changedOf(reply));
+    if (scope === null || changed === "unsized") {
+        return { ...pr, changed, scope };
+    }
+    const within = changed.filter(({ path, previous }) => scope.includes(path) || (previous !== null && scope.includes(previous)));
+    return { ...pr, changed: within, scope };
 }
 /** The state of pull request `number` of `repo`, from one GraphQL request and the compares a Review needs. */
 function query({ repo, number }, sized) {

package/dist/pr/state.d.ts

@@ -88,6 +88,11 @@ export type PrState = {
      * auto` to route on: `unsized` when the compare cannot list them all, null when not read.
      */
     changed: ChangedFile[] | "unsized" | null;
+    /**
+     * The files whose own change moved since `lastRead`, when a merge of the base came after it: the files
+     * a fix touched, the base's own left out. Null with no such merge, or when a compare cannot show them.
+     */
+    scope: string[] | null;
 };
 /**
  * A file a Review would read: its name, its name before a rename, and the lines it adds and removes,
@@ -106,6 +111,7 @@ export type LastRead = {
     commit: string;
     clean: boolean;
     mergesOnly: boolean;
+    merges: boolean;
 };
 /**
  * The Reviews that left a Finding open since the last review success, a success under off and the dev's
@@ -144,5 +150,5 @@ export declare function parseView(reply: string): {
 /** The default branch of the repository whose `gh repo view --json defaultBranchRef` printed `reply`. */
 export declare function parseDefaultBranch(reply: string): string;
 /** The state of the pull request in `reply`, the text `gh api graphql` printed for QUERY on `repo`. */
-export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed">;
+export declare function parsePr(reply: string, repo: string): Omit<PrState, "carried" | "changed" | "scope">;
 export {};

package/dist/pr/state.js

@@ -253,7 +253,12 @@ function lastReadOf(history, head) {
     if (last === undefined) {
         return null;
     }
-    return { commit: last.oid, clean: last.read === "clean", mergesOnly: mergesOnlyAfter(index) };
+    return {
+        commit: last.oid,
+        clean: last.read === "clean",
+        mergesOnly: mergesOnlyAfter(index),
+        merges: commits.slice(index + 1).some(({ merge }) => merge)
+    };
 }
 /**
  * Whether a non-merge commit follows `commit` in the history, oldest first, as `lastReadOf` judges a read

package/dist/sweep-trees.d.ts

@@ -1,5 +1,7 @@
 /** `git <args>` at `root`, or a stop naming its problem. */
 export declare function must(root: string, args: string[]): string;
+/** The local branches of the repository at `root`. */
+export declare function branchesOf(root: string): string[];
 export type Tree = {
     path: string;
     head: string;
@@ -15,3 +17,11 @@ export declare function dirtyFiles(path: string): string[] | {
 };
 /** The operation paused in the worktree at `path`: its git dir holds the state git resumes it from. */
 export declare function pausedOperation(path: string): string | undefined;
+/** The dev's way off `branch`, checked out in the main checkout at `root`: null until it is Landed and nothing there could be lost. */
+export declare function switchOff(root: string, base: {
+    name: string;
+    ref: string;
+}, branch: string): {
+    reason: string;
+    command: string;
+} | null;

package/dist/sweep-trees.js

@@ -1,9 +1,11 @@
-// What a Sweep reads of a repository's linked worktrees: where each lies, what it has checked out, its lock,
-// the files that hold it and the operation paused in it.
+// What a Sweep reads of a repository's branches and worktrees: where each worktree lies, what it has checked
+// out, its lock, the files that hold it and the operation paused in it, and the way off the main checkout's.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { exec } from "./exec.js";
 import { repositoryFreeEnv } from "./git-env.js";
+import { isLanded } from "./landed.js";
+import { shellLine } from "./pr/decide.js";
 import { CannotRun } from "./pr/read.js";
 import { asked, git } from "./working-tree.js";
 /** `git <args>` at `root`, or a stop naming its problem. */
@@ -14,6 +16,12 @@ export function must(root, args) {
     }
     return result.out;
 }
+/** The local branches of the repository at `root`. */
+export function branchesOf(root) {
+    return must(root, ["for-each-ref", "--format=%(refname:lstrip=2)", "refs/heads"])
+        .split("\n")
+        .filter((name) => name !== "");
+}
 /** Every worktree of the repository, the main checkout first. */
 export function worktreesOf(root) {
     const trees = [];
@@ -70,3 +78,15 @@ export function pausedOperation(path) {
     const dir = asked(path, ["rev-parse", "--absolute-git-dir"]);
     return dir === undefined ? undefined : OPERATIONS.find(([file]) => existsSync(join(dir, file)))?.[1];
 }
+/** The dev's way off `branch`, checked out in the main checkout at `root`: null until it is Landed and nothing there could be lost. */
+export function switchOff(root, base, branch) {
+    const files = dirtyFiles(root);
+    if ("error" in files ||
+        files.length > 0 ||
+        pausedOperation(root) !== undefined ||
+        !isLanded(root, base.ref, branch)) {
+        return null;
+    }
+    const command = `${shellLine(["git", "switch", base.name])} && ${shellLine(["git", "pull", "--rebase"])}`;
+    return { reason: `checked out in the main checkout at ${root}, Landed on origin/${base.name}`, command };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dw-sdlc",
-  "version": "0.18.0",
-  "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, the Sync and setup of References, and the Ship script that drives a pull request to merged; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
+  "version": "0.20.0",
+  "description": "The Gate and the agentic config behind the sdlc Claude Code plugin: a bin with the Gate and its Checks, the setup, the doctor, the Sync of References, the Ship script that drives a pull request to merged, the Sweep, and Lead and Worker sessions in herdr; the resolver of a repository's .ai/agentic.config.json layers and its JSON Schema.",
   "license": "MIT",
   "repository": {
     "type": "git",