diff --git a/docs/prd/mosaic-stack.md b/docs/prd/mosaic-stack.md index 42ff1fb4a..94643cc82 100644 --- a/docs/prd/mosaic-stack.md +++ b/docs/prd/mosaic-stack.md @@ -1,6 +1,6 @@ # PRD: Mosaic Stack -- Status: approved, version 1.14. Jason approved draft 0.4 unchanged as +- Status: approved, version 1.15. Jason approved draft 0.4 unchanged as 1.0 on 2026-10-05 (lead decision 61). They approved version 1.1, the Organization requirements, in decision 03130d08-ddce-480d-a601-e59f64744fc3 on 2026-10-14. They approved version 1.2, the chief of staff, the @@ -41,7 +41,21 @@ takes the same path as 1.11 (mos-1231, vikunja:19/463). Version 1.14 adds the playground levels to REQ-LIB-2 and a draft universe to REQ-LIB-3, from the approved playground ruling. It takes the same path - as 1.11 (mos-1233, mos-1238, mos-1241, vikunja:19/464). + as 1.11 (mos-1233, mos-1238, mos-1241, vikunja:19/464). Version 1.15 + rewrites REQ-LIB-6 to Jason's Q223 and Q226 rulings and adds supporting + folders to REQ-LIB-1 and REQ-LIB-2. Mos ordered it in mos-1320 item 8, + and Jason gets a report. +- Version 1.15 source: Jason's Q223, answering Q29: "The agents are not + allowed to write the prose into the writing projects. Agents are + allowed to CRUD character sheets, info summaries, cross-link info, and + supporting documentation. They are NOT allowed to actually write any of + the story." and "They are permitted to freely converse with the writer + via chat interface." His Q226: "Q30: yes." to Mos's reading that a + folder nobody has marked counts as story, and "F43: citations should be + requireable. Tunable setting." Mos's reading of F43: "require-citation + is a setting changed by a human only. Mos's default is off." The text + is drafted from the Case 2 design's ruling after r11, "agents never + write story", b68d79663 on `gosalyn/case2-design`. - Version 1.14 source: Jason's Q176 lines TARGET.md:92 "Brainstorm ideas in a "playground" where new universes can be created", :93 "Brainstorm ideas in a "playground" for books in a universe" and :94 "This means @@ -1168,12 +1182,14 @@ library is the user's own writing repository. - **REQ-LIB-1.** A library project maps the user's writing repository onto universes, books, entity types such as character and place, the - manuscript, and playgrounds. The mapping sits in the organization file + manuscript, playgrounds and supporting folders. The mapping sits in the + organization file and fits the user's own folder layout. Only the human changes it, and an agent's organization write that changes it is refused. So `universe.book.{character,place,...}` reads as universe, book folder, type folder. (Design 1.1 and M9. Q176 Case 2 "Data is stored in - little-endian organizational scheme".) + little-endian organizational scheme". Version 1.15: supporting + folders.) - **REQ-LIB-2.** Playgrounds are never confused with canon. A playground has one of three levels, set by where its prefix sits. A book-level prefix lies inside one of its universe's book folders, and its files @@ -1186,15 +1202,20 @@ library is the user's own writing repository. mapping is refused when a prefix lies inside or holds another universe's book folder, when a prefix equals or holds a book folder of its own universe, when two prefixes overlap, when a draft has books or - no prefix, and when a hybrid names a draft as a source. A file's scope - comes from its path alone, prefixes first: a Markdown file under a - playground prefix at any level is playground, any other Markdown file - in a book folder is canon, and everything else is unmapped and never - returned. Lookups return canon unless the caller asks for playground. - An agent can't cite a playground file as a fact, a finding or a - correction. The Console shows each cite's scope. (Design 1.2, 5.2 and - 7.4, and the playground ruling, 51fdfb7e2. Q176 Case 2, the playground - items, TARGET.md:92-94. Version 1.14: the levels and the draft.) + no prefix, and when a hybrid names a draft as a source. Supporting + prefixes, the folders agents may write in (REQ-LIB-6), follow the same + placement rules. A file's scope comes from its path alone, prefixes + first: a Markdown file under a supporting prefix is supporting, one + under a playground prefix at any level is playground, any other + Markdown file in a book folder is canon, and everything else is + unmapped and never returned. A folder in both lists is supporting. + Lookups return canon unless the caller asks for playground or + supporting. A citation marked as canon must name a canon file, so an + agent can't cite a playground or supporting file as canon. The Console + shows each cite's scope. (Design 1.2, 5.2 and 7.4, the playground + ruling, 51fdfb7e2, and the ruling after r11. Q176 Case 2, the + playground items, TARGET.md:92-94. Version 1.14: the levels and the + draft. Version 1.15: supporting.) - **REQ-LIB-3.** Universes stay separate. Every lookup names one universe, and its results never leave it. A draft universe (REQ-LIB-2) counts as a universe here. It has no canon, so a lookup in a draft asks for @@ -1229,18 +1250,25 @@ library is the user's own writing repository. item and "Connections are always visible".) - **REQ-LIB-6.** The creative roles are ideas, research, proofreader, fact-checker and continuity, plus a companion role that the user's own - named agents run as. No creative agent can write to the user's - repository. Its tools are the lookups and a message to the human, and - research and companion also fetch web pages through the broker. Every - message an agent sends the user is a short list of items. Each item - cites a line of the repository at a commit, or a page the agent - fetched, and the broker checks every cite before it stores the message. - The one exception is a message with no items and one of three fixed - notices: no cited answer, no answer, or the turn failed. The Console - shows each notice as a fixed line, with no text from the model. - The user sees only stored messages, on every channel. (Design 4, 5.1, - 5.2 and 5.3; Q180 for Bean and Chet. Q176 Case 2, the agent list and - "User sets strict guardrails for agent capabilities".) + named agents run as. Agents never write the story. A creative agent may + create, edit and delete Markdown files only under the supporting + folders a human marks (REQ-LIB-1), such as character sheets, summaries, + cross-link notes and research notes. Every other path in the user's + repository is read-only to it, chapters and unmarked folders included, + and the broker refuses such a write before any git call. Each agent + write is one commit by that agent's own Gitea account, with a trailer + naming the agent. The user sees a notice for it and can revert it. Its + tools are the lookups, a message to the human and the two write tools, + and research and companion also fetch web pages through the broker. + Agents talk with the user in free text. A reply may cite lines of the + repository at a commit or pages the agent fetched, and the broker + checks every citation before it stores the message. A setting, + `requireCitation`, makes every reply carry a citation. Only the human + changes it, and it is off by default. The user sees only stored + messages, on every channel. (Design 4, 5.2 and the ruling after r11. + Q223 and Q226. Q180 for Bean and Chet. Q176 Case 2, the agent list, + "User sets strict guardrails for agent capabilities" and TARGET.md:101 + "Agents NEVER write prose for the user". Version 1.15.) - **REQ-LIB-7.** The user talks to several creative agents in one chat. A room holds one thread per creative agent in a project. A message goes to every agent in the room, or only to the agents named by @tags at its @@ -1591,11 +1619,14 @@ latest-by date and a hard target (Q176). - REQ-PROJ-1's "no remote" covers project record repositories. A library project is a separate kind with no record repository, and its mirror fetches from the remote (design 2.1, 7.2). - - REQ-LIB-6 has a stated residual: an `idea` item carries free text, - up to 5 items of 200 characters per reply, and code can't tell story - text from advice (design 5.1). Accepting it is Jason's or Melanie's - (design section 10, step 8). It goes to Jason through Mos - (vikunja:19/465). + - REQ-LIB-6 has a stated residual: a supporting doc can hold any text, + a drafted scene included, and code can't tell a scene from a note. + Every agent write shows as a notice and a commit trailer, and the user + can revert it. Nothing an agent writes lands in a story path. The + agent's Gitea token can write any path of the repository, and the + bus's path check is the only path limit, which holds while the bus + code does (design, ruling after r11). (Version 1.15 replaced the + item-list residual. The old text is in the Version 1.15 note.) - Where each id is built: REQ-USER-3 and REQ-USER-4 are rows 193a to 193d (#1691), with FED R1 to R6. REQ-LIFE-1 is row 194 (#1692) and its follow-up row 239. REQ-KILL-1 is row 191 (#1689). The REQ-LIB ids @@ -1678,6 +1709,45 @@ latest-by date and a hard target (Q176). candidates if they have started. C2-12's setup sheet gets one line per level (design section 8). Sage files it under Vikunja 464. This amendment adds the requirements only. +- Version 1.15: + - The 1.14 text of REQ-LIB-6 was: "The creative roles are ideas, + research, proofreader, fact-checker and continuity, plus a companion + role that the user's own named agents run as. No creative agent can + write to the user's repository. Its tools are the lookups and a + message to the human, and research and companion also fetch web pages + through the broker. Every message an agent sends the user is a short + list of items. Each item cites a line of the repository at a commit, + or a page the agent fetched, and the broker checks every cite before + it stores the message. The one exception is a message with no items + and one of three fixed notices: no cited answer, no answer, or the + turn failed. The Console shows each notice as a fixed line, with no + text from the model. The user sees only stored messages, on every + channel. (Design 4, 5.1, 5.2 and 5.3; Q180 for Bean and Chet. Q176 + Case 2, the agent list and "User sets strict guardrails for agent + capabilities".)" + - The 1.12 note's REQ-LIB-6 residual was: "an `idea` item carries free + text, up to 5 items of 200 characters per reply, and code can't tell + story text from advice (design 5.1). Accepting it is Jason's or + Melanie's (design section 10, step 8). It goes to Jason through Mos + (vikunja:19/465)." Q223 removed the item list, and the residual went + with it. The note now states the new one. + - REQ-LIB-1 gains "and supporting folders" in its first sentence and a + version tag. REQ-LIB-2 gains the supporting scope, its placement rule + and the canon-cite rule, which replaces "An agent can't cite a + playground file as a fact, a finding or a correction." The rest of + both is unchanged. + - REQ-LIB-3, REQ-LIB-4, REQ-LIB-5 and REQ-LIB-7 are unchanged. REQ-LIB-4 + already says bus writes and pushes come in later rows (C2-02, + C2-03b), which covers agent writes and the user's Console saves. Its + fetch still uses a read-only token, now the chief of staff's read + grant. + - The titles of REQ-LIB-1, REQ-LIB-2 and REQ-LIB-6 in + `packages/tasks/requirements.json` change with their text. The id + count stays 85. + - The new refusal codes, settings and row order are in the design's + ruling after r11 and in the Q226 briefs of + `docs/plans/2026-10-20_case2-rows.md`. Sage files the rows under + Vikunja 416. This amendment adds the requirements only. ## Risks and open questions diff --git a/packages/tasks/requirements.json b/packages/tasks/requirements.json index 360cd16b5..a079888e0 100644 --- a/packages/tasks/requirements.json +++ b/packages/tasks/requirements.json @@ -1,6 +1,6 @@ { "prd": "docs/prd/mosaic-stack.md", - "version": "1.14", + "version": "1.15", "requirements": [ { "id": "REQ-ROLE-1", "title": "Each role is a reviewed roles/.json: contract, authority map, credentials" }, { "id": "REQ-ROLE-2", "title": "One holder per role instance, one per assistant session; the chief of staff may end a run, others need a decision" }, @@ -77,12 +77,12 @@ { "id": "REQ-SESS-1", "title": "Each session shows its lifetime count of completed compactions on pi and Claude Code; an unproven count shows unknown" }, { "id": "REQ-SESS-2", "title": "Clear context retires a session after a safe stop and starts a fresh successor with none of the old context" }, { "id": "REQ-SESS-3", "title": "Every session start passes the launch checks: authority, route, revocation, kill switch, limits and admission" }, - { "id": "REQ-LIB-1", "title": "A library maps the user's writing repository onto universes, books, types and playgrounds; only the human changes it" }, - { "id": "REQ-LIB-2", "title": "Scope comes from the path; lookups default to canon and a playground file is never cited as canon" }, + { "id": "REQ-LIB-1", "title": "A library maps the user's repository onto universes, books, types, playgrounds and supporting folders, set by a human" }, + { "id": "REQ-LIB-2", "title": "Scope comes from the path, lookups default to canon, and a playground or supporting file is never cited as canon" }, { "id": "REQ-LIB-3", "title": "Universes stay separate; a crossover is a hybrid universe only a human creates, reading its sources' canon" }, { "id": "REQ-LIB-4", "title": "Git holds every change; the bus fast-forwards a read-only mirror every 60 seconds and agents read only that" }, { "id": "REQ-LIB-5", "title": "Agents check the library through typed lookup tools that name the commit and show links out and in" }, - { "id": "REQ-LIB-6", "title": "Creative agents can't write the repository; messages to the user are cited items the broker checks, or a fixed notice" }, + { "id": "REQ-LIB-6", "title": "Agents never write story, only docs in supporting folders a human marks. Chat is free text, and any citation is checked" }, { "id": "REQ-LIB-7", "title": "One chat room with several creative agents, addressed by leading @tags; an unknown tag sends nothing" }, { "id": "REQ-INST-1", "title": "The installer offers optional components: pinned, health-checked, removable, switched on in config; first is SearXNG" }, { "id": "REQ-INST-2", "title": "With no OIDC provider to configure, the installer deploys a bundled Pocket ID, Q203 (post-v1)" }, diff --git a/packages/tasks/tests/requirements.test.mjs b/packages/tasks/tests/requirements.test.mjs index cadc7df24..759b011fc 100644 --- a/packages/tasks/tests/requirements.test.mjs +++ b/packages/tasks/tests/requirements.test.mjs @@ -21,7 +21,7 @@ test("the list holds the PRD's requirement ids, in its order, at its version", ( assert.equal(ids.length, 85); assert.deepEqual(list.requirements.map((r) => r.id), ids); assert.match(prd, new RegExp(`^- Status: approved, version ${list.version.replace('.', '\\.')}\\.`, 'm')); - assert.deepEqual([list.prd, list.version], ['docs/prd/mosaic-stack.md', '1.14']); + assert.deepEqual([list.prd, list.version], ['docs/prd/mosaic-stack.md', '1.15']); }); test('the committed list loads frozen', () => {