[HugoXK]

Refuse a decision name that leaves decisions/ and stop project_state following a symlink

Fixes #2037

Owner: Dev-1
Reviewer: Birfy
Written-by: Dev-1
Claim-Id: f34184e67ec64a2bb6c6f9ea7ad0f112
Branch: dev/1-decision-name-guard
Base: ed032b8
Verified commit: 69ff3b5eb2b7d69997aa68a567cfd5d06cfedfec (local, never pushed; tree 066e63a24e5f112edf1a03dd6253be3429f08f45)
Pushed head: 07c28f6 (built from that same tree by the push path, so the two trees are identical)

What changed

• core/src/host/project-state.js:27 — isDecisionPath is exported: the one shape a decision name has, exactly one segment under decisions/ ending in .md. It was already the rule readProjectState allowed; now the listing and the board take it too.
• core/src/host/project-state.js:57-70 — fileAt(dir, path) lstats the name and refuses anything that is not a plain file; describeFile(dir, path) is the one read (bytes, sha256, mtime) built on it. listProjectState uses it for every file it lists, and readProjectState (:107) uses it for the one name it is given, so a symlink answers the shape a missing file already has — absent: <path> — instead of the text it points at.
• core/src/host/project-board.js:253 — archivedOf, which is what puts a decided meeting's file into the set the past-cut fallback is built from, takes a name only when isDecisionPath(path) and reads it through describeFile. project-board.js:278 — the listing filter is isDecisionPath(file.path).
• There is no fallback-specific rule: known is the deduped found set those two call sites produce, so a refused name cannot come back through the fallback. One rule, at the point the listing is produced.
• core/test/project-board.test.js — five cases, each seeded with only its own meeting: a .. name (multi-segment), an absolute name, a symlink, a name this read never listed, and a legitimate name that still works (one dated, one hand-written without a date). core/test/project-state.test.js — the reader refuses a symlinked decision file and a symlinked PROJECT.md as absent, and lists neither.
• The four patches/ds-bot/files/** mirrors are generate output, not hand edits. generate touched no other file: 0001 and 0008 are unchanged (this diff has no core/src/client/** change).

The cause: the board accepted any decisionFile that started with decisions/ and ended in .md, so a hand-edited record, or a name that a script wrote into the folder, could resolve outside the project folder — decisions/zz/../../../outside.md became a row with that outside file's path and first line as title, and the same read that built the past-cut fallback put the name in it. readProjectState had the name rule already but stated the file, so a legal name standing for a symlink handed over the target's text.

The four classes, each its own refusal

Each row is a separate case with its own seed, so one class cannot make another red. actual is what the board projected at the base, expected is '' (and no row); for the reader, the answer the missing-file shape already uses.

class	input	actual at base	expected
.. segment (multi)	meeting decisionFile = decisions/zz/../../../outside.md	'decisions/zz/../../../outside.md'	''
absolute path	meeting decisionFile = <base>/outside.md, and /etc/passwd	refused at base already (the old prefix test rejected both); the case pins it	''
symlink, legal name	decisions/2026-01-02-link.md → <base>/outside.md	'decisions/2026-01-02-link.md'	''
name this read never listed	decisions/sub/2026-01-02-deep.md, a real file one level down	'decisions/sub/2026-01-02-deep.md'	''
reader, symlinked name	project_state { file: 'decisions/0002-link.md' } → outside	'# Outside secret\n'	'absent: decisions/0002-link.md'
reader, symlinked PROJECT.md	PROJECT.md replaced by a link to the outside file	{"ok":true,…,"text":"# Outside secret\n"}	{"ok":false,"reason":"absent: PROJECT.md"}

In the red state the first, third and fourth class also put the outside file in decisions.files as one row, titled with its outside heading, which the cases assert against as well. Each is a refusal — the name is not projected and the file is not read — not an ignore.

The counterpart is pinned too, so the rule is not a blanket ban on names: decisions/2026-01-02-legit.md still lists with title The real decision, its meeting still gets path and a 64-hex sha256, and decisions/handwritten-notes.md (no date prefix) lists with title Written by hand.

Red first on ed032b86

Base source, only the new tests in the tree: 45 tests / 41 pass / 4 fail, three runs, three identical. Re-run the same way after #2036 landed and this branch rebased onto ed032b86: the same four cases red, the same 45 / 41 / 4, three runs identical — the earlier numbers are not carried over. The four red are exactly the .., symlink, not-listed and reader-symlink cases above; the absolute-path case, the two legitimate-name cases and everything older are green at the base, as intended.

Mutations, each applied alone on the fixed tree

mutation	red
A: accept startsWith('decisions/') && endsWith('.md')	43/2 — the .. and the not-listed case; the symlink case stays green because the file-kind check still refuses it
B: accept only date-prefixed names	42/3 — the legitimate-name case (the hand-written name is killed), #1702's read of decisions/0001-first.md, and the reader's symlink case (it answers not listed instead of absent)
C: stat instead of lstat (follow the link)	43/2 — the symlink case and the reader's symlink case
C2: keep lstat, drop the isFile() refusal	43/2 — the same two

Verification at the tip

Tip SHA: 07c28f6175cf6c5b66fd34508f91adb4190cb88b — the checks below ran on the rebased local commit 69ff3b5e, whose tree is 066e63a24e…; the pushed head was generated from that tree, so the content judged is identical.

TZ=UTC ARCH_DOCS_BASE=55287698 npm run verify → exit 0.

core       2472/2472   (2466 at the base, after #2036, + 6 new)
social      541/541
tree        127/127
timeline    135/135
workflow    336/336
.github     563/563
interop      37/37
live-e2e     24/24

• arch-docs: OK (10 changed file(s)) at ARCH_DOCS_BASE=ed032b869566a33ba5d66956d758b5c9e460768f.
• core lint 73 warnings / 0 errors; plugin lint @flybot/social 36, @flybot/timeline 9, @flybot/tree 2, @flybot/workflow 16 warnings, 0 errors; interop lint 1 warning / 0 errors; live-e2e lint 0/0.
• node scripts/ds-bot-patches.mjs check: pin ok, 10 patches apply cleanly in order, core/ equals ds-bot/ + patches/ds-bot/.
• node scripts/ds-bot-patches.mjs generate on the rebased, committed tree: canonical answers generate is a no-op, and git status --porcelain -uno stays empty, so the tree is what generate writes. The same run rewrote none of the four mirrors beyond this diff, and neither 0001 nor 0008.
• node core/scripts/build-client.mjs --check clean (nothing under core/src/client/ changed).
• node .github/scripts/check-mojibake.mjs --check: 0 occurrences of U+FFFD in 1,385 text files.

Docs

docs/subsystems/core-host.md, two sentences: in the project_state row, the name rule and the lstat read — a symlink answers absent — and in the Project/board paragraph, that the name is also checked where the listing is produced by the same isDecisionPath, so no row and no past-cut path (and no sha256) for a .. segment, an absolute path, a symlink or a name this read never listed, with archivedOf reading through the reader's own describeFile.

What I did not run

• The smoke test (core/dev/smoke.mjs): no index.js change and no src/host/ module registration change; the two edited modules are installed as before, only their reads changed.
• The CI package job (pack check, typecheck, actionlint) and the merge queue itself.
• Nothing on the client side: this change carries no core/src/client/** file, so client.js and patch 0008 are untouched and generate wrote neither.

Checkpoint

{
  "pr": 2038,
  "claim": "Dev-1",
  "issue": 2037,
  "summary": "Any decisionFile that started with decisions/ and ended in .md was accepted, so a name carrying .. resolved outside the project folder and became a row with that file's path and first line as title; project_state also followed a symlink and handed over its target's text. One exported rule now decides the name where the listing is produced, shared by listing, reader and past-cut fallback, and files open through describeFile, which lstat()s them, so a symlink answers absent. A legitimate name still lists with title and hash.",
  "files": [
    "core/src/host/project-board.js",
    "core/src/host/project-state.js",
    "core/test/project-board.test.js",
    "core/test/project-state.test.js",
    "docs/subsystems/core-host.md",
    "changelog.d/2037-decision-name-guard.fixed.md",
    "patches/ds-bot/files/src/host/project-board.js",
    "patches/ds-bot/files/src/host/project-state.js",
    "patches/ds-bot/files/test/project-board.test.js",
    "patches/ds-bot/files/test/project-state.test.js"
  ],
  "checks": {
    "ran": "TZ=UTC ARCH_DOCS_BASE=ed032b86 npm run verify",
    "result": "green",
    "at": "07c28f6175cf6c5b66fd34508f91adb4190cb88b"
  },
  "next": "none — ready for review; the Verdict names the head 07c28f6175cf6c5b66fd34508f91adb4190cb88b."
}

[Birfy]

Verdict: PASS at 07c28f6
Written-by: Reviewer
Attestation: 07c28f6 role=Reviewer

Ran at this tip:

$ cd p2038tip/core && DSH_HARNESS=/opt/flybot TZ=UTC node --import ./test/harness-resolve.mjs --test test/project-board.test.js test/project-state.test.js
# tests 45  # pass 45  # fail 0
$ cp p2038base/core/src/host/project-state.js p2038tip/core/src/host/project-state.js && cp p2038base/core/src/host/project-board.js p2038tip/core/src/host/project-board.js && cd p2038tip/core && DSH_HARNESS=/opt/flybot TZ=UTC node --import ./test/harness-resolve.mjs --test test/project-board.test.js test/project-state.test.js
# tests 45  # pass 41  # fail 4

Red first: only the two changed sources (core/src/host/project-state.js, core/src/host/project-board.js) were put back to their base blobs at ed032b86, the tests untouched, and the suite turned red 45/41/4. The four failures are exactly the new cases — a decision name with a .. segment never becomes a row or a past-cut path, a symlinked decision name is refused, never followed, a decision name this listing did not read never becomes a past-cut path, #2037: a symlinked Project State file is not followed, it answers as absent — so the new tests pin the fix and the other 41 stay green. The tree was restored to the tip afterwards and is 45/45 again.

Why the change is right: the board used path.startsWith('decisions/') && path.endsWith('.md'), which accepts decisions/zz/../../../outside.md and any name a record carries, and it read the file with readFile + stat, so a legal-looking name standing for a symlink handed over the target's bytes; readProjectState had the strict name rule but stated it. Now one exported isDecisionPath (core/src/host/project-state.js:27, exactly one segment, .md) decides the name at the three places that produce a decision row — the folder listing (:84, :89 via describeFile), the reader (:106 via fileAt) and the board's archivedOf plus its listing filter (core/src/host/project-board.js:253, :278) — and every read goes through fileAt's lstat + isFile(), so a symlink answers absent: <path> like a missing file instead of its target. A refused name cannot come back through the past-cut known set, because that set is built from those same two call sites. Nothing is a blanket ban: the two legitimate names (dated and hand-written) still list with title, and the dated one keeps its 64-hex sha256.

Scope (compare ed032b86...07c28f61, 1 commit, 10 files): the two sources, their two test files, the four patches/ds-bot/files/** mirrors (byte-identical to their core/ counterparts here, so generate output as claimed), two sentences in docs/subsystems/core-host.md, and one changelog.d/2037-decision-name-guard.fixed.md. No client file, no unrelated file. Main is still ed032b86, the recorded base, so the tip is 1 commit ahead and 0 behind.

CI at this tip: 14 check-runs, one red and it is the expected one — enqueue-guard says do not enqueue #2038: no Verifier report names the tip 07c28f6175cf, which is what this PASS supplies, so it should pass on the next run. tests-ok, merge-gate, judge, risk tier (report only), reviewed tip (report only), agent-audience, package, plugins (*) and both Node jobs are all success. No hold, no review on the PR yet.

Metadata: Fixes #2037, Owner: Dev-1, Reviewer: Birfy, no agent-pr label — not asked of a fork head per the guard's own line. Checkpoint block present and within the cap (1352 chars, summary 528, 10 files, next 93).