Skip to content

FIX-1421: detect declared-but-unsupported workforce-tree entries - #1885

Merged
jhoffner merged 8 commits into
mainfrom
fix/FIX-1421-loader-silent-accept
Sep 18, 2026
Merged

jhoffner merged 8 commits into
mainfrom
fix/FIX-1421-loader-silent-accept

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 18, 2026 •

Copy link
Copy Markdown
Collaborator

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 follows documents-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

  • The derivation, still — and its filters most of all. The single worst defect in this PR's history was a filter in front of a correct normalizer, and it survived a round of review because the normalizer was the part everyone looked at. Read toShape's early returns as adversarially as its output: each one is a place a published shape can vanish.
  • The exclusion lists. PROSE_PUBLISHED (5) and NOT_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.
  • The scope of 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.
  • The two worker-level .ts rows. 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:

"Structure means a shape nobody has written down yet comes out, and a genuinely new slot (org/tools/…) arrives spelled as itself and fails loudly rather than being bent to fit."

A reviewer appended one line to overview.md — A tool lives at org/tools/scanner.md and 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:

if (!segments.some((s) => SLOTS.has(s)) && segments[0] !== "blocks") return undefined;

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:

  1. The filter is where these hide, not the transform. Four of this PR's findings were in what gets discarded before the real logic runs — a prefix match, a swallowed error message, a path-only extractor, a slot-vocabulary gate. Review attention goes to the assertion; the defect lives in the guard clause above it.
  2. Anticipating a critique in prose is not evidence against it. The paragraph arguing this couldn't happen made it less likely to be checked, not less likely to be true. Worth a line in 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
  • Withdrew the escalated product question, and left the pages alone. The first draft asked whether to tell authors organization-level workers don't work yet. The premise was wrong: we never published that they exist. org/workers appears three times in the whole published surface and all three are about resources/. 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.
  • Two rows were over-cited, and came out. Both leaned on documents-on-disk.md:41, a sentence in the paragraph about a worker's own folder for documents, under a tree fence whose only org/workers/ leaf is a resources/ 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.
  • Removed the slot-vocabulary filter rather than extending it. Adding tools to 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.
  • The completeness assertion is one-directional by design. declared ⊆ tabled is the bug; the reverse is a row published in prose rather than as a path, already covered by the quote check. Those are enumerated in PROSE_PUBLISHED and asserted to be exactly the difference, so blind spots are bounded and visible rather than silent.
  • Two .tsx rows, not seven. codegen/discover.ts:82 and codegen/discover-resource-modules.ts:65 each keep their own TYPESCRIPT_EXTENSIONS, so one row per walk is the granularity at which dropping the extension can be caught.
  • That duplicated constant is a smell, and is not fixed here. Two copies of TYPESCRIPT_EXTENSIONS in one package contradicts CLAUDE.md's "no duplicate copies". Out of scope for a defect-class detector; wants its own change.
  • No "internally declared" second category. Nothing in the repo states the W3 lock, so such rows would carry no quote to re-check and would drift exactly the way the guard prevents. Keeping the categories apart also keeps the assertion sayable: mixing promises to authors with plans we made to ourselves makes "we publish this and it doesn't work" unsayable.
  • Same reasoning applied to FIX-1419 and FIX-1414. org/channels/ is published nowhere user-facing (grep → 0); neither is an org-level WORKER.md. Both are internal-lock gaps, not broken author-facing promises. Recorded on both issues.
  • Scoped to paths, refs and extensions — not frontmatter keys. Already enforced at two doors: each reader's refusedDeclaration, and the hire's refusal of a setting the kind doesn't declare (test/hire.test.ts:436 covers teamInstructions: by name).
  • No shared "loud refuse" primitive. FIX-1389's territory and in flight.
  • No changeset (BP-022). A test and an internal module docstring.
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.

