Skip to content

spec(FIX-1467): Explore: split RO references/ from mutable seed-then-evolve resources/ - #1957

Closed
jhoffner wants to merge 2 commits into
mainfrom
spec/FIX-1467
Closed

jhoffner wants to merge 2 commits into
mainfrom
spec/FIX-1467

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 20, 2026 •

Copy link
Copy Markdown
Collaborator

spec(FIX-1467): split RO references/ from mutable seed-then-evolve resources/

Someone who… Today After
keeps the company handbook in git and edits it there The edit reaches the agents on the next deploy — until anything writes that document once. From then on the file is dead weight and the agents read a body that exists in no repo. Nothing reports it The file in git is the only copy. Editing it is the edit — it reaches the agents on the next request, and keeps reaching them. No write can strand it
runs an engineering seat that needs the team handbook Reachable only because the app remembered to install that team's slice on this seat's kind Reachable because the file sits in that team's folder. No install list to keep in step
runs a sales seat in the same org Reads the engineering handbook too, unless the app also remembered a filter line. Nobody is told Cannot. The wall comes from the path, and the app writes no filter
wants an agent to keep notes that survive the turn Same folder, same word, same behaviour as the handbook. Nothing on disk tells the two apart Puts it in resources/, which keeps today's database path — reachable exactly as today, with a named grant available to narrow it and never required to get it
expects the handbook on the agent's bash mount It is not there. Bash mounts collections; a document is a single resource and is skipped Still not there. This exploration does not claim the mount

Today a markdown file under resources slash seeds one org-wide database row on first boot, every seat reads and writes it across the team wall, and the file goes stale; after, references slash is read from the file on every request and stops at the team wall, while resources slash keeps the database path

The top row is today, and the red dashed arrow is the part nobody sees: the disk file stops being the source the first time anything writes. The bottom row splits one folder into two paths.

How: references/ gets a read path that serves the file and is sealed against writes, and a seat's reachable set is derived from where the file sits in the tree instead of from a filter the app remembers to write. resources/ keeps today's behaviour, unchanged.

The POC moved this spec before it was written. Two of the issue's premises did not survive checking against main — details in Reviewers · look here.

Round 1 folded — what moved

Review round 1 is in. The load-bearing question was whether D1 needs a core/engine contract change, because if it did, this issue would collide with epic FIX-1457's "W5 is composition, not a fourth substrate epic" and you would owe a re-scope.

It does not. Settled by running it, not arguing it — five new green POC checks. writable: false is already enforced by the engine, and contentFile is already re-read whenever an execution context is built; together they give both halves of D1 with no core change. The cost is one word: the promise narrows from "served from disk on every read" to "read from the file on every request." A mid-request edit is not seen. BR-3 already declined to promise more, so no rule changed — but the sign-off sentence did, and it is below.

Also folded: a contradiction both reviewers found independently (the spec said a mutable document needs a named grant; its own rules said the opposite, and the rules were right), two business rules cut for having no production path to exercise, and one new finding — sealing a file cannot evict a database row written before the move, so the migration is a data migration rather than a file move.

Nothing here changes D1's or D2's direction. No approval is recorded and a fresh gate is owed.

Need your sign-off

Live fork · does a reference reach every seat under its scope automatically, or is there a switch to turn that off?

  • In plain terms. Whether a newly hired agent automatically knows the company handbook, or somebody has to remember to let it.
  • The trade-off. Always-on means hiring costs zero configuration, and anything dropped into org/references/ reaches everyone under that org — the blast radius of adding a file is everybody. A switch lets a tight team run tight, and adds a setting people forget, which surfaces as an agent that mysteriously does not know the handbook.
  • Recommendation: always-on, no switch. The narrowing that matters is the tree, and a seat wanting less already has an explicit references: list. A switch is a third mechanism beside two that work.
  • What would change my mind: a seat that must read nothing ambient — a contractor desk, an untrusted agent. That is an isolation level, not a narrowing.
  • What being wrong costs: little, and asymmetrically. Adding an opt-out later is additive; removing an always-on default later breaks every app that leaned on it.

Ratified, for confirmation

  1. D1 · A reference is a read path, not a renamed folder. references/ is read from the file rather than from a stored row, and is sealed so nothing can write it; resources/ keeps today's seed-then-evolve behaviour. If wrong: org knowledge can only be changed by a deploy, and anyone who wanted in-product editing has to move the file and re-teach their people. Scope of the promise, narrowed in round 1: an edit in git reaches the agents on the next request, not mid-request.
  2. D2 · The tree scope becomes derived and enforced, replacing the app's hand-written install filter. If wrong: where a file sits becomes a permission, so moving one between team folders silently changes who can read it. Round 1 sharpened one consequence: the tree is now the only way to widen — the rule that promised an install-side override was cut, because nothing could implement it without reopening the wall.

