Files
jason.woltje f8276c5eb3 row 218: C2-12 setup sheet for Melanie and the library survey run sheet (#1719)
Doc only, Sage's sage/row218 89ba79d94 (three commits squashed). Webby APPROVE round 1 (webby-0075,
rev 2848), round 2 (webby-0077, rev 2856) and round 3 (webby-0078, rev 2860). docs/case2/SETUP-SHEET.md
tells Melanie what the agents read, the playground, link and property forms, and what changes for
Bean and Chet, with M5's 1,200 character reply total (mos-1165). It goes to her only after C2-06
lands and on Jason's go (#419). docs/case2/SURVEY-RUN.md is design 10 step 7's run sheet: the
bare mirror as the source, a node check, output lines and refusals from survey.mjs. Claim sources
and rulings are in agents/sage/work/queue-218/BUILD.md. No test reads either doc path.
2026-10-21 07:05:39 -05:00

150 lines
12 KiB
Markdown

# 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".