tumwater 0.1.2 → 0.2.0

package/dist/src/tick/stage-check.js

@@ -1,7 +1,8 @@
-/** The landing gate's deterministic checks, run BEFORE a changed tick commits.
+// vocabulary: plain
+/** The merge gate's deterministic checks, run BEFORE a changed tick commits.
  *
- * The gate runs `backlogStructureReason` and `falseFixReason` at landing time, by which point
- * the author's session is over: a finding costs a queue slot, a vet, and a rejection that
+ * The gate runs `backlogStructureReason` and `falseFixReason` at merge time, by which point
+ * the author's session is over: a finding costs a queue slot, a verification, and a rejection that
  * discards the work (13 phantom-fix rejections between 2026-09-23 and 2026-10-02). Both checks
  * read the worktree and the change's merge-base, so the same questions can be asked at staging
  * time, while the authoring session can still be continued for one fix-up turn. This module
@@ -17,15 +18,32 @@
  * files whose final newline the change removed. These stage the change (`git add -A`) to read
  * the index with git only, then restore the index to HEAD before returning: staging is a read
  * aid for the checks, not a change to the tick's state. A git hiccup yields no finding rather
- * than failing the tick. */
+ * than failing the tick. Unlike the backlog checks above, the gate does not run these: they are
+ * heuristics for what a reviewer tends to reject, so neither path check looks inside record
+ * prose (isRecordProse), where an old or not-yet-created path is correct as written.
+ *
+ * `planDependencyFinding` is staging-only: it is not part of the review gate or the in-lock
+ * merge re-check, because `tumwater doctor`'s plan-dependency warning is the backstop for
+ * anything that gets past the fix-up turn. `waitingNoteFinding` is staging-only and bugfix-only
+ * for the same reason: it nudges a bugfix run that left a Progress note without the hold. */
+import path from "node:path";
 import { changedFiles } from "../git/git-diff.js";
-import { conflictMarkerReason } from "../landing/landing-git.js";
+import { conflictMarkerReason } from "../merge/merge-git.js";
 import { isExemptDiff } from "../review/exemptions.js";
 import { backlogStructureReason } from "../backlog/backlog-structure.js";
+import { protectedEditReason } from "../review/protected-edits.js";
+import { secretLeakReason } from "../review/secret-leaks.js";
 import { falseFixReason } from "../verdict/fix-claim.js";
-import { changeBaseRev } from "../git/git.js";
+import { changeBaseRev, fileContentAt } from "../git/git.js";
+import { readTextOrNull } from "../files/files.js";
+import { BACKLOG_FILES, finishedArchiveOf, parseEntryDetails } from "../backlog/backlog-md.js";
+import { entryKey, planDependencyProblems, refusalNote, waitingNote } from "../backlog/backlog-eligibility.js";
+import { baseRoleOf } from "../roles/loop-ids.js";
+import { WAITING_FOR_FAILURE_NOTE } from "../roles/role-guidance.js";
 import { gitTry } from "../git/git-run.js";
 import { moreSuffix } from "../text/phrases.js";
+/** Where finished plans are archived (plans/backlog-archive.md). */
+const PLANS_ARCHIVE = finishedArchiveOf("PLANS.md").archive;
 /** How many `file:line` hits a single stale-reference finding lists before it stops. */
 const MAX_STALE_HITS = 10;
 /** How many renamed/deleted paths each stale-reference finding reports before stopping — the
@@ -41,6 +59,17 @@ const MAX_NEWLINE_FILES = 10;
 function diffPlusPath(line) {
     return line.slice(4).replace(/^b\//, "");
 }
+/** True for record prose: a backlog file (BACKLOG_FILES: PLANS.md, BUGS.md, QUESTIONS.md and the
+ * finished-entry archives) or a markdown design doc under `plans/`. They record history and
+ * describe planned work, so a path there is correct as written even when it is absent from the
+ * tree: a finished entry names a file as it was, and a plan names the file it will create or
+ * both sides of the move it describes. Asking a rename to sweep them rewrote "old → new" into
+ * "new → new" and history into the present; that failure took five rejections on
+ * one rename on 2026-10-18 and -19. */
+function isRecordProse(file) {
+    const base = file.slice(file.lastIndexOf("/") + 1);
+    return BACKLOG_FILES.has(base) || (file.startsWith("plans/") && file.endsWith(".md"));
+}
 /** The capped list a finding line appends: at most `max` entries joined by ", ", then
  * `moreSuffix` for the rest. Shared by the missing-path and lost-final-newline findings so both
  * cap and join identically. */