D1 is the one to weigh. Reasoning and what lost: DECISIONS.md. The cases: BUSINESS-RULES.md.

Three further questions the issue left open are carried open, not put to you — they cannot be decided before the direction is. See Carried open.

Reviewers · look here

  • Decisions → D1 feasibility. The round-1 addition, and the part most worth a second pair of eyes: the (a)/(b) split, and the claim that neither half needs a core change. It rests on resource-registry.ts:502 — a stored row beating config.contentFile — which is what makes the seal load-bearing rather than decorative.
  • Decisions → D1. Two of the issue's premises were refuted by the POC. Door A .md is read-only on disk is false — writable defaults on, the disk body is a first-boot seed, and after one write the persisted body wins forever (expected 'DEFACED' to contain 'ORG HANDBOOK v1'). Is "build a read path" the right response, or is the honest answer a sync story?
  • Decisions → D2. The per-seat whitelist is the current grant path is also false: absent resources: narrows nothing, so no seat whitelists anything today. The real cost is a hand-written filter per kind. Is deriving the wall from the tree better than making that filter mandatory?
  • Rules → BR-19, new. Sealing stops new writes but cannot evict a row that already exists, so a handbook moved into references/ whose ref was written before stays shadowed by the old row forever. This is the one that would ship silently.

Not here: the bash / sandbox mount. References are on no mount today (a document is a single resource; discoverMounts keeps collections only), so it is net-new work and stays with FIX-1382. Also not here: the shipped #1943 resources: grant, which this changes in no way.

Spec · Decisions · Rules · Plan · Linear FIX-1467 · epic FIX-1457 (W5) · builds on FIX-1381 / #1943 · never merges

POC on this branch — 12 green, 3 red on main, and the reds are the work

Throwaway, never ships. It runs the loader, hireWorkforce and a live execution context against a real workforce tree on disk. Legs 1–4 are written as the issue's own POC spine, so a red leg there is the spine naming work that does not exist yet.

ln -sfn ../../packages/workforce/node_modules \
  spec-poc/FIX-1467-references-vs-resources/node_modules
cd packages/workforce
env -u FSDEV_DEFAULT_MODEL pnpm exec vitest run \
  --root ../../spec-poc/FIX-1467-references-vs-resources

Expect 3 failures out of 15. Every red is paired with a control that runs the same harness with exactly one input changed — the app's install filter, one frontmatter key — and the control goes green. A harness that could not observe the behaviour would be red in both halves.

Leg Verdict
1 · loaders walk workforce/**/resources/ GREEN. Org, team and worker refs load, path-qualified
1b · every document is minted scope: "org" The tree is a name, not a storage scope
2 · ungranted seat reads org + own team refs GREEN — only because absent-key narrows nothing
2b · never cross-team RED. The same seat reads teams/sales/handbook
3 · ungranted seat cannot write RED. It overwrote the org handbook
3b · the write sticks RED. expected 'DEFACED' to contain 'ORG HANDBOOK v1'
4 · a mutable resource, ungranted GREEN characterization. It is reachable, and BR-14 says it must stay that way. An earlier draft had this as a RED, which would have walked an implementer into breaking W5
5 · can D1 be built on today's core API? ALL GREEN — a feasibility answer, not work. Five checks; see below

Leg 5, added in round 1. It names no work — it answers the core-change question by running it.

Check Shows
(a) writable: false refuses the write Expressible today, enforced at resource-registry.ts:1971
(b) sealed + contentFile re-reads on restart Expressible today, per execution context
(b) unsealed + contentFile loses the file (a) is load-bearing for (b) — a stored row wins (:502)
(b) a row written before the seal shadows the file The migration hole → BR-19
(b) an edit mid-context is not seen Literal "every read" is the one thing that would need a core change

The seat is hired as engineering.ada — a valid team-qualified id. Round 1 caught that an earlier bare "ada" was not a placement the loader could mint. No verdict moved (nothing reads the team half of the id yet, which is exactly why leg 2b is red), but PLAN's VG adapts this harness after D2 lands and would otherwise have passed for the wrong reason.

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction document in four files, not an implementation. Reviewing it well means answering one question: is this the right approach?

In scope to challenge:

  • The problem framing in SPEC.md — are we solving the right thing, for the people named?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label or a colour you'd have chosen differently is not a finding; a figure that shows a shape the decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch showing the shape of the proposed solution. It is knowingly incomplete, is not real code, and is not what will ship. Review it for directional viability only. Do not report that it lacks error handling, omits edge cases, names things that don't exist in the repo, or wouldn't build: all of that is true on purpose.
  • Any POC files on this branch, entirely. This PR is never merged, so it may carry throwaway proof-of-concept code, characterization tests, or an HTML mockup built to validate the direction (spec-poc). None of it ships. Read it to judge whether the shape holds; do not review it as code.

