Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

fix(core): preserve resume guidance and diagnostics [N19,D1,A6,I1]

Corey Olson8a4996c4f919
diff --git a/docs/api.md b/docs/api.md
index 7d75ac88..5211f519 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -252,7 +252,7 @@ An agent is active while it holds a claim or review, has submitted work still aw
The current release is the roadmap's first milestone with unverified local work; an unplanned item counts as current. A release is the newest tag named like `v1.2.3` or `1.2.3`, dated by its creation, and its landed work is every item first recorded merged after it. A repository with no such tag has no release deadline. The trunk is the primary checkout's branch, or the retained trunk when that checkout is detached.
-The health sentinel runs this read-only scan on `pullboard resume` and every ten minutes while the background view runs. New findings and resolutions arrive as ordinary shouts from `sentinel` to the coordinator and the finding’s owner, with its cause and next step. A continuing episode is not posted again. Ordered engine-42 receipts retain the observed revision; a concurrent board change defers the observation to a later resume instead of publishing stale findings. Health never changes claim state. Set `health.sentinel` to `false` in this repo’s `pullboard.json` or in machine settings to turn automatic scans off. Repeated `health-failure` receipts are visible to `pullboard rigor`, including a recurring work cause with no changed code commit.
+The health sentinel runs this read-only scan on `pullboard sentinel run` and every ten minutes while the background view runs. `pullboard resume` reads the last recorded findings and scan time without starting a scan. New findings and resolutions arrive as ordinary shouts from `sentinel` to the coordinator and the finding’s owner, with its cause and next step. A continuing episode is not posted again. Ordered engine-42 receipts retain the observed revision; a concurrent board change defers the observation to a later scheduled scan instead of publishing stale findings. Health never changes claim state. Set `health.sentinel` to `false` in this repo’s `pullboard.json` or in machine settings to turn automatic scans off. Repeated `health-failure` receipts are visible to `pullboard rigor`, including a recurring work cause with no changed code commit.
`pullboard.json` sets the thresholds under `health`, each a duration like `90m`, `2h` or `1d`: `stuck` (default `1h`), `holds` (default `1d`) and `release` (default `1d`). A value that is not a duration is refused as `BAD_CONFIG`.
diff --git a/docs/formats.md b/docs/formats.md
index 57d3aa3c..184abd9e 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -480,7 +480,7 @@ Migration preserves event rows and adds only schema objects that are missing.
`pullboard.json` may set `affectedTests` to a command prefix that runs selected test files. When it is absent, `submit` runs the configured `gate` in full. When present and the import graph can safely select a subset, Pullboard appends the selected file paths to this prefix; an uncertain selection still runs the full gate. For example, this repository opts in with `"affectedTests": "node bin/run-tests.js"`. Projects using another test framework can leave the setting out and keep their configured gate, such as `npm test`.
-`pullboard.json` may set `worktrees` to `"inside"` or `"beside"`. Fresh `pullboard init` writes `"inside"`, placing new agent worktrees under `.claude/worktrees/<lane>-N`; it also adds `.claude/worktrees/` to `.gitignore` and prints guidance for dot-scanner ignore rules. An omitted setting defaults to `"beside"` to preserve existing sibling paths (`../<repo>-<lane>-N`). `pullboard resume` and `pullboard help worktree` show the active location from the primary checkout's config.
+`pullboard.json` may set `worktrees` to `"inside"` or `"beside"`. Fresh `pullboard init` writes `"inside"`, placing new agent worktrees under `.claude/worktrees/<lane>-N`; it also adds `.claude/worktrees/` to `.gitignore` and prints guidance for dot-scanner ignore rules. An omitted setting defaults to `"beside"` to preserve existing sibling paths (`../<repo>-<lane>-N`). `pullboard resume --diagnostics`, JSON v1 `pullboard resume --json`, and `pullboard help worktree` show the active location from the primary checkout's config.
A project with `"submitGate": "landing"` can also set `"submitInvariants": ["test/guard.test.js"]` to run a small set of project guard files on every submit, even when uncertain selection defers the full suite. The list defaults to empty and requires the project's explicit `affectedTests` runner; no framework or test files are added by default. Submit reads the list and its runner from accepted main, so a candidate cannot remove or replace its required files. Named affected tests and invariants run once per file, with their paths and results in the receipt. Missing invariant files refuse the submit, and subset passes never stamp the full gate. The coordinator still runs the configured full suite at landing.
diff --git a/src/resume-sources.js b/src/resume-sources.js
index 9bd0ac22..13407904 100644
--- a/src/resume-sources.js
+++ b/src/resume-sources.js
@@ -107,5 +107,7 @@ export async function readResumeSources(ctx, board, { compareBranch = true, incl
if (!counts) throw new Refused('NO_POLICY', 'the branch could not be compared with main; run pullboard resume --diagnostics');
behind = Number(counts[1]); ahead = Number(counts[2]);
}
- return { ...await sharedDoctrine(ctx, board, primary, main, includeHeadDoctrine), primary, branch, mainRef: main?.branch, ahead, behind };
+ // Guidance follows Git's listed primary exactly as agentDoctrine does, even when placement cannot be proven.
+ const guidanceRoot = listed[0]?.path;
+ return { ...await sharedDoctrine(ctx, board, guidanceRoot, main, includeHeadDoctrine), primary, branch, mainRef: main?.branch, ahead, behind };
}
diff --git a/test/worktree-start.test.js b/test/worktree-start.test.js
index c315eeab..86293ef7 100644
--- a/test/worktree-start.test.js
+++ b/test/worktree-start.test.js
@@ -148,7 +148,7 @@ test('a new worktree is created inside the repository [I1,I2]', () => {
'a linked checkout with a separate git dir resolves its registered main root');
const registryPath = join(box.env.PULLBOARD_HOME, 'projects.json');
const registryBytes = readFileSync(registryPath);
- const linkedResume = box.run(linkedPath, 'resume');
+ const linkedResume = box.run(linkedPath, 'resume', '--diagnostics');
assert.match(linkedResume.out, /New agent worktrees: .*\.claude\/worktrees\/<lane>-N/u);
assert.deepEqual(readFileSync(registryPath), registryBytes, 'resume reads the registry without refreshing it');
const linkedHelp = box.run(linkedPath, 'help', 'worktree');