@@ -48,13 +77,78 @@ function cappedList(items, max) {
     const shown = items.slice(0, max);
     return `${shown.join(", ")}${moreSuffix(items.length - shown.length)}`;
 }
-/** The deterministic findings the landing gate would reject this uncommitted change for, or an
- * empty list when it is clean. Checks the worktree at `wt` against `mainBranch`'s merge-base;
- * `exemptPaths` are the config's review-exemption globs that scope the false-fix check.
+/** The finding for the heading `requires` clause problems that `head` (the edited PLANS.md)
+ * adds over `base` (its text at the merge-base), or undefined when it adds none; `archivedTitles`
+ * (PLANS-DONE.md's headings) count as existing headings on both sides. Only new
+ * problems count: one already on main is not this run's fault and stays doctor's to report, so
+ * the author is never asked to fix another run's heading. The most serious new problem is named
+ * — cycle, then dangling, unparsed, then misworded — with a count of the rest. */
+export function planDependencyFinding(head, base, archivedTitles = []) {
+    const problems = (text) => planDependencyProblems(parseEntryDetails(text, "Planned"), [...parseEntryDetails(text, "Done").map((e) => e.title), ...archivedTitles]);
+    const was = problems(base);
+    const now = problems(head);
+    const newCycle = now.cycle !== null && was.cycle === null ? now.cycle : null;
+    const newDangling = now.dangling.filter((d) => !was.dangling.some((b) => b.title === d.title && b.ref === d.ref));
+    const newUnparsed = now.unparsed.filter((t) => !was.unparsed.includes(t));
+    const newMisworded = now.misworded.filter((m) => !was.misworded.some((b) => b.title === m.title && b.ref === m.ref));
+    const total = (newCycle !== null ? 1 : 0) + newDangling.length + newUnparsed.length + newMisworded.length;
+    if (total === 0)
+        return undefined;
+    let first;
+    if (newCycle !== null) {
+        first = `PLANS.md's requires clauses now form a cycle: ${newCycle.join(" → ")} — every part on it stays blocked forever; ` + // vocabulary-ok: PLANS.md heading syntax
+            "edit one heading's `requires … landed` clause to break it"; // vocabulary-ok: PLANS.md heading syntax
+    }
+    else if (newDangling.length > 0) {
+        const d = newDangling[0];
+        first = `PLANS.md plan "${d.title}" requires ${d.ref}, which no PLANS.md heading carries — the claim allocator ` +
+            "ignores the clause and hands the plan out now; fix the series name or part number to match the prerequisite's heading";
+    }
+    else if (newUnparsed.length > 0) {
+        first = `PLANS.md plan "${newUnparsed[0]}" has a \`requires … landed\` clause that names no part the claim allocator can read — ` + // vocabulary-ok: PLANS.md heading syntax
+            "it holds nothing; write each ref as `<Series> i/n` or `part i/n` after a `<Series>, part i/n:` heading prefix";
+    }
+    else {
+        const w = newMisworded[0];
+        first = `PLANS.md plan "${w.title}" names ${w.ref} as a prerequisite without a \`requires … landed\` clause — ` + // vocabulary-ok: PLANS.md heading syntax
+            "the claim allocator ignores that wording and hands the part out now; write it as `requires part i/n landed` — fix it before this change commits"; // vocabulary-ok: PLANS.md heading syntax
+    }
+    return `${first}${moreSuffix(total - 1)}`;
+}
+/** The number of `- **Progress …` lines in an entry body. */
+function progressCount(body) {
+    return body.split("\n").filter((l) => /^-\s+\*\*Progress\b/.test(l.trim())).length;
+}
+/** The finding for a BUGS.md bug that `head` (the edited file) shows with more Progress notes
+ * than `base` (its text at the merge-base) while it stays under `## Open` with neither a Waiting
+ * note nor a Refused note — bugfix's step 2 asks a run that cannot reproduce a bug to write the
+ * Waiting note, and runs that skip it leave the bug open to re-investigation. A newly filed bug
+ * is not a re-investigation. Names the first such bug in file order, with a count of the rest. */
+export function waitingNoteFinding(head, base) {
+    const was = new Map(parseEntryDetails(base, "Open").map((e) => [entryKey(e.title), e.body]));
+    const counting = parseEntryDetails(head, "Open").filter((e) => {
+        const before = was.get(entryKey(e.title));
+        return (before !== undefined &&
+            progressCount(e.body) > progressCount(before) &&
+            waitingNote(e.body) === null &&
+            refusalNote(e.body) === null);
+    });
+    if (counting.length === 0)
+        return undefined;
+    return (`BUGS.md bug "${counting[0].title}" gained a Progress note but stays open with no Waiting for the next ` +
+        `failure note — if this run could not reproduce it, add ${WAITING_FOR_FAILURE_NOTE} as its own line under ` +
+        `the heading so later runs wait for new evidence (bugfix's step 2); if it did reproduce, leave the entry ` +
+        `as it is${moreSuffix(counting.length - 1)}`);
+}
+/** The findings likely to get this uncommitted change rejected at merge, or an empty list when
+ * it is clean: the merge gate's own deterministic checks plus the staging-only heuristics (plan
+ * dependencies, the bugfix Waiting note, path drift). Checks the worktree at `wt` against
+ * `mainBranch`'s merge-base; `exemptPaths` are the config's review-exemption globs that scope
+ * the false-fix check.
  *
  * Never throws: a check that fails yields no finding, so a git hiccup at staging time defers to
  * the gate instead of failing the tick. */
