Repository navigation
FIX-1421: detect declared-but-unsupported workforce-tree entries - #1885
Conversation
`main` does not compile. `f3ac10674` (#1878, FIX-1388 P3) is red: packages/workforce/src/seat-capabilities.ts(116,3): error TS2344: Type '"controlTools"' does not satisfy the constraint 'never' Failed: @flow-state-dev/workforce#build This is a semantic merge conflict, not a mistake in either change. #1852 (FIX-1393) added `controlTools` to `PresetDef`; #1878 added an exhaustiveness guard requiring every `PresetDef` key to sit in exactly one of `BUILD_TIME_ONLY_KEYS` or `DYNAMIC_KEYS`. Both are correct alone. Their union is not, and git had no conflict to report because the two changes touch different files. Each PR was green on its own head; the break exists only in the merged result. The guard did its job — it is a compile-time assert whose whole purpose is to stop a new key being classified by accident, and it fired on the first key added after it landed. The failure is loud and names the key. `controlTools` is classified DYNAMIC, and that is a fact about core rather than a preference: `resolveDynamicCapSurface` collects it on the same traversal as `tools` and returns both, so the dynamic path does carry it. Build-time-only would refuse a seat naming a control-bearing preset, which inverts what a control is for — a seat holds one because its own file asked. Deliberately NOT changed: a selected preset's `tools` still do not reach the seat past its own `tools:` fence. #1878 settled that in the strict direction and encoded it in "carries a selected preset's context but not its tool past the seat's fence". Selecting from what the app installed is picking off a shelf, not declaring your own; widening `tools:` from a seat file would re-open what FIX-1393 closed. Verified: - red state: reverting the one-line classification reproduces the exact TS2344 above; restoring it builds clean (exit 0) - pnpm typecheck 71/71 (was 49/62 with workforce#build failing) - workforce 24 files / 407 tests pass, including the fence case above Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
Cursor caught that `seat-capabilities.ts`'s module header still said the dynamic path carries "context and tools only" — false the moment `controlTools` joined `DYNAMIC_KEYS` two commits ago, in the same file. A stale restatement I created while fixing one. Also trims the `DYNAMIC_KEYS` note from ~15 lines to 8. Two reviewers split on this: Code Snob read the long form as house style (`BUILD_TIME_ONLY_KEYS` writes its deliberation inline too), Simplify read it as a fourth copy of canon that already lives in core's `PresetDef`, `agent-worker-flow.ts` and the fence test. Simplify wins on today's evidence — four copies of one rule is precisely how the thing below goes stale. The note keeps the classification's reason and points at the two canonical sources. **Scoped out deliberately, and filed instead.** Deriving the claim rather than fixing the line I was handed found ELEVEN sites carrying "context and tools only", all made incomplete by `controlTools`: core/src/capability/types.ts, merge.ts, core/src/blocks/internal/resolve-capabilities.ts, workforce/src/agent-worker-flow.ts, integration-tests task-board-park-exit-across-requests.test.ts, apps/docs fundamentals/capabilities.md, tools/claude-code-sdk.md, docs/architecture/capabilities.md (a section heading, authority level 2), docs/atlas/framework.html x3 — aria-label, visible SVG text, figcaption Ten of those are outside this file. This PR exists to unbreak `main`, and widening it across atlas, docs and core delays that for review surface it does not need. Filed as its own issue with the derived list and the scan that produced it. Worth noting the atlas triple is the exact shape FIX-1420 just built an aria-label/visible-text parity check for — that check greps the isolation rule, not this one. pnpm typecheck 71/71; workforce 24 files / 407 tests. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
`DYNAMIC_KEYS` carries a judgement the compile-time assertion cannot check — it only proves every `PresetDef` key is in *some* list. Putting `controlTools` in the build-time list would also have compiled, and would have refused every seat selecting a control-bearing preset: a silent narrowing instead of a build break. So a test has to hold it. Adds the positive half of the pair, ported from the parallel fix on fix/FIX-1388-controltools. Same seat shape as the existing fence check, one preset key different, opposite result — so the difference is attributable to that key. The sibling seat that names nothing still cannot call the control, which keeps it a selection rather than a gift to the kind. Red state: gating `dynControlTools.push(...)` behind `!declaresTools` in the generator's tools slot fails exactly this test (`expected +0 to be 1`) and no other. Reverted; `git diff packages/core/` clean. pnpm typecheck 71/71 · workforce 24 files / 408 tests. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
Five tickets found the same defect shape independently: an author writes something the published workforce-tree convention documents, a loader accepts it as valid-looking input, and nothing happens — no seat, no channel, no document, and no error. Every instance was found by hand-reading merged code, never by a failing test, which is why the shape keeps recurring per convention instead of being caught once. This is the coordination ticket's half: the policy, stated at the loaders' shared door, and a check that enforces it. It implements no child fix. The policy — consume it, or refuse it loudly naming the path, never silence — is not new. `discoverWorkforceCode` already applies it to the locked code folders. What was missing is anything that checks the rest of the tree. `published-tree-surface.test.ts` enumerates the tree shapes from the PUBLISHED surface — the pages and READMEs an author reads — rather than from the loaders, which would only ever confirm the list of instances already known. Each row cites the file and verbatim sentence that publishes it, re-checked against the real file, so a doc change breaks the suite instead of letting the table drift. Every row's entry is written into one tree, every reader runs over it, and a row must be consumed by some reader or named in some reader's errors. The silent set must EQUAL the known-gap list, so a new instance fails on arrival and a closed gap fails until its row is struck. Two rows are silent today, both FIX-1414's to close: `org/workers/<w>/ WORKER.md` and the `skills/` beside it. `documents-on-disk.md` publishes org-level workers and their documents load, so the tree addresses documents to a seat nothing can hire. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
|
The latest updates on your projects. Learn more about Vercel for GitHub.
2 Skipped Deployments
|
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 574d026. Configure here.
…path Review found two rows over-cited and two assertion defects. All four fold into one correction. **The two rows came out.** `org/workers/<worker>/WORKER.md` and the `skills/` beside it both cited documents-on-disk.md:41 — "Organization-level workers, under `org/workers/`, are read the same way." Read in context that sentence sits in the paragraph about a worker's own folder for DOCUMENTS, under a tree fence whose only `org/workers/` leaf is a `resources/` file. It does not tell anyone they may write an org-level `WORKER.md`, and the documents page says nothing about skills. Exhaustively: `org/workers` appears three times in the published surface and all three are about `resources/`. By this suite's own standard a wrong row is worse than no row, because it looks like coverage. **The real defect is sharper, and now cited to unambiguous table rows.** What we publish, twice, is a document ref `workers/<worker>/<name>` addressed to a seat nothing can hire. An author follows documents-on-disk.md:83, the document loads, and the address on it names nothing. So the class rule now also applies one level up: a published ref naming a worker must name a worker some reader accounts for. That is the same "consumed or reported, never silent" policy applied to an address instead of a path, and it is what `KNOWN_UNRESOLVABLE_REFS` records against FIX-1414. **Prefix match could go vacuous** (Bugbot, Low). The ref check asked whether any reported path *started with* the worker folder, and a failing sibling document under that folder satisfies it — the worker would read as accounted for and the equality assertion would look like FIX-1414 had closed. Latent rather than active on this fixture, and proved to diverge: with a sibling that fails to load, prefix says accounted-for and exact says unresolvable. Now exact. It was the only prefix match in the file. **Three published module paths were missing** (Bugbot, Medium). `org/resources/<name>.ts`, plus the worker-level `.ts` at both levels. The page splits a worker-level `.ts` by what the file IS — a plain resource is fine, a capability there is refused by name — and the walk cannot tell them apart, so it consumes both and flags the position. Those rows therefore assert the plain-resource half only, and say so: claiming the refusal from a path alone would be coverage the fixture cannot have. 16 published shapes. All consumed. One unresolvable ref, FIX-1414's. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
|
Did the check you asked for — each
So the failure mode: if someone later removes org workers from Cheapest fix if you touch this file again: give that row both quotes, so either page changing trips it. Not worth a round on its own. Worth saying plainly: the reason this is a footnote and not a finding is the rule you landed on — a grep hit is not a citation. Applied to two rows it removed them, and applied to a row it kept it surfaced that the row is load-bearing across two pages. That rule is the durable part of this PR, more than the sixteen rows are. One correction to my own earlier message, since it fed your report: I wrote that FIX-1414 and its siblings are "P3". They're not. Linear's numeric priority maps 2=High, 3=Medium, 4=Low — so FIX-1414 is Medium, this issue is High, and I mislabelled the numeric field as a P-level. Your correction was right. The load-bearing part — all five unscheduled in Backlog — holds either way. Generated by Claude Code |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
Simplify pass (FIX-1421)
Verdict: The doc-anchored, cross-reader detector is the right shape for this defect class. Enumerating shapes from loaders (or from past bugs) would stay self-confirming; the verbatim publishedIn quotes + equality on KNOWN_* lists are what make the ~525-line file load-bearing rather than accidental bulk. I would not replace this with a third-party doc linter alone — you still need the multi-reader harness and the ref-level half.
What I would not ask you to rip out: readEverything, per-row write / accountedFor, or the worker-ref assertion with exact folder matching (the prefix footgun called out in the PR is real).
Where the change set is heavier than FIX-1421 strictly needs
-
Two products in one PR. The
controlTools→DYNAMIC_KEYSfix, its module-header cleanup, and the fence regression test are the FIX-1388 / #1880 line of work. FIX-1421 is policy +published-tree-surface.test.ts+ a short loader door note. Merging was pragmatic whilemainwas red, but for reviewers the mental model is easier when the classification fix is already onmainand this PR is detector-only. Not a merge blocker from here. -
Policy prose in three places. The consume-or-refuse rule now lives in the test file header,
loader/index.ts, and (by reference) codegen discover. The loader block largely points at the test. Simpler: one paragraph at the loader door + link topublished-tree-surface.test.ts; keep the long rationale only where the allowlists live. -
Small harness DRY (optional). Duplicate doc-quote loops (shapes vs
WORKER_REFS_RESOLVE), duplicatefor (const shape of PUBLISHED_SHAPES) await shape.write(root)in two tests, and the samedocuments-on-disktable row cited both on the org-worker-resources shape and inWORKER_REFS_RESOLVE— all easy tidy-ups without weakening the guard. -
readEverythingcost (test-only).readWorkforcealready walksreadSeatSkillsper worker; the harness callsreadSeatSkillsagain foralpha.leadby design. Fine at 16 shapes × 2 tests; if the table grows, consider a sharedwriteAllPublishedShapes+ maybe one cached readout per test file — not worth refactoring preemptively. -
workerFromRefin the test. Mirrors minting rules without sharingmintResourceRef/ production helpers. Acceptable at this size; if FIX-1414 moves ref rules, consider a single package-level helper so the test cannot drift.
Alternatives considered (and why I’d stay on this approach)
| Alternative | Why I’d skip it |
|---|---|
| Per-reader “silent gap” tests only | Misses cross-reader silence — the actual failure mode |
Containment (silent ⊆ KNOWN) instead of equality |
Known gaps never force row deletion when fixed |
| Extract shapes to YAML/JSON fixture | Loses typed accountedFor and doc co-location |
Add a shared loudRefuse() primitive now |
PR already defers to FIX-1389 — agree |
Production fix bundled here: Moving controlTools into DYNAMIC_KEYS is the minimal compile-time-safe classification (the _EveryPresetKeyIsClassified guard cannot judge dynamic vs build-time by itself). The paired seat test is appropriate; citing exact it(...) titles in seat-capabilities.ts is brittle — behaviour wording would age better.
Checks: pnpm --filter @flow-state-dev/workforce test — 411 tests passed on this branch (includes new surface + control-tool cases).
No major concerns; approve with the optional tidies above left to author judgment.
Sent by Cursor Automation: Review For Best Approach
| * Being dynamic is not being unfenced: a selected preset's catalog `tools` | ||
| * still stop at the seat's own `tools:`. See `PresetDef.controlTools` for the | ||
| * distinction, and the paired tests in `test/seat-capabilities.test.ts` for | ||
| * the behaviour — *"carries a selected preset's context but not its tool past |
There was a problem hiding this comment.
Linking behaviour to exact it("…") strings in this file will rot when someone renames tests. The fence vs control distinction is worth documenting; I'd describe the invariant in prose and point at seat-capabilities.test.ts without quoting titles.
There was a problem hiding this comment.
Not mine to act on — flagging rather than silently ignoring.
seat-capabilities.ts came from #1880 (fix/classify-control-tools-seat-selection), which I merged into this branch only because main was red on its TS2344 and this branch wouldn't typecheck without it. #1880 has since merged to main, so that file is no longer in this PR's diff — which is now 2 files, loader/index.ts and the test.
The point itself looks sound (quoting it("…") titles rots on rename; describe the invariant and point at the file). It just belongs to whoever owns that code, not to a defect-class detector — editing it here would put an unrelated change back into a diff that just shrank to the thing under review.
Generated by Claude Code
There was a problem hiding this comment.
Code Snob — outcome 3: already tight. No POC.
Read: packages/workforce/src/loader/index.ts (the door essay), packages/workforce/test/published-tree-surface.test.ts (the detector), resource-convention.ts / discover.ts / read-workforce.ts only far enough to check whether workerFromRef or readEverything was a second encoding. seat-capabilities.ts + its test are #1880 riding along — already called tight there.
The new contract is one token: every path, and every worker-addressed ref, the published pages tell an author they may write is consumed or named, equality against a gap list. The 16 citation rows, the two quote re-checks, the ghost folder, and the empty KNOWN_SILENT_GAPS list are that token. A rewrite does not shrink it.
- Data-drive
write/accountedFor(16 lambdas → 16 records + a generic dispatch): quieter table, same pins. - Invert
mintResourceRefinstead ofworkerFromRef: same size, second spelling of the same rule. - Merge the path test and the ref test: two WHYs, one walk. The ghost folder exists to keep them from reading the same.
- Drop the empty gap list: the equality is what makes "none" sayable when the next row arrives.
- Strip the door essay or the file header: house style, same call as on #1824 / #1891.
Not re-litigated: the rule lives at the loader door; no internally-declared second category; paths + refs only; no loud-refuse primitive (FIX-1389); FIX-1414 owns the one unresolvable ref; the two worker-level .ts rows assert the plain-resource half only; dual citation on the org-worker .ts row (already a footnote).
Leftovers not implemented: FIX-1411 / 1412 / 1414 / 1419 / 1422.
Sent by Cursor Automation: Code Snob
|
Thanks — approved and useful. Dispositioning all five here rather than one line per thread, because two of them moved out from under the review while it was running. Two of the five are now moot: this PR is detector-only. #1880 merged in the interim, so the So your point 1 resolved itself — the classification fix is already on On that nit specifically, since it's my text and I don't fully agree. You're right that a quoted title rots on rename. But the alternative — prose pointing at a file — never rots and never helps either; it degrades silently into a signpost with nothing behind it. The better answer is the one this very PR uses: quote verbatim and make the quote checkable at runtime, which is what The three live ones — all fair, none pushed. The On the alternatives table — agreed, and the equality row is the load-bearing one. Containment over equality is precisely what lets a fixed gap linger in the allowlist as a standing excuse. That was deliberate and your reasoning matches ours. Two things you flagged as fine that I want on the record as known-fragile: Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d043f57248
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…refusals Three findings, one push. **The derivation guard was one-way** (Greptile, P1). Checking each row's quote against its cited file proves no row went stale. Nothing read the pages the other way, so a page that started declaring a new shape left the table quietly incomplete while every assertion in it passed — the exact decay this suite's own comment says it exists to prevent, and completeness is the claim the whole thing rests on. So the extraction that built the table by hand now runs as a standing check. Tree fences are reassembled from their indentation (a fence spells one path across many lines, which is why it was hand-read the first time), prose and tables are scanned for inline tokens, and every token is normalized by STRUCTURE — a segment the convention fixes stays literal, a segment the author names becomes the placeholder its parent slot implies. Normalizing against a list of known shapes would have been the self-confirming scan one level down; normalizing by structure means a shape nobody has written down yet comes out, and a genuinely new slot arrives spelled as itself and fails loudly. Three assertions, all equality: every declared shape has a row; every row the extractor cannot see is listed in PROSE_PUBLISHED with the sentence that publishes it; every declared file extension is exercised by a row. **`.tsx` was published and never exercised** (Codex, P2), and it is the instance that proves the above. workers-on-disk.md says "Every `.ts` and `.tsx` file in one of the three folders is a declaration". The table built `.ts` fixtures only, so dropping `.tsx` from TYPESCRIPT_EXTENSIONS would have silently ignored documented declarations with this suite green. It is not a new path — the directories were already tabled — so a path-only extractor would have shipped the same hole one level down. That is why extensions are extracted too. Two `.tsx` rows, not seven: `codegen/discover.ts` and `codegen/discover-resource-modules.ts` each keep their own TYPESCRIPT_EXTENSIONS, so one row per walk is the granularity at which dropping the extension can be caught. **A codegen refusal could not be recognised as a refusal** (Codex, P2). The catch pushed the aggregate WorkforceCodeError message as one array element while every predicate asks `reported.includes(path)` — exact match per element — so a path inside that message never matched and a conforming loud refusal was classified as silence. Now the structured `problems` array is used and each problem contributes the path it quotes. Proved: a refused `blocks/triage.fixture.ts` reads accounted-for by the parsed problems and silent by the old message. The lost `files`/`resourceModules` on throw are surfaced as `codeWalkThrew` in the failure text rather than papered over. Also carried, since the file was already open: a `writeAllPublishedShapes` helper, one constant for the ref-table row cited twice, and a note on why `teamSeatSkills` takes a second `readSeatSkills` call. 18 published shapes. All consumed. One unresolvable ref, FIX-1414's. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
Cursor: the paragraph had grown into a second copy of the test file's header. The rule belongs at the door; the derivation, the exclusion lists and the recorded gaps belong where they are enforced, in one place that cannot drift from itself. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt
Greptile: the P1 was only half fixed, and the half left behind was the
worse half. Reproduced exactly as reported — one line appended to
overview.md ("A tool lives at `org/tools/scanner.md` and is read at boot")
and the suite stayed green on 4 passed.
**This is the sharpest instance this epic has produced, and it is mine.**
The previous commit anticipated this exact critique, argued structural
normalization avoided it, and named `org/tools/…` as the proof. The
normalization is structural and that part was true. The FILTER IN FRONT OF
IT was not: `toShape` required a segment drawn from a vocabulary of slots
already known, so the one case the completeness check exists for — a slot
nobody has written down yet — was discarded before normalization could see
it. A self-confirming scan sitting inside the fix for the self-confirming
scan, defended in a PR body by the example that disproves it.
The filter's job was rejecting refs and folder mentions, and it did that by
asking "is this built from parts we already recognize?" — the wrong
question. The leaf test above it already answers the right one: a shape ends
in a file, a ref and a folder mention do not. Measured rather than argued:
over the whole published surface, removing the slot check changes the
extracted set by ZERO shapes. It was rejecting nothing and hiding the only
thing that mattered.
An unrecognized segment now stays literal and fails by name.
**`PUBLISHED_FILES` was hand-maintained while calling itself the published
surface** — the same defect one level up, so it is derived now. Every `.md`
under the workforce and skills doc trees is read, so a page added to either
is scanned the moment it lands. What stays manual is which directories,
which is a much smaller claim, and the residual scope is stated rather than
implied: a page published elsewhere is not scanned and this suite will not
say so.
Regression added, synthetic because the slot must not exist: an
unrecognized slot must come out of the extraction spelled as itself, and a
ref and a folder mention must still not. Proved red by restoring the old
filter (`expected [] to deeply equal [ 'org/tools/scanner.md' ]`), and
proved end to end by re-running the reported reproduction, which now fails
naming the path.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt



The problem
Someone writes a workforce folder exactly the way our published docs tell them to. The loader accepts it. Nothing happens — no seat, no channel, no document, and no error. They have no way to find out except by reading our source.
Five separate tickets found that same shape independently (FIX-1411, FIX-1412, FIX-1414, FIX-1419, FIX-1422). Every one was caught by a person hand-reading merged code during spec work. Not one was caught by a test.
That last fact is the actual problem. Patching five instances leaves the sixth to be found the same way — by luck, in someone else's app.
What this does
It makes the class detectable, and it fixes none of the five. Each child keeps its own call.
The rule goes at the door every loader is added beside (
packages/workforce/src/loader/index.ts): anything the published convention tells an author they may write is either consumed or refused loudly, naming it. Never silence. The rule isn't new — the code-folder walk already applies it. Nothing checked it.The check (
packages/workforce/test/published-tree-surface.test.ts) enforces it in three parts.Paths. Eighteen published shapes go into one tree, every reader runs over it, and each must come back loaded or named in an error.
Addresses, where the real defect lives. The ref tables publish addresses, and we publish — twice — a document ref
workers/<worker>/<name>pointing at a seat nothing can hire. An author followsdocuments-on-disk.md:83, the document loads, and the address on it names nothing. Same defect, one level up.The derivation itself, guarded in both directions. This is what decides whether any of the above can be trusted. Checking each row's quote against its page proves no row went stale. It proves nothing about a page that starts declaring something new — and completeness is what the whole thing claims. So the extraction that built the table by hand now runs as a standing check: fences reassembled from indentation, prose scanned for path tokens, everything normalized by structure, and every declared path and file extension required to have a row. A path shape it has never seen before comes out spelled as itself and fails by name. A missing row is worse than a missing check, because it looks like coverage.
Every list here is asserted by equality, not containment. A new instance fails on arrival; a gap someone closes fails until its row is deleted. Nothing can rot into a standing excuse.
Where that leaves us: all eighteen published shapes are read by something today. One published ref is not resolvable —
workers/<worker>/<name>— and it's FIX-1414's to close.What's asked of you
Nothing. No product decision here. This adds a check and changes no behaviour an author can see.
An earlier draft asked whether to caveat the docs about organization-level workers. That question rested on a misreading of our own page and has been withdrawn — see Engineering calls.
Parts worth reviewing closely
toShape's early returns as adversarially as its output: each one is a place a published shape can vanish.PROSE_PUBLISHED(5) andNOT_AN_EXTENSION(1) are where an imperfect extractor is permitted to be imperfect. Every entry carries a reason; a reason that doesn't hold is a blind spot with paperwork.PUBLISHED_DIRECTORIES. Derived per-directory now, so a new page is scanned automatically — but a page published outside those trees is not, and the comment says so. Check that the stated scope matches what you'd expect "the published surface" to mean..tsrows. They assert less than the page says, on purpose; the comment names which half is covered. Review the reasoning, not the assertion.codeWalkThrew. When the codegen walk throws, its results are genuinely gone, so neighbouring rows report unverifiable rather than being silently excused. A deliberate choice about what a degraded readout should do.Links
Linear: FIX-1421 · parent epic FIX-1351 (W3 — File-convention surface) · no spec, no spec PR (defect class, direct route) · this PR merges.
How to review this — altitude, what's in scope, what's deliberately unsettled
How to review this. This is a bug fix on the direct route: there is no spec and no spec PR, because the hard part was the diagnosis and it happened in code. This PR is the only gate, so unlike a spec-backed change, the approach is in scope — nothing here was signed off upstream.
Most valuable here: the diagnosis chain — does the repro actually reproduce the reported failure, is the named cause the real one, does the fix address that cause rather than the symptom, and does the regression test fail without the fix? Then the second path (the legacy shape, the null boundary, the concurrent case, the cancel path).
In scope to challenge: where the guard was placed, any behaviour change a user could notice, and whether this should have been a spec'd feature instead of a fix.
The most useful thing this PR produced — instance ten, and it was mine
Recorded plainly because it is better data than the fix it describes.
The previous revision added a completeness check to close a P1: the derivation guard only ran
table → docs, so a newly published shape stayed invisible. In writing it I anticipated exactly the critique that would follow, argued that normalizing by structure rather than against known shapes avoided it, and named the example that proved it:A reviewer appended one line to
overview.md—A tool lives atorg/tools/scanner.mdand is read at boot— and the suite passed. Green, on the exact spelling I had named as proof.The normalization was structural. The filter in front of it was not:
A token had to contain a slot word already known, so the one case the check exists for was discarded before normalization could see it.
A self-confirming scan, inside the fix for the self-confirming scan, defended in a PR body by the example that disproves it. Ninth instance in this epic of an assertion that can't fail for its stated reason; second of that species; and the only one where the author had already argued the point in writing.
Two things generalize:
distill-lessons: a claim that a check can't fail a certain way needs the failing case run, not the reasoning written out.The fix cost nothing, which is its own indictment: removing the filter changes the extracted set by zero shapes across the whole published surface. It was rejecting nothing and hiding the only thing that mattered.
Engineering calls — decided along the way, no product sign-off needed
org/workersappears three times in the whole published surface and all three are aboutresources/. No page to caveat, no promise to retract. What survives is narrower and is FIX-1414's: a ref we do publish points at an unhireable seat.org/workers/leaf is aresources/file. Cost: two real tree-level silences are no longer asserted. Accepted — a row claiming a citation it doesn't have is the failure mode this suite exists to prevent.toolsto the known set would have fixed the reported case and left the class intact. Measured first: the leaf test alone rejects every ref and folder mention across the whole surface, so the filter was pure loss.PUBLISHED_DIRECTORIES, not a page list. A hand-listed set of pages describing itself as the published surface is this suite's own defect one level up. Derived per-directory; the residual manual claim is which trees, and that limit is stated rather than implied.declared ⊆ tabledis the bug; the reverse is a row published in prose rather than as a path, already covered by the quote check. Those are enumerated inPROSE_PUBLISHEDand asserted to be exactly the difference, so blind spots are bounded and visible rather than silent..tsxrows, not seven.codegen/discover.ts:82andcodegen/discover-resource-modules.ts:65each keep their ownTYPESCRIPT_EXTENSIONS, so one row per walk is the granularity at which dropping the extension can be caught.TYPESCRIPT_EXTENSIONSin one package contradicts CLAUDE.md's "no duplicate copies". Out of scope for a defect-class detector; wants its own change.org/channels/is published nowhere user-facing (grep → 0); neither is an org-levelWORKER.md. Both are internal-lock gaps, not broken author-facing promises. Recorded on both issues.refusedDeclaration, and the hire's refusal of a setting the kind doesn't declare (test/hire.test.ts:436coversteamInstructions:by name).Review findings addressed — seven, across four reviewers
Five of the seven were assertions that could not fail for the reason they claimed, found inside a detector built for exactly that class. Three were self-confirming in the specific sense this suite is named after.
table → docsonly.tsxpublished, never exercisedPUBLISHED_FILESwas hand-maintained while calling itself the published surfaceFinding 7 is covered above in its own section. Finding 3 is what turned finding 2 from structural into demonstrated:
.tsxis not a new path — the folders were already tabled — so a path-only extractor would have shipped the same hole one level down, which is why extensions are extracted too.Also carried: a
writeAllPublishedShapeshelper, one constant for the ref-table row cited twice, a note on whyteamSeatSkillstakes a secondreadSeatSkillscall, and the loader-door paragraph shrunk to the rule plus a pointer.One Cursor nit on
seat-capabilities.tsis not addressed: that file came from #1880, which has since merged, so it's no longer in this diff. Answered on the thread and left open for its owner.Verification — what was executed, and the red states
A check that has never failed isn't a check. Every claim below was executed; each red state was restored.
The unseen-slot regression (finding 7). Reproduced the reported case first — one line in
overview.md, suite green on 4 passed. Then, after the fix, both directions:And the measurement behind removing the filter rather than extending it: across the whole published surface the extracted set is 13 shapes with the filter and 13 without. It rejected nothing.
The completeness check's acceptance test (finding 2, via finding 3). Against the table as it stood:
Codegen refusal parsing (finding 4). A
blocks/triage.fixture.tsfixture, refused by name:Prefix vs exact (finding 5). Latent on this fixture, so proved to diverge rather than assumed:
Does the ref check see today's real silence? Emptied
KNOWN_UNRESOLVABLE_REFS→+ "build", and onlybuild. The fixture also holdsteams/alpha/workers/ghost/(documents, noWORKER.md), which must not appear — proving the assertion discriminates rather than flagging every worker-addressed ref.Does it catch a new instance? Stubbed the
org/walk out ofread-resources-directory.ts:Both halves fire, and the
-shows a known gap disappearing fails too.Is the derivation tied to the docs? Corrupted one row's quote → the citation guard names the row and the file.
Green.
npx vitest runinpackages/workforce— 25 files, 413 tests.pnpm --filter @flow-state-dev/workforce typecheck— clean. Counts re-derived from the file rather than remembered: 18 shapes, 5PROSE_PUBLISHED, 1NOT_AN_EXTENSION, 11 pages scanned (up from 8 hand-listed, with no new shapes).The original finding, reproduced before any of this was written:
How the table is derived
Docs → code, never code → code. Originally by hand; now the same extraction runs as a standing check:
.mdunderPUBLISHED_DIRECTORIES, plus the package README.PROSE_PUBLISHED/NOT_AN_EXTENSIONcarrying a reason.🤖 Generated with Claude Code
https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt