@davidbalzan/groundwork-seam 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -6,6 +6,14 @@ Started at 0.1.6 because a contract change landed in the tree with nowhere to re
 it — which is the same class of gap as the change itself: a fact that exists and has
 no home.
 
+## [0.1.16] — 2026-09-11
+
+### Fixed
+- `zeroIsUnparsed` no longer reports a pruned-but-healthy queue as unparsed. It measured CONTENT (`substantiveLines`) on every axis — the right question for the done axis, the wrong one for a queue, which keeps its headings and explanatory prose by design. Measured on this repo's own queue: 793 substantive lines, zero rows, `unparsed: true`. Red-when-fine, one axis over from the failure the predicate was written to avoid.
+
+### Added
+- `queueRowAttempts` and an optional `axis` argument to `zeroIsUnparsed`. For `"queue"` the discriminator is checkbox ROW ATTEMPTS — lines somebody wrote as rows — not authored content. **Omitting the axis preserves the previous behaviour exactly**, so the done and board axes are unchanged. Not "any list item": pruning the real queue leaves 0 checkbox lines and 9 plain bullets of template prose, so a bullet-counting predicate stays red on the very case being fixed.
+
 ## [0.1.8] — 2026-08-28
 
 ### Added

package/README.md

@@ -4,4 +4,51 @@ Schema owner of `docs/QUEUE.md`, `docs/DONE.md`, `docs/WORKSTREAMS.md`, `docs/FA
 
 Markdown stays authoritative. This package is a library, not a daemon.
 
+## Find the answer without knowing the name
+
+**This section is indexed by the QUESTION, not by the export.** If you are about to
+write a regex against one of these documents, the answer is almost certainly here —
+and if it is not, that is a gap in this package, not a reason to hand-roll one.
+See *Gaps* below for the ones we know about.
+
+> **Why this section exists.** A consumer re-derived three verdicts this package
+> already owns, each with a local regex. That is a seam-design failure, not a
+> consumer bug: every export was present and none was findable without already
+> knowing its name. The fix is that the name is now the ANSWER rather than the
+> search term.
+
+| You want to know… | Ask | Never |
+|---|---|---|
+| Is this queue item done? | `queueItemsOf(doc)` → `item.done` | a `/\[x\]/` or `/done\|merged\|closed/i` regex |
+| What are this queue's items at all? | `queueItemsOf(parseWorkDoc(text))` | splitting on `- [ ]` |
+| What does this DONE entry cite? | `doneEntriesOf(doc)` → `entry.ref` | scraping `#\d+` from the line |
+| Do two refs mean the same PR? | `refsMatch(a, b, { contextRepo })` | string equality |
+| What CLOSED this queue row? | `closingCitation(row)` — a nullish result means *read the row* | any "closed by" in the body; 4 rows say it in prose |
+| …the same commit? | `commitRefMatches(a, b, { contextRepo })` | comparing sha prefixes by hand |
+| Which refs does this text carry? | `refsIn(text)` · `commitRefsIn(text)` | a local `#(\d+)` |
+| Which board grammar is this? | `boardSchemaOf(doc)` | reading the header row yourself |
+| Which board rows are `workstreams.v1`? | `workstreamsV1RowsOf(doc)` | indexing table cells positionally |
+| Does this row carry a leading tag? | `leadingTagsOf(item)` · `sweepTagOf` · `awaitingOf` | matching `**[KEY:value]**` anywhere in the line |
+| Is a zero an answer or an unread file? | `zeroIsUnparsed(count, sourceText, axis?)` | treating `0` as "none" |
+| What is wrong with this document? | `workDocIssues(doc)` · `workDocIssuesDetailed(doc)` | your own validator |
+| Which phase citations CLOSE a task? | `phaseClosureCitationsIn(text)` | `phaseCitationsIn`, which cannot tell "closes" from "unblocks" |
+| Did this diff newly tick a task? | `newlyTickedInDiff(diff)` | diffing checkbox counts |
+
+**A verdict this package exports is a verdict this package owns.** If your code
+answers one of the questions above with its own regex, the two answers will
+diverge — and the divergence is silent, because both sides parse cleanly.
+
+## Gaps — questions this package does NOT answer
+
+Recorded so a consumer can tell "you missed it" from "we do not offer it", and so
+the check that flags re-derivations knows what it must NOT flag.
+
+- **Counting checkboxes in a phase file.** `newlyTickedInDiff` reads a DIFF;
+  `phaseCitationsIn` reads citations in prose. Neither counts `- [x]` in a phase
+  document. A consumer doing that is filling a gap, not duplicating a verdict.
+- **The source LINE of a parsed item.** No item type carries a line, index or
+  offset, so anything that reports `docs/QUEUE.md:<line>` must scan lines itself.
+
+## Notes
+
 PR2 parse contract: any markdown table is a board, arity 5. Header-cell detection is PR3.