-export async function stageCheckFindings(wt, mainBranch, exemptPaths) {
+export async function stageCheckFindings(wt, mainBranch, exemptPaths, role) {
     const files = await changedFiles(wt).catch(() => null);
     if (files === null || files.length === 0)
         return [];
@@ -62,6 +156,29 @@ export async function stageCheckFindings(wt, mainBranch, exemptPaths) {
     const structure = await backlogStructureReason(wt, mainBranch, files).catch(() => undefined);
     if (structure)
         findings.push(structure);
+    if (files.includes("PLANS.md")) {
+        const head = readTextOrNull(path.join(wt, "PLANS.md")) ?? "";
+        const base = await fileContentAt(wt, await changeBaseRev(wt, mainBranch), "PLANS.md").catch(() => undefined);
+        // Finished plans are archived in PLANS-DONE.md (plans/backlog-archive.md): a requires clause
+        // naming a merged part resolves there, on both sides of the comparison alike.
+        const archived = parseEntryDetails(readTextOrNull(path.join(wt, PLANS_ARCHIVE)) ?? "", "Done").map((e) => e.title);
+        const dependency = base === undefined ? undefined : planDependencyFinding(head, base, archived);
+        if (dependency !== undefined)
+            findings.push(dependency);
+    }
+    if (baseRoleOf(role) === "bugfix" && files.includes("BUGS.md")) {
+        const head = readTextOrNull(path.join(wt, "BUGS.md")) ?? "";
+        const base = await fileContentAt(wt, await changeBaseRev(wt, mainBranch), "BUGS.md").catch(() => undefined);
+        const waiting = base === undefined ? undefined : waitingNoteFinding(head, base);
+        if (waiting !== undefined)
+            findings.push(waiting);
+    }
+    const protectedReason = await protectedEditReason(wt, mainBranch, files, role).catch(() => undefined);
+    if (protectedReason)
+        findings.push(protectedReason);
+    const secretReason = await secretLeakReason(wt, mainBranch, files).catch(() => undefined);
+    if (secretReason)
+        findings.push(secretReason);
     if (isExemptDiff(files, exemptPaths)) {
         const falseFix = await falseFixReason(wt, mainBranch, files).catch(() => undefined);
         if (falseFix)
@@ -77,11 +194,11 @@ export async function stageCheckFindings(wt, mainBranch, exemptPaths) {
  * (plans/parallel-work-instances.md "Claims", part 4/7): the assigned entry is the instance's
  * one task, so moving another is the same class of mistake `backlogStructureReason` catches
  * and costs one fix-up turn before the change commits. undefined when nothing moved or the
- * claimed entry itself moved — a landed entry is the expected way to release a claim. */
+ * claimed entry itself moved — a merged entry is the expected way to release a claim. */
 export function assignedMovedFinding(claimKey, moved) {
     if (moved.length === 0 || moved.some((m) => m.key === claimKey))
         return undefined;
-    return `this tick is assigned one backlog entry but moved a different one: "${moved[0].title}"`;
+    return `this run is assigned one backlog entry but moved a different one: "${moved[0].title}"`;
 }
 /** The staging finding for an unassigned tick that moved a backlog entry a sibling instance
  * holds — one the poll listed in the tick's `<held-entries>` note (LoopState.heldElsewhere).
@@ -89,13 +206,13 @@ export function assignedMovedFinding(claimKey, moved) {
  * point as assignedMovedFinding (BUGS.md 2026-10-12: 24 of 29 staged claims duplicated a
  * sibling's held entry, and each duplicate cost a gate check, a review, and a conflict
  * resolver run holding the merge slot). The fix-up turn is asked to drop the duplicate work.
- * A change that held nothing else then ends with no change to land. undefined when no moved
+ * A change that held nothing else then ends with no change to merge. undefined when no moved
  * entry is held. */
 export function heldMovedFinding(heldKeys, moved) {
     const dup = moved.find((m) => heldKeys.has(m.key));
     if (dup === undefined)
         return undefined;
-    return (`this tick moved a backlog entry a sibling instance holds: "${dup.title}" — it is that ` +
+    return (`this run moved a backlog entry another instance of this role is working on: "${dup.title}" — it is that ` +
         `instance's task (see <held-entries>), so revert every edit made for it, including the ` +
         `entry's move, and leave nothing behind if that was the whole change`);
 }
@@ -138,7 +255,7 @@ async function gitLevelFindings(wt, mainBranch) {
     }
     finally {
         // Restore the index to HEAD. Without this, the tick's change detection (changedFiles and
-        // stageTickLanding's "nothing left to land" guard) reads the stale index and reports a
+        // stageTickMerge's "nothing left to merge" guard) reads the stale index and reports a
         // fix-up that reverted the whole change as still changed, so an empty tree would reach
         // commitAll instead of the tick ending no_change.
         await gitTry(wt, "reset");
@@ -146,7 +263,8 @@ async function gitLevelFindings(wt, mainBranch) {
 }
 /** (a) References left behind by a rename or delete: for each `D` path and each `R` origin,
  * `git grep --cached` the old path across the staged tree and report up to MAX_STALE_HITS
- * `file:line` hits. Renames report the path they moved to; deletes report the deletion. */
+ * `file:line` hits outside record prose (isRecordProse). Renames report the path they moved to;
+ * deletes report the deletion. */
 async function staleReferenceFindings(wt, entries) {
     const findings = [];
     let reported = 0;
@@ -164,7 +282,7 @@ async function staleReferenceFindings(wt, entries) {
         const hits = [];
         for (const line of out.split("\n")) {
             const m = /^([^:]+):(\d+):(.*)$/.exec(line);
-            if (!m || !hasStandalonePathOccurrence(m[3] ?? "", old))
+            if (!m || isRecordProse(m[1]) || !hasStandalonePathOccurrence(m[3] ?? "", old))
                 continue;
             hits.push(`${m[1]}:${m[2]}`);
             if (hits.length >= MAX_STALE_HITS)
@@ -198,6 +316,13 @@ function hasStandalonePathOccurrence(line, needle) {
     }
     return false;
 }
+/** Each distinct path-shaped token in `text`, in first-appearance order: at least one slash and
+ * a final `.<ext>` segment. Scanned inside the text (not whitespace-split) so surrounding
+ * backticks, brackets, and sentence punctuation fall away with the match. */
+export function pathTokens(text) {
+    const tokenRe = /[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+\.[A-Za-z0-9]+/g;
+    return [...new Set([...text.matchAll(tokenRe)].map((m) => m[0]))];
+}
 /** (b) Nonexistent paths: every path-shaped token on an added diff line whose first segment is
  * a tracked top-level directory but which is absent from the staged tree. Rename origins and
  * deleted paths are excluded — "moved from X" prose names them legitimately. */
@@ -222,10 +347,6 @@ async function missingPathFindings(wt, diff, entries) {
     }
     const seen = new Set();
     const missing = [];
-    // A path-shaped token: at least one slash and a final `.<ext>` segment. Scanned inside the
-    // line (not whitespace-split) so surrounding backticks, brackets, and sentence punctuation
-    // fall away with the match.
-    const tokenRe = /[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+\.[A-Za-z0-9]+/g;
     let file = null;
     for (const line of diff.split("\n")) {
         if (line.startsWith("+++ ")) {
@@ -235,12 +356,12 @@ async function missingPathFindings(wt, diff, entries) {
         if (!line.startsWith("+") || line.startsWith("+++"))
             continue;
         // A test file's fixtures routinely name paths from the software under test, which need
-        // not exist here; the added-nonexistent-path heuristic targets real references, so it
-        // spares added lines in test/ (the rename/delete scan above still covers the file).
-        if (file?.startsWith("test/"))
+        // not exist here, and record prose names the paths a plan proposes to create; the
+        // added-nonexistent-path heuristic targets real references, so it spares added lines in
+        // test/ and in record prose (isRecordProse).
+        if (file !== null && (file.startsWith("test/") || isRecordProse(file)))
             continue;
-        for (const m of line.slice(1).matchAll(tokenRe)) {
-            const p = m[0];
+        for (const p of pathTokens(line.slice(1))) {
             const top = p.slice(0, p.indexOf("/"));
             if (!topDirs.has(top) || oldPaths.has(p) || staged.has(p) || seen.has(p))
                 continue;

package/dist/src/tick/telemetry-digest.js

@@ -1,22 +1,23 @@
 /** The `telemetry` role's tick-time evidence: the failure digest rendered over the role's own
- * one-day window. Split out of src/failure/failure-render.ts — which stays the pure
+ * trailing 24 h window. Split out of src/failure/failure-render.ts — which stays the pure
  * renderer — so every observer role's evidence builder has its own module the way
  * qa-coverage.ts and backlog-structure.ts do, and the tick lifecycle (tick-prompt.ts) injects
  * it from there instead of reaching into a report module. */
-import { collectFailureReport } from "../failure/failure-data.js";
+import { collectFailureReportSince } from "../failure/failure-data.js";
 import { renderFailureMarkdown } from "../failure/failure-render.js";
-/** The `telemetry` role's own digest window, in local calendar days (plans/telemetry-role.md).
- * The CLI keeps the usage report's 14-day default; the role reads one day so a cluster
- * re-surfaces only while it is live. The 2×-window read below still spans two days, which is
- * what makes the delta line meaningful. */
-export const TELEMETRY_DIGEST_DAYS = 1;
+/** The `telemetry` role's own digest window: the trailing 24 h ending now, not the local
+ * calendar day. A calendar day starts at midnight, so a run at 06:32 would never see the
+ * previous evening. The CLI keeps the usage report's 14-day default; the role reads 24 h so a
+ * cluster re-surfaces only while it is live. The collector's equal-length prior window is what
+ * makes the delta line meaningful. */
+export const TELEMETRY_DIGEST_MS = 24 * 60 * 60 * 1000;
 /** The `telemetry` role's tick-time evidence: the failure digest rendered over its own
- * one-day window. A missing or corrupt log omits the block (undefined) and never fails the
+ * trailing 24 h window. A missing or corrupt log omits the block (undefined) and never fails the
  * tick — an observer must not break on bookkeeping (plans/telemetry-role.md). The window and
  * the swallow-errors policy live with the digest, not in the tick lifecycle that injects it. */
 export function telemetryDigest(root) {
     try {
-        return renderFailureMarkdown(collectFailureReport(root, TELEMETRY_DIGEST_DAYS));
+        return renderFailureMarkdown(collectFailureReportSince(root, TELEMETRY_DIGEST_MS));
     }
     catch {
         return undefined;