# Finding Reviewer
1 Two rows cited a sentence that meant something else human
2 Derivation guard ran table → docs only Greptile P1
3 .tsx published, never exercised Codex P2
4 Codegen refusal unrecognisable as a refusal Codex P2
5 Prefix match could go vacuous Bugbot Low
6 Three published module paths missing Bugbot Medium
7 Finding 2's fix discarded unseen slots — and PUBLISHED_FILES was hand-maintained while calling itself the published surface Greptile

Finding 7 is covered above in its own section. Finding 3 is what turned finding 2 from structural into demonstrated: .tsx is 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 writeAllPublishedShapes helper, one constant for the ref-table row cited twice, a note on why teamSeatSkills takes a second readSeatSkills call, and the loader-door paragraph shrunk to the rule plus a pointer.

One Cursor nit on seat-capabilities.ts is 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:

# regression red, with the old filter restored
expected [] to deeply equal [ 'org/tools/scanner.md' ]

# the reported reproduction, re-run end to end
AssertionError: The published pages declare a path shape with no row in PUBLISHED_SHAPES.
+   "org/tools/scanner.md"

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:

AssertionError: The published pages name a file extension no row exercises.
+   ".tsx",

Codegen refusal parsing (finding 4). A blocks/triage.fixture.ts fixture, refused by name:

PROBE accounted byOldMessage:      false     ← a loud refusal read as silence
PROBE accounted byParsedProblems:  true

Prefix vs exact (finding 5). Latent on this fixture, so proved to diverge rather than assumed:

PROBE reported: ["org/workers/build/resources/bad.md"]
PROBE unresolvable byPrefix: false   byExact: true

Does the ref check see today's real silence? Emptied KNOWN_UNRESOLVABLE_REFS → + "build", and only build. The fixture also holds teams/alpha/workers/ghost/ (documents, no WORKER.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 of read-resources-directory.ts:

+   "org/resources/<name>.md",
+   "org/workers/<worker>/resources/<name>.md",
-   "build",

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 run in packages/workforce — 25 files, 413 tests. pnpm --filter @flow-state-dev/workforce typecheck — clean. Counts re-derived from the file rather than remembered: 18 shapes, 5 PROSE_PUBLISHED, 1 NOT_AN_EXTENSION, 11 pages scanned (up from 8 hand-listed, with no new shapes).

The original finding, reproduced before any of this was written:

readWorkforce:           workers: []                           errors: []   ← silent
readResourcesDirectory:  documents: ["workers/build/runbook"]  errors: []   ← the document loads
readChannelsDirectory:   channels: []                          errors: []   ← silent
How the table is derived

Docs → code, never code → code. Originally by hand; now the same extraction runs as a standing check:

  1. Read every .md under PUBLISHED_DIRECTORIES, plus the package README.
  2. Reassemble paths from indented tree fences (a fence spells one path across many lines — the reason a regex alone missed them the first time), and scan prose and tables for inline tokens.
  3. Reject what isn't a path by shape: a shape ends in a file, so a ref and a folder mention drop out. Nothing is rejected for being unfamiliar.
  4. Normalize by structure: a segment the convention fixes stays literal, a segment the author names becomes the placeholder its parent slot implies, and an unrecognized segment stays spelled as itself so it fails by name.
  5. Pull every file extension the pages name in a backtick span.
  6. Require a row for each, or an entry in PROSE_PUBLISHED / NOT_AN_EXTENSION carrying a reason.
  7. Write all eighteen into one tree and run every reader over it, so a shape is judged against the whole package rather than the one reader you'd have thought to ask.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ULydJv3JEeMUgeZbSvm4Rt