package/dist/docs.d.ts

@@ -82,9 +82,19 @@ export type Block = {
     kind: "decisions";
     items: string[];
 };
+/** What the continuation check looked at, and the RULE that produced it. */
+export type ContinuationPopulation = {
+    rule: string;
+    linesConsidered: number;
+    loadBearing: number;
+    proseOnly: number;
+    excludedCommentBlockLines: number;
+    excludedBlockquoteLines: number;
+};
 export type WorkDoc = {
     trailingNewline: boolean;
     blocks: Block[];
+    population?: ContinuationPopulation;
     warnings?: string[];
     advisories?: string[];
 };
@@ -94,12 +104,44 @@ export declare function parseQueueLine(line: string, section?: string): QueueIte
 /** The warning an invalid-priority item earns, quoting the tag and naming the set. */
 export declare function invalidPriorityIssue(item: QueueItem, line?: number): string;
 export declare function parseDoneLine(line: string, section?: string): DoneEntry | null;
+/**
+ * Does this text carry a CITATION — an issue/PR ref or a commit sha?
+ *
+ * Deliberately delegates to `refsIn`/`hasCommitRef` rather than testing a local
+ * regex. The comment below those primitives says why: four separate matchers
+ * re-derived "what is a ref" in one day and each got it wrong differently. A
+ * fifth here would be the same mistake with a done line instead of a queue item.
+ *
+ * This is NOT `parseDoneLine`'s tail rule, and the difference is the point. That
+ * rule accepts any space-free token after ` — ` as a ref, which is right for a
+ * record it is about to keep but far too loose for deciding whether a HEADING was
+ * a completion in disguise: `## Phase 5 — shipped` would qualify. A malformation
+ * detector that cries wolf on ordinary prose gets switched off, so this one asks
+ * for a real citation shape.
+ */
+export declare function carriesCitation(text: string): boolean;
+export declare const doneReflessIssue: (line: number, text: string) => string;
+export declare const doneHeadingFormIssue: (line: number, heading: string) => string;
 export declare function withoutCodeContext(text: string): string;
 export type Ref = {
     raw: string;
     repo: string | null;
     number: string;
 };
+/**
+ * What a queue continuation line is HIDING, or null if it is only prose.
+ *
+ * ⟨q-3f81c92e⟩ — `queue.v1` is one line per item, so a continuation is kept for a
+ * human and dropped by every consumer. That is tolerable for commentary and not
+ * tolerable for the two things a reader ACTS on: the acceptance criteria and the
+ * citation. Hidden there, `list_work` hands a worker a row whose acceptance does
+ * not exist and whose PR cannot be followed, with nothing to indicate a loss.
+ *
+ * Reuses `refsIn` rather than re-deriving a ref pattern: four separate matchers
+ * re-derived ref matching in one day once and each got it wrong, which is why
+ * that primitive is shared (see `REF_RE`'s own note).
+ */
+export declare function loadBearingContinuation(line: string): string | null;
 /** Every issue/PR reference in a string, qualified where the text qualified it. */
 export declare function refsIn(text: string): Ref[];
 /**
@@ -146,6 +188,51 @@ export declare function commitRefsIn(text: string): string[];
  * does not carry that state.
  */
 export declare function hasCommitRef(text: string): boolean;
