stack/agents/sage/work/queue-218/BUILD.md

Row 218 draft notes: claims and sources

Drafts for docs/case2/SETUP-SHEET.md and docs/case2/SURVEY-RUN.md. Repo base: refactor at 947101d8a, which holds 29ce1e360 (row 231). "Design" means git show 75fb3e10e:agents/gosalyn/work/case2/DESIGN.md, cited as D:<line>. "Brief" means docs/plans/2026-10-20_case2-rows.md. Code paths are relative to the repo root. Nothing was run except reads, greps and git merge-base --is-ancestor 29ce1e360 HEAD.

SETUP-SHEET.md

Claim	Source
She keeps writing in Obsidian, obsidian-git pushes to git.mosaicstack.dev, nothing changes on her machine, nothing commits to her repo	D:939-940 (7.1)
Agents read what she pushed; a push reaches them in about a minute	D:1006-1007 (7.5); D:972-973 (60-second sync timer)
Agents read .md notes inside book folders only	D:457-461 (1.2); packages/library/src/scope.mjs:9-19
Not read: top-level notes, .canvas, .base, attachments, anything outside a book folder	D:461
Other repos under ~/src are not read	D:489 (1.3), D:494-497 (N4)
Agents can't write to her repo: canon, playground, anything	D:389 (D3); D:1008
Folder roles live in the projects entry of the business file, hand-edited, agents can't change it	D:409-429, D:443-451 (1.1, M9)
Jason asks her to confirm the mapping first	D:431; D:1324-1328 (10 step 7)
A folder named in playground is her playground	Brief:22; D:434
Each playground prefix sits inside one book folder	D:434-436; packages/library/src/mapping.mjs:77-80
One per book, e.g. <book>/playground/; until then everything mapped is canon	D:438-439
Agents search canon unless they ask for the playground	D:463
Playground may back an idea or question, not a fact, finding or correction; refused before she sees it	D:858 (playground-cited-as-canon); D:378-382, D:835-839 (guard runs before store)
Only the folder decides; a tag or property can't change scope	D:388 (D2); D:440-441; scope.mjs:1
Graph colour group via Groups and a path: query, her own vault setting, changes nothing for agents	Brief:23; D:941-943. Obsidian UI steps from the task prompt, not the design
Path starts with the books repo folder because the vault is ~/src	D:939
N2: moving a note into a book folder makes it canon, agents may cite it as fact	D:944-945; D:259
Rough drafts outside the playground are canon	Inference from D:460 (scope rule)
N4: Obsidian resolves short links across ~/src, the reader sees one repo, the two can differ, the reader can't tell	D:494-497; D:262-263
A name only in another repo leads nowhere for agents	D:489 (R4); packages/library/src/links.mjs:61-87
A full-path link resolves the same in both	D:497-498. Hub side: links.mjs:77-78 (vault-prefix step)
"New link format: Absolute path in vault" setting	Obsidian UI knowledge. Not in design or code. Reviewer may strike it
appears_in and relationships links are read as links	D:489-490; packages/library/src/reader.mjs:15, :153-162
Quoted flow list ["[[A]]", "[[B]]"] parses	reader.mjs:81-96 (flow), :66-73 (quoted scalar), :159
Block list with quoted items parses	reader.mjs:117-122, :66-73
Unquoted [[[A]], [[B]]] is R3	Brief:28-29; reader.mjs:87 (bracket inside a flow list stops parsing), :137
R3 effect: whole front matter unread, note still indexed by path, name and body, listed as a problem	D:480; reader.mjs:103-105, :193; packages/library/README.md:69
Problems show in Mosaic's status	D:473-474; D:999-1000 (7.4 status line)
A value without [[ ]] is a name	D:489-490; reader.mjs:159
Bean and Chet keep names and personalities	D:660-661 (Q180)
Hermes: free text and story text. Mosaic: short cited items, a prose request gets a question or idea	D:778-781 (design 4)
Bean and Chet's item kinds: idea, question, finding, fact; web cites allowed	D:649 (companion); D:860 (citation-unfetched)
Limits 10 items, 5 ideas of 200, others 300	D:819 (M5)
She or Jason can ask for lower limits	D:1329-1330 (10 step 8); D:831
"No cited answer" notice	D:870-871, D:996-997
One item can't mix two worlds	D:859 (citation-cross-universe)
She talks to them in the Console; Hermes keeps running until she moves over; stopping it is her choice	D:381-382; D:1331
Five more helpers; she chooses the start set and can add one later	D:647-654; D:783-784; D:1327-1328
What Jason will ask	D:1325-1327 (10 step 7)