One request, if you are an automated reviewer: the two lists above are the whole difference between a useful review of this document and a long one. Volume is not signal here — a single finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback about their direction is not line-level and is treated like any other above-the-bar finding.

🤖 Generated with Claude Code

https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz


Generated by Claude Code

The four documents, the what-changes figure, and a POC that checked the
issue's premises against main before any of it was written.

The POC reframed the direction. A Door A `resources/*.md` is not a
read-only document on disk: the disk body is a first-boot seed, `writable`
defaults on, and after one write the persisted body wins forever. So
`references/` is a read path that has to be built, not a folder to rename.
And the cross-team wall exists today only as a filter line the app
remembers to write — absent `resources:` already narrows nothing, so the
per-seat whitelist the issue argued against is not the current default.

11 checks, 6 green and 5 red on main; every red paired with a one-input
control that goes green.

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 2:47pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 20, 2026 2:47pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 20, 2026 2:47pm 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-20T14:27:24.970219Z 01328ac 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

@jhoffner jhoffner added the spec label Sep 20, 2026 — with Claude

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

FSD Architect — coherence only. Not owner approval / not the merge gate (never-merges; shared jhoffner login).

Streams

Does not fork in-flight siblings:

  • #1944 / FIX-1457 (W5 parent) — child explore, soft-before KS
  • #1955 / FIX-1458 (people via flow actions) — orthogonal
  • FIX-1465 graphs-as-resources — stays on the mutable resources/ side if it lands
  • #1943 / FIX-1381 — correctly left byte-for-byte alone (PLAN V4/V6 / BR-13–14)

What landed well

POC-moved D1 (read path, not writable: false rename) and D2 (tree-derived wall replaces the optional app filter) match W3 path=scope and the invent-kills on Linear. Carving the bash mount to FIX-1382 is right given POC leg 5 (refs on no mount today).

Sync debt (not a second direction)

FIX-1467 Desired outcome + POC spine still say always mount refs RO and “retarget #1943.” This PR says mount is out and #1943 keeps its shape with a separate references: ambient key. Spec/PLAN win after Jake signs D1/D2; Linear should drop mount from this ticket’s AC so an EM does not rebuild FIX-1382 here.

For Jake on the live fork

Ambient always-on (no opt-out switch) matches the morning lean; contractor/untrusted “read nothing ambient” is correctly named as a later isolation level, not a third mechanism beside tree + explicit references: narrow. Sign D1 carefully — deploy-only handbooks is the real product cost.

No two-direction hold. No D-n.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect — coherence / approach stamp on this never-merge explore. Not owner approval / not the merge gate.

Live fork — ambient reach

Lock: always-on, no switch. Tree scope + optional explicit references: narrow are enough. A third opt-out knob is the forgotten-setting failure mode. Contractor / untrusted “read nothing ambient” is an isolation level, not a switch on this default — additive later if needed.

D1 — read path, not rename

Confirm. POC correctly killed “Door A is RO on disk.” writable: false / rename-only is not a convention (one forgotten key restores the write). No write verb is the contract; sync-from-disk-on-boot is the worse alternative (silent data loss). Deploy-only for references/ is the intentional trade; in-product edit stays on resources/.

D2 — tree wall derived at hire

Confirm. Absent resources: already narrows nothing; the real unpaid cost is the unenforced per-kind filter. Derive reachability from path at mint; explicit list only narrows. Moving a file between team folders is a permission change — correct cost. Storage still scope: "org" is a name, not the wall — principal-bound auth stays W5/FIX-1455, not this ticket.

Plan S3

Hold the fence hard: writable: false on an ordinary entry is not equivalent to absent write verb. Don’t let impl collapse them.

Holds / out of scope

No two-direction vs W5 / #1955 Model B / Door B. 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 review (exploration spec + POC)

Verdict: The direction is sound and better than the lighter alternatives this spec already argues against (writable: false on resources/, folder rename only, docs-only). The POC is the right shape: leg 3 + 3b + the writable: false control are the load-bearing proof that D1 needs a read path, not a convention tweak; leg 2 RED + install-filter control cleanly separates D2 from “keep the app filter.”

I am not approving yet because a few artifacts fight each other or overshoot an exploration gate—fixable without reopening D1/D2.

Where the approach might be simpler (without undoing D1/D2)

