Repository navigation
Conversation
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
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
jhoffner
left a comment
There was a problem hiding this comment.
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.
|
FSD Architect — coherence / approach stamp on this never-merge explore. Not owner approval / not the merge gate. Live fork — ambient reachLock: always-on, no switch. Tree scope + optional explicit D1 — read path, not renameConfirm. POC correctly killed “Door A is RO on disk.” D2 — tree wall derived at hireConfirm. Absent Plan S3Hold the fence hard: Holds / out of scope
No two-direction vs W5 / #1955 Model B / Door B. No D-n. — FSD Architect |
There was a problem hiding this comment.
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 ingrepResourceContent/searchResourcesoverllmReadablehandbooks. BR-3 already allows caching; PLAN should pin per-request memoization (external-collection pattern) or hire-time/contentFileseeding so implementers do not accidentally ship a search regression.
What I'd fix before merge (recommended)
- Reconcile LEG 4 with BR-14 / PLAN V4 — highest priority (inline).
- Drop or relocate LEG 5; update README “5 failures” count.
- One short PLAN subsection on reference read caching (align with BR-3).
- 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.
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(); |
There was a problem hiding this comment.
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:
- Flip this to GREEN characterization (“ungranted seat still reaches scratch — must stay after FIX-1467”) with a pointer to V4/BR-14; keep the
resources:control as proof feat(FIX-1381): a seat reaches the documents its file names —resources:withro/rw#1943 narrowing still works, or - Remove leg 4 from the “5 reds” spine and move any mutable-grant story to a separate issue/epic.
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(); |
There was a problem hiding this comment.
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.
| | 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** | |
There was a problem hiding this comment.
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.)
| | 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 | |
There was a problem hiding this comment.
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.
| | 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 | |
There was a problem hiding this comment.
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.
|
|
||
| ## Surfaces | ||
|
|
||
| | ID | Package · role | Change | Rules | |
There was a problem hiding this comment.
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 | |
There was a problem hiding this comment.
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.)
| [`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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
💡 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".
| |---|---|---|---| | ||
| | 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 | |
There was a problem hiding this comment.
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 👍 / 👎.
| | 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) | |
There was a problem hiding this comment.
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 👍 / 👎.
| | **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 | |
There was a problem hiding this comment.
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 👍 / 👎.
| | # | 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 | |
There was a problem hiding this comment.
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")], { |
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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 throughdefineResource, same substrate as everything else. references:seat-level narrowing (BR-4/5/6) mirrors the already-shipped, already-consumedresources:grant (#1943, exercised ingoals/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
|
FSD Architect — follow-up on the second-look S3 note. Not owner approval / not the merge gate.
|
…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
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


spec(FIX-1467): split RO
references/from mutable seed-then-evolveresources/resources/, which keeps today's database path — reachable exactly as today, with a named grant available to narrow it and never required to get itThe 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: falseis already enforced by the engine, andcontentFileis 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?
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.references:list. A switch is a third mechanism beside two that work.Ratified, for confirmation
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.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
resource-registry.ts:502— a stored row beatingconfig.contentFile— which is what makes the seal load-bearing rather than decorative..mdis read-only on disk is false —writabledefaults 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?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?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;
discoverMountskeeps collections only), so it is net-new work and stays with FIX-1382. Also not here: the shipped #1943resources: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 workThrowaway, never ships. It runs the loader,
hireWorkforceand 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.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.
workforce/**/resources/scope: "org"teams/sales/handbookexpected 'DEFACED' to contain 'ORG HANDBOOK v1'Leg 5, added in round 1. It names no work — it answers the core-change question by running it.
writable: falserefuses the writeresource-registry.ts:1971contentFilere-reads on restartcontentFileloses the file:502)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), butPLAN'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:
SPEC.md— are we solving the right thing, for the people named?docs/philosophy.md?DECISIONS.md— that's the sign-off surface.BUSINESS-RULES.mdmisses, or a rule that would invalidate the design.Out of scope — deliberately unsettled here, and owned by the implementing agent:
PLAN.mdpins on purpose.PLAN.mdleft open on purpose — it is directional by design, and a gap at that altitude is intended, not an omission.PLAN.mdmay 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.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 reviewfor 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