Repository navigation
A reference is read from its file; its reach comes from the tree (FIX-1467) - #1958
Conversation
`references/` joins `resources/` at the same four levels, minted into the same namespace by the same rule. What differs is what the document is afterwards, and both halves of that are the point. D1 — the read path. A reference installs as `contentFile` + `writable: false` + `llmWritable: false` + a `render` that strips the file's frontmatter. The seal is what makes the read path work rather than decorate it: a stored row beats `contentFile` exactly as it beats `content`, so unsealed it would be a first-boot seed with a longer name. All three keys are DERIVED and refused in frontmatter, so there is no key an author can forget. The handle still carries `writeContent` — that is a runtime refusal, not an absent verb, and `references-from-docs`'s header says so in as many words rather than letting a weaker guarantee ship under a stronger word. The frontmatter strip is not cosmetic. `contentFile` hands the engine the raw bytes, so without `render` every prompt would carry the YAML block. The tests assert bodies with `toBe` for exactly this reason. D2 — the wall. A seat reaches the references at or above its place in the tree: the org's, its own team's, its own folder's. Not a sibling team's, not a teammate's. Derived from the loader-minted ref and the loader-minted seat id, never from anything a seat wrote; an explicit `references:` list narrows within it and is refused if it names anything outside. Checked again on the MINTED instance, because a reference a block also declares merges back after the seat's map replaces the flow-level one. BR-19 — the migration, which would otherwise ship silently. Sealing stops new writes and cannot evict a row already there, so a handbook written before the move stays shadowed forever. `clearShadowedReferences` finds those rows, reports each with the body it had been serving, and clears them. Idempotent, `dryRun`-able, never touches a `resources/` row. `resources/` is unchanged. Its reader, records, install and reach are byte for byte as they were — `read-resources-directory.test.ts` and `seat-resources.test.ts` pass untouched, which is the evidence for it. The one place that slipped (a `filePath` on every record) was caught by that suite and narrowed to references only. Evidence: 670 tests pass in workforce (36 new, real path: tree on disk -> loader -> hire -> live execution context). Four mutations confirm each mechanism is load-bearing — removing the seal reds 3, the frontmatter strip 11, the wall 4, the migration's delete 1. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
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. |
…es-read-path # Conflicts: # apps/docs/docs/workforce/documents-on-disk.md
|
FSD Architect — coherence / approach on the write-verb fork. Not owner merge approval. Write-verb fork — ship this; file absent-verb as its own issueD1’s load-bearing ask was: no forgotten key restores the write path, and the disk file stays the source. This PR meets that with a stronger seal than per-file
That closes the reachable write hole. The handle still carrying Flip later if: a W5 surface is called by code you don’t control where a compile error is the only stop. Not today’s bar. Deviations — agree
Follow-up to file (not a D-n)
No two-direction vs #1957 locks. No D-n. — FSD Architect |
There was a problem hiding this comment.
Simplify / architecture read
Verdict: The product split (references/ = file-backed + tree wall vs resources/ = mutable row + install filter) is the right fix for the two failure modes in the PR description. I do not see a materially simpler approach that closes both holes without giving up one of them. Staying on resources/ + app-side filters does not fix ambient cross-team reads; sealing only in frontmatter does not fix shadowed rows or a trustworthy wall.
What already simplified well: readDocumentSlot (one walk, two slots) is the main win in this diff — a second reader would have been the obvious over-build. Extracting describe-value.ts for the two seat modules is appropriate.
Where complexity is real (mostly justified): ~500-line seat-references.ts beside seat-resources.ts looks heavy, but the semantics diverge enough (modes vs no modes, grant vs derived wall, absent vs ambient) that a merged “seat permissions” module would trade line count for constant which key? branching. Keeping them siblings matches the existing boundary pattern.
Follow-ups worth considering (non-blocking if you fix the guard below):
referenceKeys/documentKeys— same name-or-identity union with a small behavioral fork in the catalog loop; a shared internal helper (or one property test) would reduce drift risk.placeOfReferencevsmintResourceRef— inverse grammar lives only inseat-references.tswhile mint lives inloader/resource-convention.ts; colocating parse+mint in the loader module would make theworkers-as-document-name case easier to keep in sync (your header already calls this out as the subtle case).- Boot-only: hoist
referenceKeys(catalog, kindResources)outside the per-worker loop inhire.tswhenoptions.referencesis set;verifySeatReferenceWallcould reuse a hoisteddefinitionsset too. - Tests:
references-convention.test.tsis thorough (good); pullingtree()/ fixture writers into a shared test helper would shrink noise without losing BR traceability.
Alternatives I considered and would not take instead:
- Single map +
slotmetadata only — slightly smallerhireWorkforceAPI, but blurs install halves and makes collision/refusal harder to reason about at each door. - Blocking on core
ReadOnlyResourceRef— cleaner types, does not remove tree wall / migration / loader work; I agree with your recommendation to ship the seal + file path now and file absent-verb separately unless you have an external caller that must get a compile-time guarantee immediately. - Third-party path library — ref grammar is workforce-specific; unlikely to help.
Write-verb contract (item 1 in the PR): No objection to shipping as-is; the derived-key refusal story is the right workforce-layer answer until core widens DeclaredResourceEntry.
Requesting changes — process guard
Locally, pnpm --filter @flow-state-dev/workforce test is 669 pass / 1 fail: test/published-tree-surface.test.ts — “has a row for everything the published pages declare”. The updated documents-on-disk.md tree/examples surface four references/ path shapes that are not in PUBLISHED_SHAPES:
org/references/code-of-conduct.mdteams/<team>/references/handbook.mdteams/<team>/references/escalation.mdteams/<team>/workers/<worker>/references/runbook.md
The PR evidence block says all process guards are clean; this one needs matching rows (same pattern as the existing resources/ entries) or a doc tweak so extraction does not publish shapes the table does not cover.
Docs: Acknowledged that docs-writer / docs-editor did not run; separate from the guard above, but still worth that pass before merge.
Once published-tree-surface is green, I am comfortable with the direction of the change set; the remaining simplify items above are polish / follow-up, not a rethink of the approach.
Sent by Cursor Automation: Review For Best Approach
| workforce/ | ||
| org/ | ||
| resources/ | ||
| references/ |
There was a problem hiding this comment.
These references/ paths are now picked up by published-tree-surface.test.ts extraction, but PUBLISHED_SHAPES in packages/workforce/test/published-tree-surface.test.ts still has no matching rows (only resources/ shapes). That leaves the process guard red — same fix pattern as the existing teams/<team>/resources/<name>.md entries: add four shapes + write/accountedFor hooks, or narrow the doc examples so they are not published as canonical tree shapes.
| // anything. What keeps that from touching an app with no references is the | ||
| // wall itself: a kind holding none hands `base` straight back, including | ||
| // handing back `undefined` so the seat is minted with no map at all. | ||
| const wall = applyReferenceWall({ |
There was a problem hiding this comment.
Nit (boot only): applyReferenceWall → referenceKeys rebuilds the same Set for every seat on the kind. When options.references is defined, hoisting referenceKeys(options.references, kindResources) once per kind before the worker loop would be a small clarity/perf win without changing behavior. Optional for this PR.
| * @returns Where its file sits, or `undefined` if the ref is not a shape the | ||
| * convention mints. | ||
| */ | ||
| export function placeOfReference(ref: string): TreePlace | undefined { |
There was a problem hiding this comment.
This parser is the inverse of mintResourceRef in loader/resource-convention.ts (including the workers segment edge case). Not wrong to keep reach logic next to the wall, but if you want to reduce long-term drift risk, consider moving placeOfReference / TreePlace next to the minter and importing from both loader + hire paths — follow-up is fine if you are confident in the new tests.
| import path from "node:path"; | ||
| import { readChannelsDirectory } from "./read-channels-directory"; | ||
| import { readResourcesDirectory } from "./read-resources-directory"; | ||
| import { readReferencesDirectory, readResourcesDirectory } from "./read-resources-directory"; |
There was a problem hiding this comment.
Simplify note (optional / follow-up): roster now runs readResourcesDirectory and readReferencesDirectory serially — two full structural walks. Acceptable at expected tree sizes and consistent with the “no fourth walk” comment, but if boot ever hurts, a single walk that emits both slots would be the next consolidation (bigger than this PR needs).
There was a problem hiding this comment.
Code Snob — outcome 3: already tight. No POC.
Read seat-references.ts against seat-resources.ts, references-from-docs.ts against resources-from-docs.ts, clear-shadowed-references.ts, manifest.ts (DERIVED_REFERENCE_KEYS), hire.ts, the parameterized walk in read-resources-directory.ts (readDocumentSlot + readReferencesDirectory), read-declared-roster.ts (collision), resource-convention.ts, discover-resource-modules.ts, describe-value.ts, index.ts, test/references-convention.test.ts, documents-on-disk.md, and the workforce README.
The contract is four things that have to stay distinct: a reference is its file (contentFile + derived seal + frontmatter render); reach is derived from the minted ref and the minted seat id; resources/ is byte-for-byte as it was; and a row written before the move is reported and cleared, not hoped away. The walk is already one function with a slot. The two install halves and the two seat modules answer different questions (seed-a-row vs file-is-source; modes-and-no-wall vs wall-and-no-modes). A rewrite that merged them would add a branch on which key you were called for, not remove a type.
Rejected subtractions:
- Share
passthroughFrom/refusedDeclarationMessagebehind a keys argument — the sets are not interchangeable, and BR-13 exists because widening the shared list would breakresources/. The reference wording also tells you to move the file; the resource wording does not. - Fold
seat-referencesintoseat-resources— every branch would ask which key it was. That is larger. - Collapse
TreePlaceinto prefix matching — same reachability, loses theworkers-as-a-document-name totality, no contract shrink. - Unexport
placeOf*/TreePlace— hire still computes them; one line inindex.tsis not a smaller wall. - Drop
describeShadowedReferences— it is the documented deploy-log sentence. - Strip the seal header — the PR already named it as the anti-overclaim guard.
Not re-litigated: ship-now vs hold for an absent writeContent verb; keeping the resources: filter (S6); leaving labs and kitchen-sink unmigrated (S7); ambient reach always-on.
Leftovers left alone: absent-verb as its own issue, the labs follow-up, the isolated docs-writer pass.
Sent by Cursor Automation: Code Snob
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 c315362. Configure here.
| if (parts.length < 3) return undefined; | ||
| team = parts[1]; | ||
| rest = parts.slice(2); | ||
| } |
There was a problem hiding this comment.
Org reference named teams is unreachable
Medium Severity
placeOfReference treats a single-segment ref teams as a broken teams/ path and returns undefined, so the wall marks it unreachable. mintResourceRef still mints that ref for org/references/teams.md, and validateSegment allows the name. An org-level handbook named teams installs, then reaches no seat.
Reviewed by Cursor Bugbot for commit c315362. Configure here.
| for (const ref of references) { | ||
| const place = placeOfReference(ref); | ||
| if (place !== undefined && referenceReachableBySeat(seat, place)) reachable.add(ref); | ||
| } |
There was a problem hiding this comment.
Alias keys widen reference reach
Medium Severity
referenceKeys correctly treats an aliased definition as a reference, but applyReferenceWall then places that alias by its accessor key rather than the definition's minted ref. A single-segment alias of a team or worker handbook parses as org-level, so every seat can read it.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit c315362. Configure here.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c3153620cb
ℹ️ 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".
| for (const ref of references) { | ||
| const place = placeOfReference(ref); | ||
| if (place !== undefined && referenceReachableBySeat(seat, place)) reachable.add(ref); |
There was a problem hiding this comment.
Derive reach from canonical refs, not accessor aliases
When a flow exposes references["teams/sales/handbook"] under an alias such as handbook, referenceKeys returns the alias and this loop passes that alias to placeOfReference; the one-segment alias is classified as an organization-level reference. An engineering seat therefore retains the aliased sales handbook, and the post-mint check accepts it because allowed also contains the alias. Resolve each accessor back to its catalog ref before evaluating reach so aliases cannot bypass the team/worker wall.
Useful? React with 👍 / 👎.
| for (const ref of Object.keys(references)) { | ||
| checked.push(ref); | ||
| // The ref IS the storage key for a file-declared document: `resourcesFromDocs` | ||
| // and `referencesFromDocs` both pass it as `ref`, and the registry keys | ||
| // content by it. | ||
| const shadowedContent = await content.get("org", orgId, ref); |
There was a problem hiding this comment.
Resolve the actual resource scope before clearing
When the former resources/ document used flowIsolation: true (or inherited an isolated org scope from its flow), the engine stores its content under the instance-qualified scope id, not the raw orgId used here. This lookup then reports no shadowed row and the stale stored body continues to win over the reference file; shared org IDs containing : or \ also require the engine's scope-key encoding. The migration needs the flow/resource storage coordinate rather than assuming orgId is the content-store scope id.
Useful? React with 👍 / 👎.
| workforce/ | ||
| org/ | ||
| resources/ | ||
| references/ |
There was a problem hiding this comment.
Register the new reference paths in the surface guard
Publishing these references/ paths without extending PUBLISHED_SHAPES and the path normalizer leaves the package test suite red. Running pnpm --filter @flow-state-dev/workforce test fails published-tree-surface.test.ts and lists four untabled shapes, including org/references/code-of-conduct.md; add coverage rows for the newly supported slot so the convention guard recognizes and exercises it.
Useful? React with 👍 / 👎.
| return ( | ||
| `references: ${result.cleared.length} of ${result.checked.length} were shadowed by a ` + | ||
| `stored write and have been cleared — ${result.cleared.map((r) => r.ref).join(", ")}. ` + | ||
| `Each now serves its file again.` |
There was a problem hiding this comment.
Preserve dry-run state in the migration result
After clearShadowedReferences({ dryRun: true }), the returned result is indistinguishable from a real migration, so the documented describeShadowedReferences(result) path prints that rows “have been cleared” and each reference now serves its file even though no deletion occurred. An operator can consequently treat a preview as a completed migration and leave stale content active; carry the dry-run status or report prospective rows separately.
Useful? React with 👍 / 👎.
jhoffner
left a comment
There was a problem hiding this comment.
second-look: PR #1958
Verdict: Appropriately scoped, with a small amount of trimmable duplication. Scope: +2146 / −58 across 17 files (packages/workforce, one changeset, docs).
This is an unusually self-aware PR — the header comments in seat-references.ts, references-from-docs.ts, resource-convention.ts, and manifest.ts each pre-argue the obvious "why not merge/simplify this" objections (why a sibling module instead of a shared one, why the seal is derived rather than authored, why resources/ stays untouched), and the PR description itself already surfaces the one real open fork (the write-verb contract) with a recommendation rather than deciding it silently. I'm not re-litigating that fork or D1/D2, both already ratified at spec review — per pr-reviewer-guidance.md's implementation-PR row, that's a decided direction, not something automated review should reopen.
What I did find, scoped to what this PR already touches:
| # | Finding | Lens | Recommendation | Est. Δlines | Sev | Conf |
|---|---|---|---|---|---|---|
| 1 | Sibling-slot-path ("swap resources/↔references/ in a path") computed two independent ways, in two files, neither of which is resource-convention.ts — the module this PR itself designates as the single source of truth for the two slots |
Architecture (opportunistic) | Extract one siblingSlotPath() helper into resource-convention.ts |
~0 net (consolidation, not reduction) | Med | High |
| 2 | prefetchMode === "lazy" refusal block duplicated byte-for-byte between refusedDeclarationMessage and refusedReferenceDeclarationMessage in manifest.ts |
YAGNI/duplication | Extract shared refusedPrefetchModeMessage() |
~0 net | Low | High |
| 3 | ApplyReferenceWallInput.kind is documented and plumbed through from hire.ts but unused inside applyReferenceWall's own body — only the separate VerifySeatReferenceWallInput.kind is actually read |
YAGNI | Drop the field, or confirm it should feed a message and wire it in | small | Low | High |
None of these clear second-look's usual "meaningful net removal" bar on line count alone — I flagged them anyway because they're concrete, verified against the code (not eyeballed), and land exactly on the seam this PR is already responsible for (the two-slot convention, the reference-declaration refusal, the wall's own inputs), which is what "opportunistic" architecture cleanup means here rather than a scope expansion.
Considered & deemed justified
- A whole parallel
seat-references.ts(492 lines) instead of extendingseat-resources.ts— the module's own header lays out the real behavioral differences (modes vs. no modes, narrows-within-a-derived-wall vs. plain narrows) and argues a merged function would branch on which key it was called for throughout. Kept. ResourceDoc.filePathas a new optional field carried by every record, not just references' — justified inmanifest.ts's doc comment as "one walk that records provenance beats two walks that disagree about whether to"; only references actually consume it, but the field costs one line and avoids a second walk. Kept.- The write-verb-can't-be-removed-from-the-type gap (
ResourceRef.writeContentstaying a required member) — this is the PR's own explicitly-flagged fork with a stated recommendation ("ship now, file absent-verb separately"), not something for automated review to reopen. - Four small helpers exported from the package index with no current consumer (
placeOfReference,placeOfSeat,referenceReachableBySeat,TreePlace) — real, but the export block is a handful of lines; didn't clear the calibration bar for a standalone finding.
Posted by the second-look skill — a retrospective approach/bloat review, not a correctness pass. Findings are for triage, not blocking.
Generated by Claude Code
| const referenceSlotPath = `${slotPath.slice(0, -RESOURCES_SLOT.length)}${REFERENCES_SLOT}`; | ||
| const siblings = await openStructuralDirectory( | ||
| path.join(path.dirname(slotDir), REFERENCES_SLOT), | ||
| referenceSlotPath, | ||
| ); |
There was a problem hiding this comment.
second-look (architecture, opportunistic): referenceSlotPath is derived by string-slicing the trailing resources off slotPath and appending references:
const referenceSlotPath = `${slotPath.slice(0, -RESOURCES_SLOT.length)}${REFERENCES_SLOT}`;read-declared-roster.ts's collidingRefs (lines ~222–228) needs the exact same fact — "the sibling of this path in the other slot" — and computes it a second, independently-written way, via path.sep-aware String#replace:
reference.filePath.replace(
`${path.sep}${REFERENCES_SLOT}${path.sep}`,
`${path.sep}${RESOURCES_SLOT}${path.sep}`,
)resource-convention.ts is this PR's own answer to "where do the two slots disagree" — its header says explicitly that resources/ and references/ must not be spelled two different ways across doors, which is exactly why RESOURCES_SLOT/REFERENCES_SLOT/mintResourceRef live there as a single source of truth. This one derived fact (swap the slot segment in a path) now has two ad hoc implementations outside that module instead of one function in it — and the slice-based one is the fragile half: it silently assumes slotPath ends in exactly resources with no trailing segment, which happens to hold today only because of how slotPath is built at each call site.
Concrete alternative: add one small helper to resource-convention.ts, e.g. siblingSlotPath(p: string, from: DocumentSlot, to: DocumentSlot, sep = "/"), and have both call sites use it. Net effect is close to a wash in raw line count, but it collapses two independently-maintained "swap the slot" implementations (one of them assumption-fragile) into the one module this PR itself designates as the place that must not disagree — worth doing given this PR is already touching both files for this exact concern.
Generated by Claude Code
| const sibling = | ||
| reference.filePath === undefined | ||
| ? reference.ref | ||
| : reference.filePath.replace( | ||
| `${path.sep}${REFERENCES_SLOT}${path.sep}`, | ||
| `${path.sep}${RESOURCES_SLOT}${path.sep}`, | ||
| ); |
There was a problem hiding this comment.
second-look (architecture, opportunistic): second half of the sibling-path duplication — see the comment on discover-resource-modules.ts:274. This path.sep-based replace and that slice-based concatenation compute the same derived fact ("this path's sibling in the other slot") two different ways in two different files, neither of which is resource-convention.ts — the module this PR's own header names as the place the two slots' conventions must not drift apart.
Generated by Claude Code
| if (declared["prefetchMode"] === REFUSED_PREFETCH_MODE) { | ||
| return ( | ||
| `declares \`prefetchMode: "${REFUSED_PREFETCH_MODE}"\`, which a file-declared ` + | ||
| `resource cannot be: it is installed at flow level, and a flow-level declaration ` + | ||
| `has no per-block load trigger to load it on. Drop the key.` | ||
| ); | ||
| } |
There was a problem hiding this comment.
second-look (YAGNI/duplication, minor): This prefetchMode === REFUSED_PREFETCH_MODE block is byte-for-byte identical to the one in refusedDeclarationMessage (lines 581–587) — same condition, same message text, copy-pasted rather than shared.
refusedReferenceDeclarationMessage's own doc comment already frames itself as "refusedDeclarationMessage's rule over the wider DERIVED_REFERENCE_KEYS set" — but it re-implements the prefetch check instead of delegating to it. A future wording change to the prefetch refusal now has to remember to touch both functions, which is the exact "two doors disagreeing" failure mode this PR's own comments warn about elsewhere (e.g. the resource-convention.ts header).
Concrete alternative: pull the prefetch check into its own small refusedPrefetchModeMessage(declared) in this file and call it from both functions after their respective derived-key loops. (The derived-key loops themselves can't be trivially merged — the reference-flavored message text differs from the resource one — so this is scoped to just the duplicated tail.) Net line delta is close to zero; the value is removing the literal duplicate, not shrinking the file.
Generated by Claude Code
| */ | ||
| base: DeclaredResources | undefined; | ||
| /** The kind's name, for the refusals. */ | ||
| kind: string; |
There was a problem hiding this comment.
second-look (YAGNI, minor): ApplyReferenceWallInput.kind ("The kind's name, for the refusals") appears to be unused inside applyReferenceWall itself (lines 352–421) — none of the messages it can return (seatHasNoPlaceMessage, parseSeatReferences's problems, unreachableSeatReferenceMessage) take a kind argument. Only the separate VerifySeatReferenceWallInput.kind (line 459), consumed in verifySeatReferenceWall via referenceCrossedWallMessage(key, seatId, kind), is actually read.
hire.ts passes kind into the applyReferenceWall({...}) call, so the field isn't just dead in isolation — it's plumbed through from the caller for no effect. Worth double-checking this wasn't meant to flow into one of the wall's own refusal messages (e.g. unreachableSeatReferenceMessage naming the kind alongside the seat id); if it's genuinely unneeded there, dropping it from ApplyReferenceWallInput (and its doc comment) removes a parameter callers have to supply that the function ignores.
Generated by Claude Code
… bucket Review found four real defects, three of them in the wall and the migration — the two mechanisms with no prior art here and the least test surface inherited from `resources/`. Each fix has a check that fails without it. **The wall could be widened by an alias.** `applyReferenceWall` placed an entry by its ACCESSOR KEY, so an app exposing a team handbook under a second, single-segment key got an org-level reading and handed it to every seat in the company. Placement now comes from the definition's minted `ref`, which the loader derived from the path; an entry with no readable minted ref is unreachable rather than org-wide. `verifySeatReferenceWall` re-derives the place itself instead of asking whether the key is in `allowed` — asking that made the verification agree with the bug it exists to catch. **A reserved segment is still a legal document name.** `org/references/teams.md` mints the bare ref `teams`, which parsed as a broken `teams/` path and reached nobody. Fixed as a class, not two cases: a ref's shape is fixed by how many segments it has, so a single segment is an org document whatever it spells. **The migration looked in the wrong bucket.** A resource's row is not keyed by the bare org id. An installing flow that isolates its org scope stores under `<orgId>:<flowId>`, so the old lookup found nothing and reported success while the stale body kept winning — BR-19 failing in the exact mode BR-19 exists to prevent. `installedOn` is now required, so the coordinate is stated rather than guessed. Where the engine's private per-component escaping would apply (an id holding `:` or a backslash) this THROWS rather than reading the wrong cell; duplicating that escape would put one fact in two places. `flowIsolation` joins the derived-and-refused set for a reference, which is what makes the bucket knowable: a per-instance copy of a file that nothing can write is incoherent, and allowing it would make "where does this live" a per-file question. **A dry run said the work was done.** `dryRun` now rides on the result, and `describeShadowedReferences` says "WOULD be cleared" for a preview. A preview that claims completion is worse than no preview. Also: four `PUBLISHED_SHAPES` rows, because the docs publish `references/` shapes and that guard is what caught the PR body claiming clean guards when one was red. `siblingSlotPath` in `resource-convention.ts` now owns "this path's sibling in the other slot", which two files were deriving two different ways — the slice-based one silently assumed a trailing slot segment. The duplicated `prefetchMode` refusal is one helper. `ApplyReferenceWallInput.kind` is gone: none of that function's refusals names a kind, so callers no longer supply something it ignores. Docs move with the signature. The `clearShadowedReferences` example in `documents-on-disk.md` and the README both showed the old three-argument form, which no longer compiles and which demonstrated exactly the silent-miss this commit fixes. Both now pass `installedOn` and say why it is not defaulted. Evidence: 680 pass / 41 files in workforce, after merging main. Both new fixes mutation-checked — placing by accessor key reds the alias case, dropping the length-first rule reds the `teams` case. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
Rewrites `documents-on-disk.md` and the workforce README's document section around what a developer has to decide: which folder a document belongs in, who can change it afterwards, and which seats reach it. The trade-off is stated flat — a reference changes by editing the file and deploying, a resource can change from inside the product — with the ref rule, the reader API and the install call covering both folders once instead of twice. Three corrections where the prose had claimed more than the code does: - The both-slots name collision is not caught by either directory reader; neither sees the other folder. `readDeclaredRoster` collects it in `problems` on the reference layer, and `hireWorkforce` throws for a catalog built by hand. - Automatic reach holds only once the map reaches `hireWorkforce` as `references`. Spreading it into the flow and omitting the hire option leaves every entry an ordinary document, and a seat that declares `references:` is refused. That is the silent one, so it is stated where the install call is made. - Seats are minted only from `teams/<team>/workers/<name>/`, so a document under `org/workers/<name>/references/` sits above no seat and is reachable by nobody. Also fixes a pre-existing broken anchor in `workers-on-disk.md`, which pointed at a heading that no longer exists on the documents page. Docs site builds warning-free: no broken links, no broken anchors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
The wall had a silent off-switch. `applyReferenceWall` derives reachability
against the catalog the app passes as `hireWorkforce({ references })`, and
`referenceKeys` returns empty when that is absent — so an app that spread
`referencesFromDocs(...)` into its flow and forgot the hire option got D1
intact (the seal rides on the definition) and D2 gone: nothing recognised as a
reference, the wall applied to nothing, every seat reaching every team's
handbook, and no warning anywhere.
That is this issue's own problem statement one level up. The change opens by
naming a wall that exists only as a line the app remembers to write, with
nothing said when it is missing; shipping a wall whose absence is equally
silent would hand the same failure to the next author, in a shape that looks
safe because the folder is called `references/`. D2 was ratified as "there is
no install-side override, because one would make the wall optional again", and
omission is an install-side override wearing a different hat.
Refused at hire, naming the option. A partial catalog is refused by the same
check and for the same reason: one unrecognised reference is one document the
wall does not cover.
**Reference definitions are distinguishable at hire, and the discriminator is
`render === referenceBody` — identity, not shape.** That fact is load-bearing
for anyone who later touches `references-from-docs`: it is the only thing that
attaches that exact function, so identity answers "did this convention build
it?" A shape test (`contentFile` set, both write flags false) would read a
hand-written sealed file-backed resource as a reference and refuse an app whose
wiring is fine. A brand field was rejected for the reason the convention
rejects every other marker — a second place the same fact lives, and one a
hand-built entry could set. Probed before building on it: `render` survives
`defineResource` by identity.
## The published-surface guard, fixed in its extraction rather than its rows
Both of its failures were the guard not understanding the convention:
- `RESERVED` and the leaf normalizer now read `DOCUMENT_SLOTS` from
`resource-convention`, so a file under `references/` normalizes to
`<name>.md` exactly as one under `resources/` does. Half the convention's
shapes were being spelled as whatever a page's example happened to call them.
- The README states the ref rule once as `<root>/org/<slot>/<name>.md` rather
than writing every level twice. `<slot>` is a notation, not a folder, so a
shape carrying it now expands into both slots before comparison. Read
literally it was a folder nobody implements. Expanding also makes the check
stricter: one generic sentence is verified against each slot separately.
Four `references/` rows follow, one per level — including
`org/workers/<worker>/references/<name>.md`, which reaches nobody, because no
seat is minted below an org worker's folder. Tabled anyway: the pages publish
the shape, and a shape that reaches nobody is exactly what this suite must not
pass over.
## Documentation, in the same commit because it is the same fact
Three pages move with the behaviour, written by the isolated docs pass rather
than by this change's author. Four passages had documented the silent fallback
— two in `documents-on-disk.md` and the README, one in `workers-on-disk.md`
that this change had missed entirely — and all four now state the requirement
in the present tense, with the failure shown, so no reader learns it once
worked differently. The install snippet runs end to end, sample refs are
whole, and the read-only failure leads with `resource_read_only`.
Evidence, re-run after the pages landed rather than before: 685 pass / 41
files, workforce and CLI typechecks clean, CLI 246 pass, five process guards
clean. The refusal is mutation-checked — tolerating the missing catalog reds
all three of its cases, and they assert the negative (an app that omits the
option is refused, not quietly hired).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
…3422) * fix(FIX-1470): define green as the CI check run on the current head PR #1958 opened on a head that conflicted with main, and GitHub starts no pull_request workflow while a PR conflicts with its base. Its check list held only third-party checks, all passing. Separately, the combined commit status reads success (Vercel's skipped builds) on a head whose `Typecheck & Test` check run failed. The epic-wake scan was told only "report whether CI is failing", leaving the surface to the reader. It now names the `Typecheck & Test` check run, rules out the combined status, and treats a head with no run as untested rather than green. The Gates section of orchestration.md carries the definition. The branch-protection half (a required status check on main) is a repo setting this change cannot make. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DME8pzA4e4Rc7fRLGsYavW * fix(FIX-1470): shorten the CI scan line, leave the rationale to Gates Folds the Cursor review suggestion from POC PR #3438 (commit 7e44c47). The scan line keeps every operative rule: read the `Typecheck & Test` check run on the current head, never the combined commit status; ciFailed when it concluded anything but success; no run means untested, readyToMerge false. The "why" stays in orchestration.md -> Gates. Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DME8pzA4e4Rc7fRLGsYavW * fix(FIX-1470): ciFailed reads every CI check run, not only Typecheck & Test `Typecheck & Test` needs only the typecheck and test jobs, so Docs Site Build, Process guards, Knip and the rest could fail with ciFailed false and PR_FEEDBACK would never dispatch a fix. Green still means a successful `Typecheck & Test` run on the current head (missing means untested, readyToMerge false, not ciFailed); ciFailed is now any CI check run on the current head concluding failure, a cancelled run superseded by a later success aside. orchestration.md -> Gates matches. Addresses Greptile review comment 4277383095. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DME8pzA4e4Rc7fRLGsYavW * fix(FIX-1470): a failing check withholds the merge gate; only a check's latest run counts A scout could report readyToMerge and ciFailed together (Typecheck & Test passed, another check failed), and the wake offered the merge while dispatching pr-feedback for the failure. The refresh now forces readiness false on any current-head CI failure for the row, each sub-PR, and the repair PR (new optional repairCiFailed scan field). ciFailed now counts only each check name's latest completed run, so a failed or cancelled attempt a rerun turned green no longer keeps a recovered PR failing. Scan prompt and orchestration.md Gates updated to match. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DME8pzA4e4Rc7fRLGsYavW --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Cursor Agent <cursoragent@cursor.com>




A company handbook in a workforce tree has two quiet failure modes today, in opposite directions.
It stops being the file. A
resources/*.mddocument seeds a stored row on first boot, and after anything writes that row once, the row is the source forever. The file in the repository looks authoritative and reaches nobody. Nothing reports it.It reaches the wrong people. An ordinary seat with no grant list reads another team's handbook. The only wall is a filter line the app remembers to write; when it is missing, nothing warns and nothing logs.
What this does
references/joinsresources/at the same four levels of the tree, minted into the same namespace by the same rule. What differs is what the document is afterwards.references/resources/D1 — the read path. A reference installs as
contentFile+writable: false+llmWritable: false+ arenderthat strips the file's frontmatter. The seal is what makes the read path work rather than decorate it: a stored row beatscontentFileexactly as it beatscontent, so unsealed this is a first-boot seed with a longer name.writable,llmWritable,renderandflowIsolationare all derived by the folder and refused in frontmatter, so there is no key an author can forget.D2 — the wall. Reach is derived from the definition's loader-minted
refand the loader-minted seat id — never from an accessor key an app chose, and never from anything a seat wrote. An explicitreferences:list narrows within the wall and is refused if it names anything outside it. Width comes only from moving the file up the tree.And the wall cannot be switched off by omission. It is derived against the catalog passed as
hireWorkforce({ references }), so an app that spread the map into its flow and forgot the hire option would get D1 intact and D2 gone — every seat reaching every team's handbook, silently. That is this change's own problem statement one level up, so it is refused at hire, naming the option. A partial catalog is refused the same way.BR-19 — the migration. Sealing stops new writes but cannot evict a row already there, so a handbook written before the move stays shadowed forever.
clearShadowedReferencesfinds those rows, reports each with the body it had been serving, and clears them. It takesinstalledOnrather than assuming the storage address, and throws rather than guessing where the engine's own escaping would apply.resources/is unchanged. Its reader, records, install and reach are byte for byte as they were.What's asked of you
Nothing is open. Both forks raised in review have been answered, recorded here so a reviewer arriving now does not re-litigate them.
The write-verb contract — decided: ship as built, absent-verb deferred. The Architect's review asked for "no write verb", explicitly not
writable: false. That could not be built here, and the weaker thing was not substituted under the stronger word:DeclaredResourceEntryadmits onlyDefinedResource | DefinedResourceCollection(core/src/types/block.ts:984).ResourceRefdeclareswriteContentas a required member (core/src/types/resource.ts:457) — contrastedges?, optional by design.What ships closes the reachable write hole: code calling
writeContent()is refused at the engine by name, the model is never offered the write tool, and neither key is an author's — both derived, and a file declaring either is refused at load at either value. What remains is that the handle still carries the method: type-level debt, not a live hole. Absent-verb is purely additive later (aReadOnlyResourceRefbeside the existingExternalResourceRef, which already omits it; only 9 internal call sites touch.writeContent().Two deviations from the plan, both confirmed correct in review.
resources/. BR-14 keeps the mutable path cross-team reachable, so the filter is still the only way to scope those..mddocuments and installs none. The two labs undergoals/are graded instruments — the pentest lab has a documents-swapped control — so moving their documents onto a sealed read path changes what the goal suite measures. BR-16 permits leaving them.Parts worth reviewing closely
seat-references.ts→placeOfEntry,verifySeatReferenceWall, and the omission refusal. The wall places an entry by its definition's mintedref, not its accessor key; the post-mint check re-derives the place itself rather than asking whether the key is inallowed. An earlier version's verification agreed with its own bug.isReferenceDefinition— the discriminator isrender === referenceBody, identity not shape. A shape test (contentFileset, both write flags false) would read a hand-written sealed file-backed resource as a reference and refuse a correctly-wired app; a brand field would be a second place the same fact lives, settable by a hand-built entry. Load-bearing for anyone touchingreferences-from-docslater.clear-shadowed-references.ts→referenceScopeId. The one place this refuses instead of guessing. A wrong address here reports success and leaves stale content live, which is worse than not running.published-tree-surface.test.ts— fixed in its extraction, not its rows:RESERVEDand the leaf normalizer now readDOCUMENT_SLOTSfrom the convention, and the README's<slot>is expanded into both slots rather than read as a folder. Rows would have papered over a guard checking the wrong thing.Evidence
Re-run on
46a9860, after the documentation pass landed — the surface guard reads those pages, so a run from before them would certify a state that had already changed.pnpm --filter @flow-state-dev/workforce test— 685 pass / 41 files.pnpm --filter @flow-state-dev/workforce typecheck— clean.pnpm --filter @flow-state-dev/fsdev typecheckandtest— clean, 246 pass.Mutation testing, because a green test that would stay green without the implementation proves nothing:
writable: false/llmWritable: falserender(frontmatter strip)referenceReachableBySeatalways trueplaceOfReferenceteamsname)referencescatalogThe wall's bypasses are asserted as negatives — a seat that must not reach the aliased handbook does not, an app that omits the catalog is refused rather than quietly hired — because a happy-path check stays green straight through every one of them.
Two corrections to earlier versions of this description, kept rather than quietly edited away. An earlier body claimed all five process guards clean while
published-tree-surfacewas red; that claim was written from the checks intended rather than from a run, which is why every line above now names the commit it came from. An earlier body also reported CI green onc3153620when the Actions workflow had never run on this branch at all and the three green statuses were Vercel builds cancelled by an Ignored Build Step. CI does run now — the gap was specific to the PR-open event — but the combined commit status can readsuccesswhileTypecheck & Testis red, so read the check run, not the aggregate.Not claimed: the bash/sandbox mount (stays with FIX-1382), and any change to the shipped
resources:grant.Acknowledged follow-ups, deliberately not here: a shared
referenceKeys/documentKeyshelper, colocatingplaceOfReferencewithmintResourceRef, single-walk consolidation inread-declared-roster.ts, test fixture helpers, and hoistingreferenceKeysout of the per-worker hire loop — that last needs per-kind memoization to stay correct, since workers in one roster can have different kinds, so it is not the few-line change it looks like.Documentation was written by an isolated docs pass rather than by this change's author, and lands in the same commit as the behaviour it describes. It found a fourth passage documenting the removed silent fallback that this change had missed.
The spec gate was approved in session on 2026-09-20 by
jhoffner, on headb869e600ofspec/FIX-1467(#1957) — D1 and D2 ratified, ambient reach always-on with no switch. No label applied or removed by me.Closes FIX-1467.
🤖 Generated with Claude Code
https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
Generated by Claude Code