Idea Take
Docs + writable: false only Insufficient: POC shows writes can be blocked while reads still come from the row (3b).
Single folder, no references/ Would keep seed-then-evolve semantics; git-as-source needs a separate install/read contract anyway.
Tighten mutable grants in this ticket Out of scope for FIX-1467 (see BR-14 / V4)—but the POC currently reads like it is in scope (leg 4).
Third-party package Nothing obvious; this stays workforce + core/engine.
Less new code at implement time Reuse is good in the plan; I'd make it explicit: parameterize the existing tree walk (slot constant) instead of a second read-resources-directory fork; seat-references.ts as sibling of seat-resources, not a copy of resolveSeatResources / readOnly() semantics.

Complexity that may have gone too far (for an exploration PR)

  • Eight surfaces + 18 BRs + V1–VG read like a committed implementation epic before FIX-1457 scopes children. Consider collapsing PLAN to “likely surfaces + sequence constraint (no dual-run)” until the epic splits issues—keep the POC + DECISIONS sign-off surface.
  • LEG 5 in the POC adds a fifth failure mode for bash mounts already settled out of scope (FIX-1382). DECISIONS “Settled” is enough; leg 5 dilutes the 5-red narrative.
  • D1 wording (“disk on every read”) vs BR-3 and engine reality: naive per-readContent() disk hits N+1 in grepResourceContent / searchResources over llmReadable handbooks. BR-3 already allows caching; PLAN should pin per-request memoization (external-collection pattern) or hire-time/contentFile seeding so implementers do not accidentally ship a search regression.

What I'd fix before merge (recommended)

  1. Reconcile LEG 4 with BR-14 / PLAN V4 — highest priority (inline).
  2. Drop or relocate LEG 5; update README “5 failures” count.
  3. One short PLAN subsection on reference read caching (align with BR-3).
  4. Optional trim: duplicate mermaid + “considered” table, PLAN pseudocode sketch, POC file header vs README.

If you only want sign-off on D1 + D2

Those decisions look directionally right given the POC. The open ambient-reach fork is well-framed; recommendation (always-on) matches the narrowing model. Principal/scope: org vs tree wall (FIX-1455) is correctly raised as epic-level, not hidden.

Happy to approve on a follow-up pass once leg 4/BR-14 alignment and read-caching intent are explicit.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

const { ctx } = await ctxFor(ada);
// The spine's promise: mutable access is explicit. Absent-key narrows nothing,
// so the same absence that grants ambient reads also hands over the pen.
expect(handleFor(ctx, ENG_SCRATCH)).toBeUndefined();

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.

LEG 4 vs spec scope (major). This RED expects ENG_SCRATCH to be unreachable with no resources: key, and the comment calls that “the spine’s promise.”

BUSINESS-RULES.md BR-14 and PLAN.md V4 explicitly require the opposite: absent resources: must keep today’s mutable reachability (regression guard).

FIX-1467 owns the reference wall (D2) and read path (D1), not tightening mutable grants. Suggest one of:

As written, a implementer chasing “make leg 4 green” can break W5.

// `discoverMounts` keeps an entry only when `isCollectionRef(value)`, which
// reads `.pattern`. A single resource has none, so it is skipped: references
// are on no mount at all today, RO or otherwise.
expect(orgHandbook.pattern).toBeDefined();

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.

LEG 5 is out of scope for this exploration. SPEC.md / DECISIONS.md already defer bash/sandbox mounts to FIX-1382 and record “no mount today” as settled CONFIRMED, not work for 1467.

Keeping this as a RED leg inflates the POC README (“5 failures”) and can be read as part of the sign-off surface. Consider dropping the describe block here (evidence already in DECISIONS) or moving a 3-line characterization under FIX-1382 when that issue implements mounts.

Comment thread spec/FIX-1467/BUSINESS-RULES.md Outdated
| BR-11 | Any code path attempts to write a reference's content | Refused, whatever the frontmatter says. A reference has no write path to turn on | CI · **red today** (POC leg 3) |
| BR-12 | A reference's file declares `writable: true` in frontmatter | Refused at load, naming the file. A document that asks for a pen in the folder that has none is a mistake, not a preference | CI |
| BR-13 | A `resources/` document is read and written by a granted seat | Exactly as it behaves today, byte for byte — seed once, the row is the source (BP-030) | Existing suite, unchanged |
| BR-14 | A `resources/` document is reached by a seat with no `resources:` key | Exactly as today: reachable. This spec does not tighten the mutable path | Existing suite · **the regression that must not happen** |

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.

BR-14 is the guardrail that matters for scope discipline. Worth a cross-link in the POC README leg table (or a one-line note at LEG 4) so the exploration harness and the rules page cannot be read as asking for the same change.

