Fix(vinaya-web): Trace repo-root marker for /docs + /the-harness

[daniboomerang]

Tier: 1
Project: vinaya

Production hotfix. https://vinaya.attalabs.dev/the-harness and /docs were returning 500; every other route was fine.

Symptom

GET /             200
GET /the-harness  500   ← digest 4221790960
GET /docs         500   ← digest 2636202812
GET /state-machine 200
GET /start/quick  200
GET /cli          200
GET /roadmap      200
GET /the-studio   200

The runtime error is visible only in vercel logs — the build is green, because nothing about this fails at build time:

Error: Could not locate repo root (vinaya.config.json) above process.cwd()

Root cause

Both failing routes reach disk through findRepoRoot() (apps/vinaya/web/src/lib/github-links.ts), which walks up from process.cwd() looking for a marker file and throws if it never finds one. Every route that does not call it was unaffected — which is what made the failure look selective and unrelated to deploys.

ROOT_MARKER became vinaya.config.json in #664 (5612c1bc), so that a repo carrying a Vinaya config but no project registry would still resolve. next.config.ts's outputFileTracingIncludes was never updated and still shipped only the previous marker, .vinaya/projects.md.

On Vercel the serverless bundle contains only what file tracing detects. aeg-root/** was present and the doctrine reads would have worked — but the marker that locates it was absent, so the walk failed before any doctrine file was opened. Locally the file is always there, so this could not reproduce outside production.

Fix

One entry added to the tracing list, plus a comment recording the coupling that has now broken twice (packages/governance/projects.md → .vinaya/projects.md → vinaya.config.json, tracing config following late each time):

'/**': ['../../../aeg-root/**', '../../../vinaya.config.json', '../../../.vinaya/projects.md']

.vinaya/projects.md stays — src/lib/repo-state/read-root.ts walks up for that one independently, by a different test.

Verification

Built @atta/vinaya-web and read the route file traces directly, which is the only local check that proves what the lambda will contain:

$ python3 - <<'PY'
... json.load(open('.next/server/app/(site)/<route>/page.js.nft.json'))['files']
PY
the-harness -> 240 traced files, includes ../../../../../../../../vinaya.config.json
docs        -> 242 traced files, includes ../../../../../../../../vinaya.config.json

• bun run build --filter=@atta/vinaya-web — passes.
• bun run typecheck --filter=@atta/vinaya-web — passes.
• bunx biome check apps/vinaya/web/next.config.ts — passes.

No behaviour changes locally; the marker file was always resolvable there. The real proof is post-merge: both routes returning 200 on vinaya.attalabs.dev.

Test Plan:

• [agent] bun run build --filter=@atta/vinaya-web exits 0.
• [agent] Both route traces (.next/server/app/(site)/{the-harness,docs}/page.js.nft.json) list vinaya.config.json.
• [principal] On this PR's Vercel preview deployment (signed in): https://vinaya-git-fix-vinaya-7b814f-daniel-estevezs-projects-6fbb0ca1.vercel.app/the-harness and /docs both render instead of 500ing.

The preview deployment is the honest pre-merge check: it is a real Vercel serverless bundle built from this branch, which is the exact environment the marker was missing from. Production (vinaya.attalabs.dev/the-harness, /docs) can only be confirmed after this merges and redeploys — that confirmation is recorded as a follow-up comment, not as a Test Plan box, since a box that can only be ticked after merge blocks the merge that would make it tickable.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
vinaya	Ready	Preview	Jul 30, 2026 6:45pm

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
atta-ai	Ignored	Preview	Jul 30, 2026 6:45pm
herald-ai	Ignored	Preview	Jul 30, 2026 6:45pm
vada-ai	Ignored	Preview	Jul 30, 2026 6:45pm

[daniboomerang]

Security review — PR #707

Scope reviewed: apps/vinaya/web/next.config.ts (+11/−3), apps/vinaya/web/CLAUDE.md (+1/−1), apps/vinaya/specs/vinaya-spec.md (+1/−0). One commit, b7272559. No dependency, auth, DB, crypto, .claude/, MCP or hook file is touched.

The question that mattered: what does this newly ship into the production lambda?

Exactly one file: vinaya.config.json (644 bytes, repo root). I read it in full. It contains a single briefSchema object — a list of {"builtin": "..."} section names for PR and Issue validation. No token, key, connection string, endpoint, account id, or private configuration of any kind. Nothing in it is sensitive even if it were served verbatim.

It also cannot be served. Two independent reasons:

• findRepoRoot() (apps/vinaya/web/src/lib/github-links.ts:23-35) touches the marker with existsSync only — it never opens or parses it. No route in apps/vinaya/web/src reads the file's contents; a git grep for vinaya.config.json under web/src returns the ROOT_MARKER constant, its error string, and prose/copy references only.
• outputFileTracingIncludes places a file in the serverless bundle's filesystem, not on the static CDN. Next serves bytes-by-path only out of public/, and no route builds a filesystem path from user input — /docs/[...slug] resolves the slug through findDoc(nav, ...) against an in-memory map derived from the modelBackedDocPaths allowlist, never by concatenating the param into a path. No traversal reaches the new file.
• Independently: daniboomerang/attalabs is a public repository (gh repo view → "visibility":"PUBLIC"). Both the newly traced file and the pre-existing aeg-root/** glob are already world-readable at their source. Deploying them changes no confidentiality boundary.

Pre-existing traced content (checked, unchanged by this PR): 42 tracked files under aeg-root/ plus .vinaya/projects.md and .vinaya/doc-owners. Secret-pattern scan (OpenAI/GitHub/AWS/Slack/Stripe key shapes, PEM private-key headers, postgres://user:pass@, mongodb+srv://, bearer tokens, CLERK_SECRET_KEY=/SANITY_API_*TOKEN=) over aeg-root, .vinaya, and vinaya.config.json: zero hits. Zero email addresses. The only GITHUB_TOKEN occurrences are prose in aeg-root/state-machine.md and a tranche file describing that CI requires the variable — a variable name, not a value. Nothing there should be withheld from a public deploy, so I have no pre-existing finding to raise.

Confirmed not changed by this diff: no new network call, no new file write (the added path is a read-only tracing declaration), no new process.env read, no auth or middleware change, and isVercelDeploy() (apps/vinaya/web/src/lib/env.ts:22, VERCEL_ENV !== undefined — presence, not equality) is untouched, so Studio stays gated on both production and preview deploys exactly as before.

The two documentation edits are architectural prose about marker files and file tracing. No credential, no internal hostname, no private endpoint, no non-public identifier introduced.

VERDICT: PASS

FINDINGS (ordered by severity):

1. [LOW] apps/vinaya/web/next.config.ts:28-30 — the tracing key is '/**', so the doctrine tree and both markers are bundled into every route's lambda, including /api/coherence, rather than only the routes that read them. No exposure follows (the content is public and no route serves raw bytes by path), but a per-route key would keep the deployed surface equal to the surface actually needed. Hardening note, not a blocker.
2. [LOW] apps/vinaya/web/next.config.ts:20-27 — the marker-constant ↔ tracing-list coupling is now documented in three places but still enforced by nothing mechanical. It has broken twice, and both breaks were production-only with a green build. This is a correctness/availability risk rather than a confidentiality one, so it is not a security blocker; a check that asserts every ROOT_MARKER-class constant appears in this list would retire the class.

CONFIG SCAN: not applicable — the PR touches no agent, skill, hook, or MCP configuration (.claude/** and all MCP configs are outside the diff), so the external config scanner had no in-scope surface to run against.
SECRETS: none found

Tokens: pr-707: security — Security — claude-opus-5 — —

[daniboomerang]

[agent] Test Plan evidence

Both [agent] items run on fix/vinaya-root-marker-tracing @ b7272559. Ticked in the body; the [principal] item stays open until the deploy lands.

1. Build exits 0

$ bun run build --filter=@atta/vinaya-web
 Tasks:    15 successful, 15 total
Cached:    12 cached, 15 total
  Time:    28.518s
build exit: 0

2. Both route traces list the marker

This is the item that actually proves the fix — the file trace is what determines the contents of the serverless bundle, so it is the only local check that can distinguish "fixed" from "still broken in production".

$ python3 -c "... json.load(open('.next/server/app/(site)/<route>/page.js.nft.json'))['files'] ..."
the-harness: 240 traced files; marker -> ['../../../../../../../../vinaya.config.json']
docs:        242 traced files; marker -> ['../../../../../../../../vinaya.config.json']

(Filtered to the repo-root marker; two unrelated vinaya.config.json test fixtures under node_modules/@attalabs/vinaya/tests/ and apps/vinaya/cli/tests/ were already traced and are not what this fix adds.)

Also run, outside the tagged plan: bun run typecheck --filter=@atta/vinaya-web and bunx biome check apps/vinaya/web/next.config.ts — both pass.

[daniboomerang]

VERDICT: REQUEST CHANGES

BRIEF CONFORMANCE: The PR body is the specification here (standalone fix/*, no task Issue), and the code change does exactly what it states: one entry added to outputFileTracingIncludes so the repo-root marker findRepoRoot() walks up for is present in the serverless bundle. Root cause, path, and blast radius are all correct as described; the accompanying prose carries one factually wrong historical claim, repeated in both docs.

SPEC CONFORMANCE: clean — the addition to apps/vinaya/specs/vinaya-spec.md sits under ## Architecture beside the existing State placement bullet and contradicts nothing already specced.

What I verified independently

1. The trace entry fixes the stated cause, and the path is right. Reproduced the failure surface from the code, not the report: apps/vinaya/web/src/lib/github-links.ts walks up for ROOT_MARKER = 'vinaya.config.json' and throws otherwise. The only two importers that reach it from a (site) route are (site)/the-harness/page.tsx and (site)/docs/[...slug]/page.tsx — and (site)/docs/page.tsx reaches it transitively via ../the-harness/_lib/load-diagram, which calls findAegRoot(). That is exactly the 500 set in the symptom table, and exactly the routes untouched by it that returned 200.

Path resolution checks out. outputFileTracingIncludes globs are relative to the project directory (apps/vinaya/web), so ../../../vinaya.config.json is the repo root, and vinaya.config.json is present there.

2. The verification is real, and I re-ran it. I found a stale pre-fix .next in the worktree whose (site)/{the-harness,docs}/page.js.nft.json contained no repo-root vinaya.config.json (only an unrelated node_modules/@attalabs/vinaya/tests/fixtures/checks/vinaya.config.json). After bun run build --filter=@atta/vinaya-web, both traces contain ../../../../../../../../vinaya.config.json — eight levels up from .next/server/app/(site)/<route>/, i.e. the repo root. That is a genuine before/after on build output, not a restatement of intent.

I also checked the doctrine glob itself rather than assuming it: aeg-root/** traces 42 of 42 files on disk, so nothing behind the marker is missing either.

3. Keeping .vinaya/projects.md is correct — it is not dead. apps/vinaya/web/src/lib/repo-state/read-root.ts builds its candidate from CONFIG_DIR = '.vinaya' + REGISTRY_FILE = 'projects.md' and existsSyncs that, independently of github-links.ts. readRegistry() then reads the same path for content. The PR's claim is accurate as written. (Its practical reach in a Vercel lambda is nil, since /studio/** notFound()s on any deploy — but the local bun run build && bun run start path does exercise it, and removing it would be a second silent coupling break. Keeping it is the right call.)

4. No second instance of the same bug in this app. This was the finding most worth having, so I swept for it exhaustively rather than spot-checking. There are exactly three upward walks under apps/vinaya/web/src:

• lib/github-links.ts → vinaya.config.json — traced by this PR.
• lib/repo-state/read-root.ts → .vinaya/projects.md — traced.
• lib/docs/load-aeg-docs.ts:13-21 → walks up for the aeg-root directory — covered by the existing aeg-root/** glob.

@atta/vinaya-sources (doctrine-file-adapter.ts, file-adapter.ts) reads only from a root it is handed, and @atta/aeg-core does no cwd-relative I/O. Nothing else in the runtime path resolves a marker that is not declared.

5. The CLAUDE.md correction is right. The prior claim that /docs reads doctrine "at build time" was false: apps/vinaya/web/src/app/layout.tsx:1 is export const dynamic = 'force-dynamic', and the build output marks every (site) route ƒ (Dynamic) server-rendered on demand. (/docs/[...slug] does have a generateStaticParams, which runs at build — but rendering is per-request, so the read is too. The new wording sidesteps timing and says "off disk rather than from the forge", which is accurate.)

FINDINGS (ordered by severity):

1. [MAJOR] apps/vinaya/specs/vinaya-spec.md:79 and apps/vinaya/web/CLAUDE.md:7 — the history the two doc additions rest on is wrong, and I checked it against the commits rather than the report.

   The spec says: "it has been renamed twice, and the tracing declaration lagged behind both times." CLAUDE.md says: "The marker has now been renamed twice (packages/governance/projects.md → .vinaya/projects.md → vinaya.config.json, the last in Refactor(vinaya): Short versions, role split, lock and log retired #664) with the tracing list following late each time."

   Neither half holds:

   • The chain is not one marker's history. findRepoRoot()'s marker was GOVERNANCE_MARKER = 'packages/governance/projects.md' right up to 5612c1bc (Refactor(vinaya): Short versions, role split, lock and log retired #664), which renamed it to vinaya.config.json in a single step. .vinaya/projects.md was never an intermediate stage of it — it is a different, still-live marker belonging to read-root.ts, created by that same commit. Presenting them as one three-stage chain is what makes the count "twice".
   • The tracing list did not lag "each time." 5612c1bc did update next.config.ts in the same commit — packages/governance/projects.md → .vinaya/projects.md. And the earlier outage (f543265e, Fix(vinaya): bundle AEG doctrine files into Vercel lambda #649) was not a rename lagging at all: outputFileTracingIncludes did not exist in that file yet, so it was the first declaration, not a late one.

   The durable lesson is real and worth writing down — it is just a different one, and a sharper one: the marker constant and the tracing list live in two files with no mechanical link, and Refactor(vinaya): Short versions, role split, lock and log retired #664 demonstrated the exact failure mode by updating one marker's entry while introducing a second marker it never declared. That is more instructive than a rename count, and it does not require a claim the log contradicts. Everything else in both additions (marker files are a deployment input; renaming is a two-place change; a missing marker 500s only in production behind a green build) is correct and should stay.

2. [MINOR] apps/vinaya/web/next.config.ts:26-27 — the coupling is enforced by prose only. The comment's rule ("changing either marker constant means changing this list in the same commit") is exactly the kind of two-file drift this app already mechanizes elsewhere: src/app/(site)/start/_lib/stages.test.ts pins a model against aeg-root/contracts/*.md, and src/lib/import-boundary.test.ts pins an import rule. A small test asserting that every marker constant in github-links.ts / read-root.ts appears in next.config.ts's include list would close it for good. Out of scope for a hotfix — noting it so it is a choice rather than an oversight.

3. [MINOR] apps/vinaya/web/src/app/(site)/the-harness/_lib/load-diagram.ts:6-8 — pre-existing, not in the diff, but it is the identical defect this PR is correcting one file away: the doc comment reads "Build-time data spine for /how-it-works", and both halves are stale — the read is per-request under the force-dynamic root layout, and the route is /the-harness. Developer's discretion whether to fold it in.

SCOPE: clean — three files, all germane. No drive-by edits, no unrelated cleanups.
TESTS: honest — no new automated test, and the PR does not claim one. Its evidence is the built route traces, which is the only local instrument that can observe the failure mode, and it reproduces (see point 2 above). The three Test Plan checkboxes are left unticked despite the body reporting all three agent-side results as passing; cosmetic, but the boxes should match the prose.
DOCS: tier-appropriate in coverage, incorrect in one claim — both doc additions land in the right files and say the right normative thing, but carry the false rename history in finding 1.

---

The code change is correct and I would not hold it for anything I found in next.config.ts. This is REQUEST CHANGES on a two-sentence doc correction, not on the fix — a product spec that exists to prevent the third recurrence should not carry a history the git log contradicts. If the live 500s make waiting unacceptable, that is a Principal call to make explicitly rather than something I should soften the verdict to accommodate.

Tokens: fix/vinaya-root-marker-tracing: review — Reviewer — claude-opus-5 — —

[daniboomerang]

Addressed in 7ec39d26

MAJOR — false history in both doc additions. Confirmed against the git log rather than taken on report:

$ git show 5612c1bc -- apps/vinaya/web/src/lib/github-links.ts
-const GOVERNANCE_MARKER = 'packages/governance/projects.md'
+const ROOT_MARKER = 'vinaya.config.json'

$ git show 5612c1bc -- apps/vinaya/web/next.config.ts
-      '/**': ['../../../aeg-root/**', '../../../packages/governance/projects.md']
+      '/**': ['../../../aeg-root/**', '../../../.vinaya/projects.md']

The review is right on both counts: one rename, not two, and #664 did update the tracing list — for the other marker. .vinaya/projects.md was never an intermediate name for this marker; it was born in that same commit as read-root.ts's separate registry marker.

The corrected sentences say what actually happened, which is the more useful lesson: #664 moved two markers and declared one. The tracing list was never stale in the "someone forgot to follow up" sense — it was updated by a commit that touched two markers and only declared the second, so the change looked complete and built green while 500ing the routes that walk for the undeclared one.

MINOR — stale comment in the-harness/_lib/load-diagram.ts. Fixed: "Build-time data spine for /how-it-works" → "Request-time data spine for /the-harness". Same falsehood class as the CLAUDE.md sentence this PR already corrects (the root layout is force-dynamic; every (site) route builds as ƒ (Dynamic)), and the route was renamed in #591.

MINOR — no mechanical guard on the marker ↔ tracing coupling. Agreed, and it is the finding I would keep: three prose warnings now exist for a coupling that prose already failed to hold once. A test asserting every marker constant appears in outputFileTracingIncludes is the real fix, and stages.test.ts / import-boundary.test.ts are the local precedent for exactly that shape. Deliberately not done here — a hotfix restoring two production routes should not also grow a new test surface. Raised with the Principal for a follow-up Issue.

Typecheck and biome pass on the changed files. The verified-correct parts of the fix (trace entry, path, .vinaya/projects.md still live, no second instance of the bug) are untouched by this commit.

[daniboomerang]

VERDICT: APPROVE

Re-review of 7ec39d26, following the REQUEST CHANGES on b7272559. I re-derived every claim from the repo and the build rather than reading the change summary.

BRIEF CONFORMANCE: The PR body remains the specification (standalone fix/*, no task Issue), and the diff does exactly what it states — one entry added to outputFileTracingIncludes so the marker findRepoRoot() walks up for exists in the serverless bundle, plus the doc coupling that records why. The MAJOR is resolved; the two remaining items are MINOR and one is deliberately deferred.

SPEC CONFORMANCE: clean.

The MAJOR is fixed, and the replacement is correct

I checked the new history claim against the commits, not against the correction. Every checkable assertion in both rewrites holds:

• apps/vinaya/specs/vinaya-spec.md:79 — "one commit moved the repo-root marker and introduced a second marker for the registry reader, updated the tracing declaration for the second, and never declared the first."
• apps/vinaya/web/CLAUDE.md:7 — "Refactor(vinaya): Short versions, role split, lock and log retired #664 (5612c1bc) renamed findRepoRoot()'s marker from packages/governance/projects.md straight to vinaya.config.json and in the same commit introduced .vinaya/projects.md as read-root.ts's separate registry marker. It updated outputFileTracingIncludes — for the second marker only."

Against 5612c1bc and its parent:

Claim	Verified
findRepoRoot() went packages/governance/projects.md → vinaya.config.json in one step	5612c1bc^:github-links.ts has GOVERNANCE_MARKER = 'packages/governance/projects.md'; the commit replaces it with ROOT_MARKER = 'vinaya.config.json'
.vinaya/projects.md was introduced by that commit as a separate marker	5612c1bc^:read-root.ts has GOVERNANCE_DIR = 'packages/governance' + REGISTRY_FILE = 'projects.md'. Both readers walked the same path before #664; the commit split them into two
The tracing declaration was updated for the second marker only	That commit's next.config.ts hunk is packages/governance/projects.md → .vinaya/projects.md. vinaya.config.json never appears

The "never stale in the 'someone forgot to follow up' sense" framing is the accurate one, and it is a sharper lesson than the count it replaced: the commit looked complete because it did update the tracing list — just for the marker it was moving rather than the one it was creating. That is the thing a future reader needs. Nothing in either rewrite now contradicts the log.

I also re-checked the surviving next.config.ts:20 comment for consistency with the corrected history, since a half-corrected set is a real failure mode. "The marker files ... are the half that has broken twice" still holds on its own terms — both outages were the marker walk throwing, #649's own commit message says findRepoRoot() threw — and it no longer implies a rename lagged. Consistent.

The MINOR stale comment is fixed

the-harness/_lib/load-diagram.ts:7 — Build-time data spine for /how-it-works → Request-time data spine for /the-harness. Both halves were wrong and both are now right: the root layout is force-dynamic so the read is per-request, and the route is /the-harness.

The fix itself still verifies at the new head

The doc commit touches no build-affecting code, but I did not assume that. At 7ec39d26:

• bun run typecheck --filter=@atta/vinaya-web — 14/14 pass.
• bun run build --filter=@atta/vinaya-web — 15/15 pass.
• (site)/the-harness/page.js.nft.json — 240 files, includes ../../../../../../../../vinaya.config.json.
• (site)/docs/page.js.nft.json — 242 files, includes the same.

Eight levels up from .next/server/app/(site)/<route>/ is the repo root, where vinaya.config.json lives. Unchanged from my first pass, and independently matching the evidence comment's numbers (240/242, same path) — that comment is an accurate report of a real run, not a restatement.

FINDINGS (ordered by severity):

1. [MINOR] apps/vinaya/web/next.config.ts:26-27 — the two-file coupling is still enforced by prose only, and I agree it should not be closed here. This is explicitly not blocking, to answer the question directly. A hotfix whose job is to restore two live routes should carry the smallest diff that does it; growing a new test surface in the same PR widens the thing under review at the moment you most want it narrow. Raising it as a Principal follow-up is the right disposition. Recording the shape so the follow-up does not have to rediscover it: the guard wants to assert that every marker constant read at runtime (ROOT_MARKER in src/lib/github-links.ts, CONFIG_DIR + REGISTRY_FILE in src/lib/repo-state/read-root.ts) appears in next.config.ts's include list — the same static-source-parsing shape src/lib/import-boundary.test.ts and src/app/(site)/start/_lib/stages.test.ts already use in this app.

SCOPE: clean — four files, all germane. The fourth (load-diagram.ts) is the comment correction this review asked for; no unrelated edits rode in with it.
TESTS: honest. No new automated test, and the PR does not claim one. Its evidence is the built route traces — the only local instrument that can observe a failure mode which by construction cannot reproduce outside production — and it reproduces independently. Both [agent] boxes are now ticked and backed by a posted evidence comment; the body and the prose agree. The open [principal] box is correctly still open: the real proof is two 200s after the deploy.
DOCS: tier-appropriate and now correct. The spec addition and the CLAUDE.md correction both say what the code does and what the log shows.

---

Approving. The change is minimal, the root cause is right, the path resolves to the repo root, and the two markers that remain in the list are both live (read-root.ts genuinely walks for .vinaya/projects.md by its own test). I re-swept for a second undeclared marker and there still is not one: the three upward walks in this app are github-links.ts (vinaya.config.json, now traced), read-root.ts (.vinaya/projects.md, traced), and lib/docs/load-aeg-docs.ts (the aeg-root directory, covered by the aeg-root/** glob at 42/42 files).

Tokens: fix/vinaya-root-marker-tracing: re-review — Reviewer — claude-opus-5 — —