+/** Every state the fleet's boards actually declare. `unknown` is a real answer. */
+export type WorkState = "blocked" | "in-progress" | "in-review" | "done" | "parked" | "orphaned" | "accepted-risk" | "staffable" | "skipped" | "no-downstream" | "unstaffable" | "unclassified" | "unknown";
+/** The projection a renderer asks for: is anybody working on this? */
+export type CoarseWorkState = "in-flight" | "finished" | "open" | "unknown";
+export declare const declarationOf: (status: string) => string;
+/**
+ * The state a board status DECLARES.
+ *
+ * Leading glyph decides; an unknown glyph is `unknown`; a glyphless status is read
+ * from its declaration only. Commentary never answers.
+ */
+export declare function workStateOf(status: string | null | undefined): WorkState;
+export declare function coarseOf(state: WorkState): CoarseWorkState;
+/** What a queue row's CLOSING POSITION cites. */
+export type ClosingCitation = {
+    token: string;
+    refs: Ref[];
+    commits: string[];
+};
+/**
+ * What the row's closing position cites, or `null` when it has none.
+ *
+ * ⚠ THE RETURN IS THREE-VALUED AND THE THIRD VALUE IS THE POINT:
+ *   - a citation — the closing position names these refs/commits;
+ *   - `null`     — THERE IS NO CLOSING POSITION TO READ, so *read the row*.
+ *
+ * ⛔ `null` is returned BOTH when there is no token AND when no token cites
+ * anything, and the collapse is deliberate: a trailer saying something
+ * unparseable must not make a row uncited on the strength of its own prose.
+ *
+ * ⛔⛆ DO NOT "SIMPLIFY" THIS TO AN EMPTY REF LIST. An empty list reads as *"the
+ * closing position says nothing owes"* — a positive claim — where `null` says
+ * *"I cannot answer; ask the row."* On the delivery-marker side that substitution
+ * turns an honest `answerable: false` into a confident wrong zero.
+ *
+ * ⛔ THIS IS A **READER**, NOT A DECISION. It does not decide the tie, does not
+ * resolve repositories (that is `refsMatch` + a `contextRepo`, and a BARE `270`
+ * is correctly untieable with no origin), does not match `DONE.md` entries, and
+ * does not read commit subjects. Its consumers ask DIFFERENT questions of the
+ * same answer — `doctor` falls back to the whole row because it asks "can this
+ * row be tied at all?", while the delivery-marker gate stays untied and says so
+ * because it asks "which refs CLOSED it?" — so sharing this reader is correct
+ * and sharing either of those decisions is not.
+ */
+export declare function closingCitation(text: string): ClosingCitation | null;
 /**
  * Do two cited shas name the same commit? Compared as a PREFIX, not
  * equality: git's own abbreviation convention means a 7-char short sha and a
@@ -154,11 +241,28 @@ export declare function hasCommitRef(text: string): boolean;
  * where the two citations were written at different times.
  */
 export declare function commitRefMatches(a: string, b: string): boolean;
+export type LeadingTag = {
+    key: string;
+    value: string;
+};
+/** The tags an item CARRIES, in order, lowercased. Body mentions are not tags. */
+export declare function leadingTagsOf(item: QueueItem): LeadingTag[];
 /**
  * The sweep tag an item CARRIES, or null. A tag quoted in the body is not carried
  * — that is the whole distinction, and it is why this is not a substring test.
  */
 export declare function sweepTagOf(item: QueueItem): string | null;
+/**
+ * WHO an item declares it is waiting on, or null.
+ *
+ * `**[AWAITS:david]**` is a FIELD set by whoever files the item. It is never
+ * inferred: an item whose prose says "awaiting David's ruling" and carries no
+ * marker awaits nobody as far as any tool can tell. That is deliberate — reading
+ * intent out of English is how identity churned before ids were recorded, and
+ * gating goes the same way (q-e334937d). Routing verbs skip a carrier and
+ * REPORT it on its own axis; nothing makes it vanish.
+ */
+export declare function awaitingOf(item: QueueItem): string | null;
 /** Items carrying `tag`. Never items merely mentioning it. */
 export declare function itemsBySweepTag(items: QueueItem[], tag: string): QueueItem[];
 /** Every carried tag with its item count, so a census never needs a grep. */
@@ -177,6 +281,85 @@ export declare function renderDoneLine(entry: DoneEntry): string;
 export declare function looksLikeBoardAttempt(cells: string[]): boolean;
 export declare function renderBoardRow(r: BoardRow | WorkstreamsV1Row | ExtensionRow | MalformedRow): string;
 export declare function parseWorkDoc(source: string): WorkDoc;