(Soft suggestion — BR-14 itself is clear.)

Comment thread spec/FIX-1467/PLAN.md
| ID | Package · role | Change | Rules |
|---|---|---|---|
| S1 | `workforce` · `loader/resource-convention.ts` | Add the `references/` slot beside `RESOURCES_SLOT`, minted by the same `mintResourceRef`. In that one module, as today — it exists so two doors cannot disagree about the convention | BR-15 |
| S2 | `workforce` · a reader beside `loader/read-resources-directory.ts` | Walk `references/` at org, team and worker level. Same symlink and slot discipline, same collect-don't-throw. Records carry the **file path**, not a body destined for a row | BR-1 BR-18 |

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.

Read caching / perf (should be explicit). S3’s “content from file at read time” is correct for D1, but D1 marketing text (“every read”) is stricter than BR-3, and tools like grepResourceContent loop readContent() per ref — today that’s in-memory after install.

Before implementation: state whether references use per-request read-through cache (engine already has a pattern for external collections), contentFile + load at context/hire (fresh after restart per BR-2), or literal disk every call. Without that, llmReadable handbooks risk a silent search/grep regression.

This doesn’t argue against D1 — it avoids an accidental implementation fork.

Comment thread spec/FIX-1467/PLAN.md Outdated
| V1 | S2 | Org, team and worker `references/` load; a directory in the slot is reported; a non-`.md` is passed over (BR-18) |
| V2 | S3 | BR-11 red→green: the POC's `DEFACED` case returns the file's body. BR-12 refuses by name. BR-2 across a restart, **never** asserted as immediate (BR-3) |
| V3 | S4 | BR-7 red→green **with no app filter written**. BR-4, BR-5, BR-6, BR-8, BR-9 |
| V4 | S4 | **The second path (BP-035): BR-14.** A seat with no `resources:` key still reaches every mutable resource, exactly as today. The regression that would otherwise ship silently |

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.

V4 is the right second-path check. Pair it with POC leg 4 cleanup (see inline on references-today.poc.test.ts ~274): the verification table and the throwaway harness should tell the same story about mutable reachability.

Comment thread spec/FIX-1467/PLAN.md

## Surfaces

| ID | Package · role | Change | Rules |

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.

Reuse / directory smell (suggestion). S1–S2–S5 are three rows for “same convention, same walk, codegen agrees.” At implement time, prefer one parameterized walk over a second 400-line read-resources-directory clone — matches resource-convention.ts’s “two doors, one ref rule” comment and keeps cross-imports shallow.

seat-references.ts beside seat-resources.ts still makes sense (tenet 5), but share parse/describe()/refusal messaging — don’t copy resolveSeatResources / kind-slice logic.

|---|---|
| **Instead of** | Renaming `resources/` to `references/` and relying on `writable: false` in each file's frontmatter |
| **Because** | There is no read-only thing to rename. The POC wrote to an org handbook through an ordinary seat and read it back from a fresh context: `expected 'DEFACED' to contain 'ORG HANDBOOK v1'`. Today's document is *already* seed-then-evolve — the disk body is a first-boot seed, a write persists, and the file in git becomes dead weight that nothing reports |
| **Locks in** | Org knowledge becomes deploy-only. Nobody fixes a handbook typo from inside the product, ever; they move the file to `resources/` and accept that the row becomes the source. In exchange the reverse promise holds: what is in git is what the agents read |

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.

D1 rationale holds. Optional simplification at implement time: if “git is source” only needs fresh body after process restart (BR-2), defineResource({ contentFile, … }) + no write verb may be enough without a new per-read disk hook — BR-3 already relaxes hot reload. If product truly needs every readContent() to hit disk, that’s a small engine decision worth calling out in PLAN so workforce doesn’t invent a one-off.

(Not asking to weaken D1 — only to avoid duplicating install semantics blindly from resources-from-docs.)

Comment thread spec/FIX-1467/PLAN.md
[`spec-poc/FIX-1467-references-vs-resources/`](../../spec-poc/FIX-1467-references-vs-resources/).
One PR.

FIX-1467 is filed as an *exploration*: the gate approves the direction, and whether the build

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.

For an exploration gate, the full S1–S8 + V1–VG matrix is valuable but heavy — FIX-1457 may still split children. Consider (if you want a leaner spec PR): keep SPEC + DECISIONS + POC as the approval surface; shorten PLAN to sequence constraint (no dual-run) + surface bullets without full verification IDs until implementation issues exist.

Uncertain this should happen; flagging as simplify smell, not a blocker if the epic wants a single implementer packet.

@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: 01328ac156