`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
@vercel

vercel Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-ui Building Building Preview Sep 18, 2026 12:05pm UTC
2 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 18, 2026 12:05pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 18, 2026 12:05pm UTC

Request Review

@linear-code

linear-code Bot commented Sep 18, 2026

Copy link
Copy Markdown

FIX-1421

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Fix All in Cursor

❌ 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

Copy link
Copy Markdown
Collaborator Author

Did the check you asked for — each publishedIn quote read in context, not grepped. Thirteen carried over clean, and I re-read the three new ones against capabilities-on-disk.md:45 in full. Two are sound. The third has a composition gap that isn't worth another round, but is worth writing down.

org/resources/<name>.ts ← "A capability lives at the organization level or in a team." Names the org level directly. Clean.

teams/<t>/workers/<w>/resources/<name>.ts ← "A plain resource there is fine…", where "there" resolves to the preceding sentence's "inside a single worker's own resources/ folder". Clean.

org/workers/<w>/resources/<name>.ts ← same quote, and this row's claim spans two files while citing one. That sentence is generic over workers — it never says team worker — so it does cover an org worker's folder. But it only covers the .ts-is-a-plain-resource half. That an org worker's resources/ folder is a published place at all comes from documents-on-disk.md:83 / README.md:560, which this row doesn't cite.

So the failure mode: if someone later removes org workers from documents-on-disk.md, this shape stops being published, and the citation guard stays green because the sentence it watches is in a different file and still says what it always said. The guard re-checks a quote, not a composition — which is fine for fifteen rows and not quite right for this one.

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

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-18T11:48:31.278832Z d043f57 Draft marked ready
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. Two products in one PR. The controlTools → DYNAMIC_KEYS fix, 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 while main was red, but for reviewers the mental model is easier when the classification fix is already on main and this PR is detector-only. Not a merge blocker from here.

  2. 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 to published-tree-surface.test.ts; keep the long rationale only where the allowlists live.

  3. Small harness DRY (optional). Duplicate doc-quote loops (shapes vs WORKER_REFS_RESOLVE), duplicate for (const shape of PUBLISHED_SHAPES) await shape.write(root) in two tests, and the same documents-on-disk table row cited both on the org-worker-resources shape and in WORKER_REFS_RESOLVE — all easy tidy-ups without weakening the guard.

  4. readEverything cost (test-only). readWorkforce already walks readSeatSkills per worker; the harness calls readSeatSkills again for alpha.lead by design. Fine at 16 shapes × 2 tests; if the table grows, consider a shared writeAllPublishedShapes + maybe one cached readout per test file — not worth refactoring preemptively.

  5. workerFromRef in the test. Mirrors minting rules without sharing mintResourceRef / 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/workforce/src/loader/index.ts Resolved
* 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 mintResourceRef instead of workerFromRef: 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.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

Copy link
Copy Markdown
Collaborator Author

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 controlTools classification, the module header and the fence regression test are on main. The diff against current main:

packages/workforce/src/loader/index.ts             |  13 +
packages/workforce/test/published-tree-surface.test.ts | 525 +++++++++++++++++++++
2 files changed, 538 insertions(+)

So your point 1 resolved itself — the classification fix is already on main and this PR is detector-only, which is the mental model you asked for. And the seat-capabilities.ts:116 comment about quoting exact it("…") titles is no longer about this PR; that line lives on main now.

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 publishedIn does for doc sentences. The seat-capabilities.ts comment has no such check, so it can rot quietly — that's the real defect, not the quoting. Worth fixing on main with a checked citation rather than vaguer prose. Not folding it here, since the file isn't in this diff.

The three live ones — all fair, none pushed. writeAllPublishedShapes to DRY the two write loops; a shared constant for the documents-on-disk row cited twice; and a one-line note on Readout.teamSeatSkills that the second readSeatSkills is deliberate. They stay as they are and ride the next push that already touches these files — I'm not starting a push for optional findings on an approved, green PR, and a bare re-push would cost a CI cycle for no behaviour change.

The teamSeatSkills note is the one I'd most want, for a reason this epic keeps proving: a future reader "optimizing away" a deliberate second read is exactly how coverage narrows without anything going red.

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: workerFromRef mirrors the minting rules without sharing the production helper, and it will drift if FIX-1414 moves those rules. FIX-1414 is the owner of the one unresolvable ref this suite pins, so whoever takes it should expect to touch both.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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
@jhoffner
jhoffner merged commit cb83589 into main Sep 18, 2026
12 checks passed
@jhoffner
jhoffner deleted the fix/FIX-1421-loader-silent-accept branch September 18, 2026 17:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants