Skip to content

A reference is read from its file; its reach comes from the tree (FIX-1467) - #1958

Merged
jhoffner merged 5 commits into
mainfrom
fix/FIX-1467-references-read-path
Sep 20, 2026
Merged

jhoffner merged 5 commits into
mainfrom
fix/FIX-1467-references-read-path

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 20, 2026 •

Copy link
Copy Markdown
Collaborator

A company handbook in a workforce tree has two quiet failure modes today, in opposite directions.

It stops being the file. A resources/*.md document 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/ joins resources/ 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.

Slot Body an agent reads Writable Reach
references/ the file, re-read each execution context no the org's, its own team's, its own folder's
resources/ seeds a row; the row is the source from then on yes every document the flow installed
workforce/
  org/
    references/handbook.md        read from the file, reaches everyone
  teams/engineering/
    references/handbook.md        reaches engineering seats only
    resources/scratch.md          unchanged: writable, seeds a row

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 this is a first-boot seed with a longer name. writable, llmWritable, render and flowIsolation are 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 ref and the loader-minted seat id — never from an accessor key an app chose, and never from anything a seat wrote. An explicit references: 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. clearShadowedReferences finds those rows, reports each with the body it had been serving, and clears them. It takes installedOn rather 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:

  • DeclaredResourceEntry admits only DefinedResource | DefinedResourceCollection (core/src/types/block.ts:984).
  • ResourceRef declares writeContent as a required member (core/src/types/resource.ts:457) — contrast edges?, optional by design.
  • So a single per-file resource cannot omit the verb without a core change.

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 (a ReadOnlyResourceRef beside the existing ExternalResourceRef, which already omits it; only 9 internal call sites touch .writeContent().

Two deviations from the plan, both confirmed correct in review.

  • S6 said remove the hand-filter recipe. It is kept, scoped to resources/. BR-14 keeps the mutable path cross-team reachable, so the filter is still the only way to scope those.
  • S7 said migrate the labs and kitchen-sink. Neither is migrated. Kitchen-sink has no .md documents and installs none. The two labs under goals/ 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 minted ref, not its accessor key; the post-mint check re-derives the place itself rather than asking whether the key is in allowed. An earlier version's verification agreed with its own bug.
  • isReferenceDefinition — the discriminator is render === referenceBody, identity not shape. A shape test (contentFile set, 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 touching references-from-docs later.
  • 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: RESERVED and the leaf normalizer now read DOCUMENT_SLOTS from 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 typecheck and test — clean, 246 pass.
  • All five process guards — clean.

Mutation testing, because a green test that would stay green without the implementation proves nothing:

Mutation Tests that go red
drop writable: false / llmWritable: false 3
drop render (frontmatter strip) 11
referenceReachableBySeat always true 4 (incl. BR-7, BR-9)
migration stops deleting 1 (BR-19)
place by accessor key instead of minted ref 1 (the alias bypass)
drop the length-first rule in placeOfReference 1 (the teams name)
tolerate a missing references catalog 3 (the omission off-switch)

The 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-surface was 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 on c3153620 when 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 read success while Typecheck & Test is 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/documentKeys helper, colocating placeOfReference with mintResourceRef, single-walk consolidation in read-declared-roster.ts, test fixture helpers, and hoisting referenceKeys out 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 head b869e600 of spec/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

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

vercel Bot commented Sep 20, 2026 •

Copy link
Copy Markdown

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

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 20, 2026 5:44pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 20, 2026 5:44pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 20, 2026 5:44pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 20, 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-20T16:42:31.506465Z c315362 PR opened
ℹ️ 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.

@linear-code

linear-code Bot commented Sep 20, 2026

Copy link
Copy Markdown

FIX-1467

…es-read-path

# Conflicts:
#	apps/docs/docs/workforce/documents-on-disk.md
@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect — coherence / approach on the write-verb fork. Not owner merge approval.

Write-verb fork — ship this; file absent-verb as its own issue

D1’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 writable: false:

  • writable / llmWritable / render are derived by the slot, refused in frontmatter at either value
  • engine refuses writeContent by name
  • model never gets the write tool

That closes the reachable write hole. The handle still carrying writeContent is a type-level debt (ResourceRef requires the method; only ExternalResourceRef omits it today). A ReadOnlyResourceRef (+ DeclaredResourceEntry widen) is the right follow-up and is purely additive — holding this PR for it would block D2’s wall and BR-19 shadow migration, which are the live data-loss / cross-team holes.

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

  • S6 keep resources/ hand-filter — correct; BR-14 still needs it for mutable. Don’t delete the only scoping recipe for that path.
  • S7 skip labs/KS migrate — correct; graded instruments + KS has no .md docs. Follow-up issue, not unilateral move.

Follow-up to file (not a D-n)

ReadOnlyResourceRef (or equivalent) in core — omit writeContent; workforce references install as that type. Soft-after this merge. Soft-related FIX-1382 stays for bash mount.

No two-direction vs #1957 locks. No D-n.

— FSD Architect

@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 / 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.
  • placeOfReference vs mintResourceRef — inverse grammar lives only in seat-references.ts while mint lives in loader/resource-convention.ts; colocating parse+mint in the loader module would make the workers-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 in hire.ts when options.references is set; verifySeatReferenceWall could reuse a hoisted definitions set too.
  • Tests: references-convention.test.ts is thorough (good); pulling tree() / fixture writers into a shared test helper would shrink noise without losing BR traceability.

Alternatives I considered and would not take instead:

  • Single map + slot metadata only — slightly smaller hireWorkforce API, 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.md
  • teams/<team>/references/handbook.md
  • teams/<team>/references/escalation.md
  • teams/<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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

workforce/
org/
resources/
references/

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.

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({

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.

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 {

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.

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";

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 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).

@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 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 / refusedDeclarationMessage behind a keys argument — the sets are not interchangeable, and BR-13 exists because widening the shared list would break resources/. The reference wording also tells you to move the file; the resource wording does not.
  • Fold seat-references into seat-resources — every branch would ask which key it was. That is larger.
  • Collapse TreePlace into prefix matching — same reachability, loses the workers-as-a-document-name totality, no contract shrink.
  • Unexport placeOf* / TreePlace — hire still computes them; one line in index.ts is 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.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@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 c315362. Configure here.

if (parts.length < 3) return undefined;
team = parts[1];
rest = parts.slice(2);
}

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.

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.

Fix in Cursor Fix in Web

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);
}

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.

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)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit c315362. Configure here.

@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: 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".

Comment on lines +377 to +379
for (const ref of references) {
const place = placeOfReference(ref);
if (place !== undefined && referenceReachableBySeat(seat, place)) reachable.add(ref);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge 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 👍 / 👎.

Comment on lines +107 to +112
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);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge 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/

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge 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 👍 / 👎.

Comment on lines +138 to +141
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.`

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge 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 jhoffner left a comment

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.

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 extending seat-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.filePath as a new optional field carried by every record, not just references' — justified in manifest.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.writeContent staying 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

Comment on lines 274 to 278
const referenceSlotPath = `${slotPath.slice(0, -RESOURCES_SLOT.length)}${REFERENCES_SLOT}`;
const siblings = await openStructuralDirectory(
path.join(path.dirname(slotDir), REFERENCES_SLOT),
referenceSlotPath,
);

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.

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

Comment on lines +222 to +228
const sibling =
reference.filePath === undefined
? reference.ref
: reference.filePath.replace(
`${path.sep}${REFERENCES_SLOT}${path.sep}`,
`${path.sep}${RESOURCES_SLOT}${path.sep}`,
);

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.

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

Comment thread packages/workforce/src/manifest.ts Outdated
Comment on lines +650 to +656
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.`
);
}

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.

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;

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.

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
@jhoffner
jhoffner merged commit 638dadf into main Sep 20, 2026
12 checks passed
@jhoffner
jhoffner deleted the fix/FIX-1467-references-read-path branch September 20, 2026 17:49
jhoffner added a commit that referenced this pull request Oct 15, 2026
…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>
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