ℹ️ 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 thread spec/FIX-1467/PLAN.md Outdated
|---|---|---|---|
| S1 | `workforce` · `loader/resource-convention.ts` | Add the `references/` slot beside `RESOURCES_SLOT`, minted by the same `mintResourceRef`. In that one module, as today — it exists so two doors cannot disagree about the convention | BR-15 |
| S2 | `workforce` · a reader beside `loader/read-resources-directory.ts` | Walk `references/` at org, team and worker level. Same symlink and slot discipline, same collect-don't-throw. Records carry the **file path**, not a body destined for a row | BR-1 BR-18 |
| S3 | `workforce` · the install half, beside `resources-from-docs.ts` | **D1's whole seam.** Content comes from the file at read time and there is no write verb — not `writable: false` on a normal entry. Refuse a `writable: true` frontmatter by name | BR-1 BR-2 BR-11 BR-12 |

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 Include the substrate change required by D1

This cannot be implemented only in workforce while retaining the existing L1 substrate: DeclaredResourceEntry admits only defined resources/collections (packages/core/src/types/block.ts:984-986), every normal ResourceRef exposes writeContent() (packages/core/src/types/resource.ts:454-456), and the engine implements that verb over cached ContentStore data. The supported file-backed option also loads at startup and retains the write verb. Either include the necessary core/engine contract work or relax D1 to an existing read-only resource; otherwise S3 has no supported API that can satisfy BR-1 and BR-11.

AGENTS.md reference: AGENTS.md:L179-L181

Useful? React with 👍 / 👎.

Comment thread spec/FIX-1467/BUSINESS-RULES.md Outdated
| BR-7 | A seat on team A reads a reference under `teams/B/` | Refused. Not an empty read, not a null body — the ref is not reachable from this seat at all | CI · **red today** (POC leg 2) |
| BR-8 | A seat under `org/workers/<name>/` reads an org reference | Reaches it. Inherit runs down the tree, and a worker under `org/` is under the org | CI |
| BR-9 | A worker-local reference under `teams/A/workers/ada/` is read by another seat on team A | Not reachable. The walk inherits downward only; a sibling's folder is not above anyone | CI |
| BR-10 | The app installs a deliberately wide slice on one kind | Honoured. An app may still widen its own kind explicitly; what changes is that it no longer has to narrow by hand | CI · the second path (BP-035) |

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 Define how a kind opts out of the team wall

There is no signal distinguishing a deliberately wide installation from the ordinary full-catalog installation used by the POC. S4 always derives a seat's reachable set from its tree position, while explicit references: entries may only narrow it, so enforcing BR-7 necessarily ignores this widening and honoring BR-10 necessarily bypasses the wall. Define an explicit trusted widening mechanism and test it, or remove BR-10.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-1467/SPEC.md Outdated
| **keeps the company handbook in git and edits it there** | The edit reaches the agents on the next deploy — until anything writes that document once. From then on the file is dead weight and the agents read a body that exists in no repo. Nothing reports it | The file in git is the only copy. Editing it *is* the edit, every read, forever |
| **runs an engineering seat that needs the team handbook** | Reachable only because the app remembered to install that team's slice on this seat's kind. Nothing derives it from where the file sits | Reachable because the file sits in that team's folder. No install list to keep in step |
| **runs a sales seat in the same org** | Reads the **engineering** handbook too, unless the app also remembered a filter line. Nobody is told | Cannot. The wall comes from the path, and the app writes no filter |
| **wants an agent to keep notes that survive the turn** | Same folder, same word, same behaviour as the handbook. Nothing on disk tells the two apart | Puts it in `resources/`, which keeps today's database path and still needs a named grant |

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 Keep the mutable-resource access promise consistent

For seats without a resources: key, this claims mutable documents still need a named grant, but BR-14 and PLAN V4 explicitly preserve today's opposite behavior: absence grants every mutable document installed on the kind (packages/workforce/src/hire.ts:588-595). This is externally observable access behavior, so the summary, figure, and implementation contract currently promise incompatible outcomes; describe grants as optional narrowing or change BR-14 deliberately.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-1467/BUSINESS-RULES.md Outdated
| # | When | Then | Proved by |
|---|---|---|---|
| BR-7 | A seat on team A reads a reference under `teams/B/` | Refused. Not an empty read, not a null body — the ref is not reachable from this seat at all | CI · **red today** (POC leg 2) |
| BR-8 | A seat under `org/workers/<name>/` reads an org reference | Reaches it. Inherit runs down the tree, and a worker under `org/` is under the org | CI |

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 Remove the unsupported org-worker acceptance case

No real seat can currently occupy org/workers/<name>: readWorkforceDirectory only creates team-qualified workers, and read-resources-directory.ts:160-165 explicitly notes that org-worker documents have no hireable seat at that address. Because V3 nevertheless requires BR-8, the planned CI check has no production path to exercise. Either add org-level seat support to the issue's scope or remove BR-8 from this contract.