+/**
+ * Stamp every queue item that carries no recorded id, and say which.
+ *
+ * THE WRITE IS WHERE IDENTITY GETS RECORDED, because a convention only works on
+ * seats that have read it and this file takes writes from outside the fleet
+ * (q-c50e9b83). Twice on 2026-09-04 a peer fleet appended a raw `- [ ] (P2)` row
+ * — by heredoc, then by a python insert — never invoking the stamping script:
+ * the id was not absorbed or lost, it was NEVER EMITTED. The gate then fired on
+ * whoever committed next rather than on the writer, so one seat reddened `main`
+ * for rows it had not written while the seat that could have prevented it never
+ * saw a failure.
+ *
+ * SO A SUPPORTED WRITE STAMPS EVERY UNSTAMPED ITEM, INCLUDING ONES THE CALLER
+ * DID NOT AUTHOR. Narrowing it to the caller's own rows would leave the absorbed
+ * row unstamped and keep the defect while moving the blame, which is the worst
+ * of both.
+ *
+ * WHY THAT IS SAFE RATHER THAN A SURPRISE DIFF: `withRecordedId` writes the id
+ * the item ALREADY HAS, derived from its current text, so no id changes value and
+ * no join key moves. Measured on the one row in this repo's queue that took both
+ * paths — a peer fleet's raw append, later stamped by hand: the derived id and the
+ * hand-written one are byte-equal.
+ *
+ * `stamped` exists so an ABSORBING WRITER LEARNS IT ABSORBED SOMETHING rather
+ * than discovering it in a diff. It lists only items this call stamped, never one
+ * that was already correct — a report that names every row is one its reader
+ * learns to ignore.
+ */
+export declare function stampQueueIds(doc: WorkDoc): {
+    doc: WorkDoc;
+    stamped: string[];
+};
+/**
+ * The render every WRITER must use: identical to `renderWorkDoc` except that it
+ * stamps first and reports what it stamped.
+ *
+ * Kept separate from `renderWorkDoc` deliberately. That one is also the READ-side
+ * round-trip — parse, render, compare — and a render that mutates identity would
+ * make a faithful round-trip impossible to express. Two functions, two contracts:
+ * render what is there, or write what should be there.
+ */
+export declare function renderWorkDocForWrite(doc: WorkDoc): {
+    text: string;
+    stamped: string[];
+};
+export type ZeroAxis = {
+    axis: "queue" | "done" | "board";
+    count: 0;
+    unparsed: boolean;
+    why?: string;
+};
+/** Non-blank lines that are not headings, frontmatter delimiters or comments. */
+export declare function substantiveLines(text: string): number;
+/** Checkbox list items outside frontmatter: queue rows somebody attempted to write. */
+export declare function queueRowAttempts(text: string): number;
+/**
+ * Is this axis's zero an ANSWER or an UNANSWERED QUESTION?
+ *
+ * `count > 0` is never in doubt, so this only ever qualifies a zero.
+ *
+ * THE QUEUE AXIS ASKS A NARROWER QUESTION THAN THE OTHERS, because on a queue
+ * document prose is not evidence of a missed row. `substantiveLines` was built
+ * for the done axis, where any authored line under an empty log is a fair
+ * reason to doubt the zero. A pruned `docs/QUEUE.md` keeps its headings AND its
+ * explanatory prose by design, so that same measure reported a perfectly
+ * healthy empty queue as unparsed — red-when-fine, measured at 793 substantive
+ * lines with zero rows present.
+ *
+ * So for `axis: "queue"` the discriminator is ROW ATTEMPTS, not content. The
+ * four states this separates, measured on this repo's real `docs/QUEUE.md`:
+ * populated (168 rows, count 168) `false` · pruned-but-prose-kept (0 attempts)
+ * `false` · heading-removed, so the rows exist but nothing parses them (168
+ * attempts, count 0) `true` · rows present but refused by the grammar (2
+ * attempts, count 0) `true`.
+ *
+ * Axis is OPTIONAL and omitting it preserves the old behaviour exactly, so the
+ * done and board axes are untouched by this change.
+ */
+export declare function zeroIsUnparsed(count: number, sourceText: string, axis?: ZeroAxis["axis"]): boolean;
 export declare function renderWorkDoc(doc: WorkDoc): string;
 export declare function queueItemsOf(doc: WorkDoc): QueueItem[];
 export declare function doneEntriesOf(doc: WorkDoc): DoneEntry[];