SURVEY-RUN.md

Claim	Source
Runs on <host> 10.1.1.54 under design 10 step 7, after step 4	D:1324; D:1266 (host)
Prints names and counts, never note text, property values, file names or link targets	packages/library/src/survey.mjs:1-6; README:118-125
Sending to Melanie is Jason's call	Brief:36; D:1324-1328
Token slot library-gitea is step 4	D:1314-1316
Run as sudo -u mosaic -H from localadmin; mosaic has no login shell	D:1195-1197; D:1281-1282
Copy at /srv/mosaic/.local/share/mosaic-stack/copies/<id>, <id> = commit in Jason's go	D:1286-1292 (2c); docs/TOOLS.md:417; home /srv/mosaic per D:1314-1315
The copy carries packages/library/src	scripts/stack-copy.sh:36
Row 231 adds the control and bidi escapes	git log 29ce1e360; survey.mjs:78-82; README:121-122
<node dir> is the --node directory of step 2c; scripts/mosaic execs node from PATH	D:1290-1291; scripts/mosaic:41
Dispatch: mosaic library survey goes to survey.mjs with survey <args>	scripts/mosaic:37-41 (one shift leaves survey as argv[0]); survey.mjs:102-103
Command and flags: <repo> plus optional --mapping <file> once; anything starting with - refuses	survey.mjs:16, :104-110
No fetch; reads HEAD	survey.mjs:5-6, :27; reader.mjs:22-24
Top folder only: ceiling is the path's parent	packages/project/src/git.mjs:12, :62
Owner must be mosaic: git gets no global config	packages/seat/src/checkout.mjs:79-89 (GIT_CONFIG_GLOBAL=/dev/null, GIT_CONFIG_NOSYSTEM=1). The dubious-ownership refusal is git's own behaviour
Bus mirror path <dataRoot>/projects/<business>/<project>	Brief:300; packages/project/src/paths.mjs:34-40
C2-04 and C2-03a not landed	grep of packages/*/src finds no library entry handling or refs/heads/served; docs/guides/host-run-sheet.md:269 says "not landed"
Served ref refs/heads/served	D:963 (7.2); Brief:676
Token kept out of URL, config, argv, logs	D:955-956 (7.2)
Mapping file is the entry alone; remote, branch required	survey.mjs:114-116; mapping.mjs:38-47
Output lines and fields	survey.mjs:83-97; data from :26-76
Folder lines list folders that directly hold an entry, full path	survey.mjs:30-35
Key names: short identifiers print, others as (other key)	survey.mjs:17-20, :47
unresolved equals the R4 count	survey.mjs:72
Scope counts cover all tree entries	survey.mjs:66
Refusal exit codes 0, 2, 3, 4	survey.mjs:99-124; README:127-129
Mapping checked before repo	survey.mjs:112-121
stderr format library survey: <message>	survey.mjs:101; problems.mjs:3-5
(project-git) suffix on git failures	reader.mjs:18-20; paths.mjs:4-6
library-playground-outside-book message	mapping.mjs:79-80
100-second git timeout	checkout.mjs:49, :52; git.mjs:68
Exit 127 when node is missing	scripts/mosaic:18, :41 (bash exec failure). Not run
Other errors rethrow as a stack trace	survey.mjs:117, :123, :128-131
Don't work around a refusal	AGENTS.md invariant 6

Code and design disagreements

1. Design 1.1 shows the mapping nested in "projects": {"books": {...}} (D:412-429). The survey's --mapping file must be the inner entry alone (survey.mjs:114-116). The run sheet follows the code.
2. Design 1.3 calls vaultPrefix part of the mapping (D:418). The code makes it optional (mapping.mjs:48, README:30). Without it, a full vault path link, the N4 advice, resolves to nothing in the hub (links.mjs:73-87: root fails, vault-prefix is skipped, shortest refuses a /). The setup sheet's full-path advice holds only when Jason sets vaultPrefix to her books repo folder name.
3. The task prompt calls the unquoted form "refused". R3 is not a refusal. It is a reported problem, and the note stays indexed (D:473, D:480). The sheet says what happens instead.

Open questions

1. Where <repo> comes from on .54. The survey reads a local repo's HEAD and never fetches. The bus mirror needs C2-04 and C2-03a, neither landed. C2-03a moves refs/heads/served, not HEAD, so the mirror's HEAD may name no commit and the survey would refuse with exit 2. The sync also needs a checked mapping with at least one book (mapping.mjs:59, :70), and the mapping's values are meant to come from this survey (D:431). Sage needs to rule: a placeholder mapping for the first sync, a HEAD the sync sets, a --commit flag on the survey, or another source.
2. The brief says Obsidian's property editor writes appears_in: ["[[A]]", "[[B]]"] (Brief:28-29, webby-0041 N4). I didn't read webby-0041 or check Obsidian's output. Both the flow and the block quoted forms parse, so the sheet shows both and says only that the editor adds the quotes.
3. Whether /srv/mosaic/.npm-global/bin/mosaic exists on .54. The run sheet uses the copy's scripts/mosaic by full path to avoid depending on a wrapper.

Sage's rulings on the open questions (2026-10-21)

1. Survey source: the bus's bare mirror after the first library.sync, the only copy on the host (design 2.1). The C2-03a brief now requires the mirror's HEAD to be a symbolic ref to refs/heads/served, with a test (5c6f73ed7), so the survey reads the served commit with no ref flag.
2. Property list forms: the sheet shows both quoted forms, since both parse. Webby checks the claim that Obsidian's property editor writes the quoted form.
3. The "New link format: Absolute path in vault" tip stays. It is an Obsidian setting, not a design claim, and Webby may strike it.
4. The run sheet calls the copy's scripts/mosaic by full path. That holds whether or not a wrapper is on PATH.
5. vaultPrefix: the run sheet's step 4 tells Jason to set it, because the setup sheet's full-path link advice depends on it.

Round 2 (2026-10-21), from Webby's round 1 notes (webby-0075, rev 2848)

• N1, by Mos's ruling mos-1165 (fix before landing): SETUP-SHEET.md now gives the 1,200 character total of item text per reply (design M5, step 8). The word "Today" is gone. No code enforces these caps until C2-06 lands, so my ruling is that the sheet goes to Melanie only after C2-06 lands, and then only on Jason's go (#419). The wording stays as is, because by then it holds.
• N2: SURVEY-RUN.md says tab, newline, carriage return, backspace and form feed print as \t, \n, \r, \b and \f, and other control and bidi characters as \uXXXX (survey.mjs quote()).
• N3: SURVEY-RUN.md has a refusal row for library-commit: (reader.mjs listTree). survey.mjs turns every LibraryError into exit 2 with its message.
• N4: SURVEY-RUN.md's new step 2 checks command -v node under the same sudo and PATH before the survey runs.

Round 3 (2026-10-21), from Webby's round 2 note N5 (webby-0077, rev 2856)

• N5: the library-commit row no longer says a moved HEAD causes it. The survey reads HEAD once, and listTree raises library-commit only for an id that isn't 40 hex or an object that isn't a commit (reader.mjs:29, :31). In practice that means a SHA-256 repository, so a rerun doesn't help. The row now says "for example in a SHA-256 repository" and "Report to Sage".