Useful? React with 👍 / 👎.

for (const [ref, def] of Object.entries(catalog)) {
if (installFilter(ref)) installed[ref] = def;
}
const hired = hireWorkforce([seat("ada")], {

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 Give the POC a valid team-qualified seat

The supposed engineering seat is hired as "ada", although WorkerManifest.id is required to be <team>.<name> (packages/workforce/src/manifest.ts:19-26), and the worker loader is never run. Since D2 derives reachability from that tree location and PLAN VG says to adapt this POC, the harness provides no valid engineering placement from which to distinguish own-team inheritance from sibling-team refusal. Load the seat through the workforce tree or use a valid engineering.ada manifest.

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: FIX-1467 spec (PR #1957)

Verdict: Appropriately scoped — the POC already did the restraint work this skill usually has to ask for (refuted the issue's own premise, dropped a References L1 type / second registry / shared skill-loader). One architecture-reuse question is worth settling before S3's shape locks; it doesn't rise to overbuilt.
Scope: spec → ~700–900 lines planned across S1–S8 (est., production + tests + docs — no implementation exists yet).

On the direction itself

D1 (read path, not a renamed folder) and D2 (derived tree scope, replacing the app's hand-filter) both survive scrutiny. The premise-check is the strongest part of this document: the issue's own two framing claims (Door A is read-only on disk; the per-seat whitelist is today's default) were checked against main and found false, and D1/D2 are the reframe that followed rather than a rename bolted onto an assumption. That's the opposite of premature — it's a spec correcting its own scope before code exists. D2 isn't scope creep riding on D1 either: it's literally the second of the two named acceptance criteria (the cross-team leak), and the decision to leave resources/ untouched (BR-13/14) keeps it from bleeding into the mutable path.

# Finding Lens Recommendation Est. Δlines Sev Conf
1 S3 (the read-path seam) may be reinventing defineExternalResourceCollection Premise / Hindsight Spike a references/ reader against the existing read-through collection type before building bespoke content-source plumbing −100 / +40 (est.) Med Med
Net −60 (est.)

Detail

1. S3 vs. the existing read-through collection type (spec/FIX-1467/PLAN.md S3, packages/core/src/types/external-resource-collection.ts) — defineExternalResourceCollection (FIX-858) is already in the codebase: a collection whose instances are resolved from an app-owned source via a read/search hook instead of ResourceStateStore, and it's read-only by construction — no mutators exist on the type at all, not a runtime-refused writable: true. That's a strictly stronger version of D1's own worry ("nothing to turn back on"). references/ at each tree level is naturally a collection (many files under one folder, one ref namespace), and the workforce package already composes contentTemplate/contentTemplateRef through defineResource elsewhere (define-persona.ts, manifest.ts), so the team has direct experience with the adjacent machinery. PLAN.md's "Considered and dropped" table has five entries and doesn't include this one.

The one real friction I found checking it: an external collection's content is only ever exposed through contentTemplate Liquid rendering (readContentRaw() falls through to "external collections have no raw content store"), so a verbatim handbook body would go through template parsing ({{/<system> tags, a 512 KB cap, a 5s render budget) rather than being served byte-for-byte — which may be exactly why a bespoke path is right. I couldn't settle that tradeoff from the spec alone; it's a real fork, not a slam-dunk cut, so it's flagged as a question for whoever writes S3, not a mandate. If the raw-content gap rules it out, that's worth one sentence in "Considered and dropped" so the next reader doesn't re-derive this.

Considered & deemed justified

  • No References L1 type, no second registry, no shared loader with skill references/ — correctly avoided; a reference stays a file entry composed through defineResource, same substrate as everything else.
  • references: seat-level narrowing (BR-4/5/6) mirrors the already-shipped, already-consumed resources: grant (#1943, exercised in goals/workforce-seats/* fixtures) — and once D2 removes the app's install filter, there's no cheaper interim way for a seat to read less than its full tree position. Not speculative.
  • Always-on ambient reach, no per-kind opt-out switch (the one open fork) — already the leaner of the two options on offer; a switch would be the third mechanism beside two that work. Good call.
  • Bash/sandbox mount left out, routed to FIX-1382 — genuinely net-new surface; correctly not absorbed here.
  • The scope: "org" / principal-bound narrowing gap deferred to the epic (FIX-1455) — correctly identified as cross-cutting rather than pretended-solved in this ticket.

— second-look (read-only; no edits made, nothing implemented)


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect — follow-up on the second-look S3 note. Not owner approval / not the merge gate.

defineExternalResourceCollection is the wrong reuse for S3

The invent-kill instinct is right (don't build a second RO content seam). The candidate is wrong for this shape:

  • Altitude. FIX-858 external collections are app-owned store read-through (read/search hooks, wildcard pattern, collection runtime). FIX-1467 refs are per-file disk entries that share mintResourceRef / the same path-qualified namespace as resources/ (PLAN pinned names + BR-15). That is defineResource composition, not a new collection kind.
  • Content contract. External content is template-rendered (contentTemplate / Liquid). D1 needs verbatim disk body on every read (BR-1 / V2 DEFACED). readContentRaw() on externals has no raw store — that gap alone rules it out without a substrate change.
  • Invent-kill already on the page. DECISIONS already kills a References L1 type / second registry. Routing S3 through defineExternalResourceCollection would reintroduce a parallel entry path beside the mutable document door.

Ask of the PR agent: add one row to Considered and dropped — defineExternalResourceCollection for the read path — with the two reasons above. Do not reopen D1/D2 or reshape S3 around hooks.

Reuse that does fit (same note as the Cursor simplify review): parameterize the existing tree walk / install sibling (read-resources-directory → S2, resources-from-docs → S3, seat-resources → S4). PLAN already sketches that. Absent write verb stays the fence; writable: false is still not equivalent.

No two-direction vs W5 / #1955 / #1943. No D-n. No Jake ping.

— FSD Architect

…s catch up

Settled the round's load-bearing question by running it rather than arguing
it. POC leg 5, five new green checks on `main`, splits D1 in two:

  (a) blocking writes  — expressible today (`writable: false`, enforced at
      resource-registry.ts:1971)
  (b) file-as-source   — expressible per execution context (`contentFile`),
      and ONLY because (a) holds: a stored row wins over `contentFile`
      exactly as it wins over `content` (resource-registry.ts:502), so
      unsealed the file is gone after one write

So D1 needs no core/engine contract change, at the cost of one word: "every
read" becomes "every request". A core change is needed only for a ResourceRef
that does not carry `writeContent()` at all, or literal disk-on-every-read —
neither of which the acceptance criteria require. Propagated the narrowed
promise through SPEC's sign-off, the figure, and the D1 heading.

One new finding: sealing cannot evict a row that already exists, so a file
moved into `references/` whose ref was written before stays shadowed forever.
New BR-19 + V2b; S7 is a data migration, not a `git mv`.

Corrected a claim mid-draft: `writable` is NOT a derived key (only
`contentFile` is), so the references door needs its own derived set. That is
the real residual behind the Architect's "one forgotten key" objection, and
it is one list, not a core change.

Also:
- Fixed the mutable-grant contradiction both reviewers found independently.
  BR-14 was right; SPEC:14, the figure, and POC leg 4 were wrong. A grant is
  optional narrowing, never a precondition for reach. Leg 4 flipped from a RED
  that would have broken W5 to a green characterization.
- Cut BR-8 (no seat can occupy org/workers/<name> — the roster reader passes
  over it in silence) and the old BR-10 (promised an install-side widening
  with no mechanism, and contradicted BR-7). Width now comes from the tree.
- Killed defineExternalResourceCollection as the read-path reuse candidate.
- Gave the POC a valid team-qualified seat (engineering.ada). No verdict
  moved — nothing reads the team half of the id yet, which is why leg 2 is
  red — but VG can now build on it.
- Retired the bash-mount leg; the finding stays in DECISIONS → Settled.
- Pinned the read-caching intent, and recorded the below-bar notes.

POC: 15 checks, 12 green and 3 red on `main` (was 11 / 6 / 5).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
@jhoffner jhoffner added the spec approved This spec is ready for implementation label Sep 20, 2026
@jhoffner jhoffner closed this Sep 20, 2026
jhoffner pushed a commit that referenced this pull request Sep 24, 2026
Review on #2167: the ledger contract ends spec and epic rounds at human
direction approval and records merge separately. Approval was re-read
from each PR's timeline and the coordinator's in-session record. Six of
the ten direction PRs record no approval act apart from the owner's
merge. #1944 was approved on 89c1a1d and re-approved at merge after the
owner's re-cut. #1957 was approved by label and closed unmerged, not
merged as the first draft said. #2045 was approved at 17:10Z, three hours
before its merge.

No round count moved, because no review wave landed between an approval
and its merge. Rounds-to-approval, design-off and the numbers the two
proposals cite are unchanged. The fix A and B quotes now match the
revised skill text, and the #2073 note records FIX-1564, filed at wrap.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016qaz1VpRK4wCQzxpjzZ4Hz
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

spec approved This spec is ready for implementation spec

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants