mosaicstack/stack
25
0 Fork 1
Code Issues 404 Pull Requests 13 Packages Projects Releases 15 Wiki Activity

sage: PRD 1.17 draft 9 (7dfc52fd), d8 plus Jason's Q41 O2 (Q239, mos-1467): REQ-LIB-5 requires the Console Connections view for converted chapters, note and Risks line follow, J-b records the answer; Webby round 5 N15-N17

Browse Source
This commit is contained in:
jason.woltje committed 2026-10-23 10:25:37 -05:00
1 parent 7b25a60633
commit 4863e2caf4
3 files changed
+1412
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

agents/sage/work/prd-1-17/DRAFT-d9.md
+647
View File
@@ -0,0 +1,647 @@
# PRD 1.17 draft: Case 2 story files are DOCX (Q235 to Q237, P1 to P6)
Sage, 2026-10-23, for mos-1366 item 1 and Vikunja 570. Draft 9. It is d8 plus Jason's Q41 answer O2 (DECISIONS Q239, mos-1467), which makes J-b yes, and Webby's round 5 N15 to N17 (webby-0210) (see "d9 changes"). d8 is d7 plus Mos's d8 fix list mos-1443 (see "d8 changes"). d7 is d6 plus Mos's ruling mos-1379 on Fenton's 571 B2 (see "d7 changes"). d6 is d5 with Webby's round 3 (webby-0207) fixed: B1 to B3 and N10 to N13, with N14 left for Mos (see "d6 changes"). d5 folds in:
- Mos's d4 check ruling mos-1372 (D1 to D14; D15 was dropped).
- mos-1374, which replaces J-c.
- The impact map mos-1368 (jason-master-restart d183246, `projects/mosaic-mvp/case2-docx-impact-map.md`: A1 to A16, critic items C1 to C6, items 2 to 7).
- Mos's F4 measurement.
Review order (mos-1367 B5): Webby, then Mos, then Jason. Base: PRD 1.16, `docs/prd/mosaic-stack.md` blob a6db9b4a at 482e865ac.
1.16 lands first (row 291), and this text is a new version on top of it. Nothing here is built or queued. The impact map's queue changes (A24, A57 to A59) go through `scripts/mosaic queue` after 1.17 is approved (C9).
Sources, verbatim in Mos's DECISIONS:
- Q235, Jason's Q36 answer.
- Q236: chapters are DOCX, Markdown for agent files and docs.
- Q237: "It is correct for now (subject to future change)".
- The P1 to P6 reading as restated to Jason in Q38.
## Settled points (mos-1367)
These stand as ruled. d5 changes only what mos-1372 changed.
- **O1. Where a converted chapter lives.** The DOCX lives in the writing store of
O2 design D12, and the archived Markdown stays in the user's repository under a
human-marked archive folder. Ruled yes in B1, on the condition that the text
says plainly that a converted chapter leaves the Gitea-mirrored repository and
lives in the stack's writing store. mos-1372 D7 and mos-1375 add a remote for
the store, off the stack's host.
- **O2. The unit of conversion.** One story file per import, refusing a file
that is already converted. Ruled yes in B2: each file gets its own fidelity
report, human confirmation, manifest and commit.
- **O3. Whether conversion is a vocabulary action.** A human-only verb outside
the agent vocabulary, with no role grant and no agent request path. Ruled yes
in B3.
- **O4. Reading archived Markdown.** A new `archived` scope. Lookups leave it out
unless the caller asks, every answer marks it archived, and a canon citation
can't name it. Ruled yes in B4.
## d3 choices after mos-1372
- **C1 is replaced by D1, keep-source-scope.** A DOCX keeps its source's scope:
universe, book, and canon or playground. A playground DOCX follows the
playground rules and is never returned as canon. The import accepts canon and
playground story files. Type-folder files and supporting files stay Markdown
(P4). This also settles the impact map's Q18, item 4. It leaves one narrowing
for Jason, J-i. A playground DOCX can't become canon in 1.17.
- **C2 stands.** The move keeps the file's path under the archive folder:
`book1/ch3.md` goes to `<archive>/book1/ch3.md`. An archived file's universe
and book are those of its old path.
- **C3 is replaced by D3 and D14.** The archive commit is written by a new
human-only bus step (Vikunja 571) on the C2-02 write plumbing and pushed through
C2-03b. The order is the store commit and the remote's confirmation that it
holds that commit, then the archive commit and its push, then publication to the
lookups.
- **N4 stands.** REQ-LIB-8 says "a real user's books". The PRD names no user
anywhere in Case 2.
## Text changes
### Status and sources
In the Status bullet's first line, "- Status: approved, version 1.16." becomes
"- Status: approved, version 1.17." Status gains, after the two 1.16 sentences at
the end of the bullet: "Version 1.17 records Jason's rulings Q235 to Q237 of
2026-10-23: Case 2 story files are DOCX, Markdown stays for agent files and
documentation, and a human-started import converts a Markdown story file one way.
It also adds REQ-LIB-9, the Console's DOCX editor, from Jason's rulings Q195, Q226
and Q234. It changes what Case 2 requirements allow, so Mos puts the text to Jason
as written, and it lands only after his yes (mos-1366, Vikunja 570)."
New source line, above the 1.16 one: "Version 1.17 source: Jason's Q235, answering
Q36: 'How about we see a markdown file, we convert the markdown file to docx, then
archive or mark the markdown file as converted. The new standard for files in the
creating writing use case is to use docx to handle versioning and WYSIWYG. We
eliminate the potential for confusion based on the files. Agents must understand
which files are what format and where they live. The system must allow for import
and conversion. We will not run the systems in parallel. There will be an
irreversible conversion of the files.' His Q236 says: 'For creative writing
chapters, we need to utilize docx as the standard. Markdown is acceptable for
agent files, instructions, PRDs, documentation, etc. The creative writing files
should be docx for familiarity for the user.' His Q237 says 'Q38: It is correct
for now (subject to future change)', which confirms Mos's reading P1 to P6.
REQ-LIB-9 rests on his Q195 request for 'a full WYSIWYG editor within Mosaic
Stack', his Q226 answer 'F41: We want to move editing into the WYSIWYG in the
WebUI. All changes are instantly committed and available to the agents.' and his
Q234 answer 'Q37: yes' to the exact security header for the editor's frame. The
storage follows the O2 design D10 to D12 as rewritten under Vikunja 571, at
b99ca86b9 on `refactor`."
### Creative library, section lead
Replace "The library is the user's own writing repository." with "The library is
the user's own writing repository plus the stack's writing store, which holds the
DOCX story files (REQ-LIB-8, version 1.17)."
### REQ-LIB-1
Add, before "(Design 1.1": "The mapping also names one archive folder, set by the
human, where converted Markdown story files go. A book's DOCX story files are in
the stack's writing store, under the same universe and book (REQ-LIB-8)." Version
tag, inside the closing parenthesis: "Version 1.15: supporting folders.)" becomes
"Version 1.15: supporting folders. Version 1.17: the archive folder and the
writing store.)"
### REQ-LIB-2
Replace "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." with:
"A Markdown file's scope comes from its path and from past imports, prefixes
first: a Markdown file under the archive folder is archived, one under a
supporting prefix is supporting, a Markdown file at a converted file's old path is
unmapped under REQ-LIB-8 but flagged in the format map, 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. The archive folder follows the same placement rules and may not
overlap another prefix or a book folder. An archived file keeps the path it had
under the archive folder, and its universe and book are those of that old path. A
DOCX document in the writing store keeps its source's scope: the universe, the
book if there is one, and canon or playground. Its source is the Markdown file it
was converted from or, for one the human starts in the editor, the universe and
book or the playground the human picks (REQ-LIB-8). A playground DOCX follows the
playground rules and is never returned as canon. It stays playground after its
draft universe is made real. In version 1.17 no promotion or mapping change makes
a playground DOCX canon. A later version of this PRD says how one becomes canon."
Replace "Lookups return canon unless the caller asks for playground or
supporting." with "Lookups return canon unless the caller asks for playground,
supporting or archived. Every answer marks an archived file as archived and names
the DOCX that replaced it."
Replace "so an agent can't cite a playground or supporting file as canon" with "so
an agent can't cite a playground, supporting or archived file as canon".
In REQ-LIB-2 only, replace "The Console shows each cite's scope." with "The Console shows each cite's
scope and format, and whether a cited Markdown file was converted."
Version tag, inside the closing parenthesis: "Version 1.15: supporting.)" becomes
"Version 1.15: supporting. Version 1.17: archived scope and DOCX scope.)"
### REQ-LIB-4
Replace "The user commits and pushes with their own tools, today Obsidian with
obsidian-git." with "The user commits and pushes Markdown with their own tools,
today Obsidian with obsidian-git. A converted story file's current text is no
longer in that repository, which keeps only its archived Markdown (REQ-LIB-8)."
Add, after "Bus writes and pushes come in later rows (C2-02, C2-03b).": "A DOCX
story file is saved in the Console's editor, and each accepted save is one commit
by the human in the stack's writing store (REQ-LIB-9). Each writing-store commit
is also pushed to a remote off the stack's host, never by force-push. The remote
is a setting only a human changes, and it starts unset. A repository on the
stack's host never counts as that remote. A missing remote or a failed push never
undoes a save, and the user sees each push that is pending or failed. Only the
stack's host pushes to that remote, and no agent can reach it with any credential.
Agents read the local commit."
Replace "Agents read only the mirror's served commit and never hold a copy of
their own, so they see the user's push within about a minute." with "Agents read
the user's repository only at the mirror's served commit, except a story file
during its import under REQ-LIB-8. They read a DOCX story file only at a committed
version in the writing store, under REQ-LIB-5. They never hold a copy of their
own, so they see the user's Markdown push within about a minute and a DOCX save at
their next lookup after the editor reports it as committed."
Version tag: "and the sync items.)" becomes "and the sync items. Version 1.17,
with Q222 for the remote setting.)"
### REQ-LIB-5
Add, after "Each answer names the commit it read.": "Each answer also names the
file's format and where it lives: its path, or its document id in the writing
store. A DOCX story file is read from its latest committed save, never from
unsaved text. A lookup that starts after the editor reports a save as committed
returns that save or a later one, even while its push to the remote is pending or
has failed, and the answer names the version. Get, search and manuscript read a
DOCX story file as its extracted text with DOCX locators, never as lines. That
text is the file with its tracked changes accepted. An agent reads a story file's
comments, or its text with tracked deletions shown, only after a human turns on
the matching setting. Both settings are off by default, and only a human changes
them. The reader in this version can't read some things a DOCX story file can
hold, such as a web link, a text box, a field or hidden text. The editor warns the
human when an edit adds one, and the human can still save it. Until a later save
takes it out, lookups give agents none of the text of the part that holds it,
whether that is the chapter's body, a note or a comment. The manuscript lookup
follows the book's chapter order across both formats (O2 design D10), and the next
chapter it names is never an archived file. Links out and in resolve across both
formats. The universe lookup returns the format map (REQ-LIB-8)."
Replace "The user sees them in Obsidian's graph and backlinks." with "The user sees
a Markdown file's links in Obsidian's graph and backlinks. A DOCX story file's
wikilinks stay clickable in the Console's editor (O2 design D11). The Console
shows a converted chapter's links out and in, in a Connections view."
Version tag: 'and "Connections are always visible".)' becomes 'and "Connections
are always visible". Version 1.17, with Q222 for the two settings.)'
### REQ-LIB-6
Replace "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." with
"A reply may cite lines of a Markdown file at a commit, a place in a committed
DOCX story file, or pages the agent fetched, and the broker checks every citation
before it stores the message. A DOCX citation never calls a paragraph a line. It
names the document id, the committed version and a DOCX locator. A citation that
names an archived file as current is refused. The `requireCitation` setting below
applies to Markdown and DOCX citations alike, and so does the rule for a citation
marked as canon."
Add, after "the broker refuses such a write before any git call.": "The writing
store and the archive folder are read-only to a creative agent as well, and the
broker's path check treats the archive folder as story. No agent creates, edits,
deletes, converts, archives or restores a story file in any format, and no agent
writes a DOCX. No creative agent starts or undoes a conversion, and none asks for
one through a tool or a decision it raises, as REQ-LIB-8 says. An agent may still
suggest a conversion to the human in chat. Each creative role's contract states
which files are DOCX and which are Markdown, and cites a DOCX story file by its
locator, never by line."
Version tag, inside the closing parenthesis: "Version 1.15.)" becomes "Version
1.15. Version 1.17.)"
### New REQ-LIB-8
This bullet goes after REQ-LIB-7 and before the "### Installer" heading.
"- **REQ-LIB-8.** Story files become DOCX. DOCX is the standard for chapters and
the other story text in a Case 2 writing project, canon and playground alike. A
story file becomes DOCX through a human's import (below), or when the human
starts it in the editor. From then on DOCX is its only working format, edited in
the Console's editor (REQ-LIB-9). A Markdown story file stays Markdown until its
import. Files in a type folder (REQ-LIB-1), such as character and place notes,
stay Markdown. So do supporting files, agent files, instructions, PRDs and
documentation, including the character sheets, summaries and cross-links agents
keep under REQ-LIB-6.
- A converted story file's current text leaves the user's Gitea-mirrored
repository. Its DOCX lives in the stack's writing store, on the stack's host,
and not in the repository the user pushes or opens in Obsidian. Only its
archived Markdown stays there.
- An import converts one Markdown story file, canon or playground, outside every
type folder (REQ-LIB-1), to a DOCX document in the writing store. It refuses
an unmapped, supporting, archived or type-folder file, and a file that is
already converted. Each import has its own fidelity report, the human's
confirmation of that report, a manifest naming the source file and its commit,
and one commit in the store. The DOCX keeps every wiki link of the source as
written, and a lost link to another library file fails the fidelity report. A
web link becomes plain text that keeps its label and address, and the fidelity
report lists it for the human to confirm. A web link that can't be kept safely
as plain text refuses the import.
- The human can also start a new story file in the editor, in a universe and
book or a playground the human picks. It is a DOCX document in the writing
store from its first commit, with no Markdown copy, and it opens under the
same gate as the import.
- The same import marks the Markdown file converted, naming the document, and
moves it to the archive folder under its old path (REQ-LIB-1, REQ-LIB-2).
The mark and the move are one commit authored by the human in the user's
repository. A new human-only bus step (Vikunja 571) on the C2-02 write
plumbing writes it, and C2-03b pushes it. The move keeps the bytes and the
git history, so it isn't `data.delete`.
- The store commit comes first, and the writing store's remote must confirm it
holds that commit. Then come the archive commit and its push, then publication
to the lookups. Until publication the Markdown at its old path keeps its canon
or playground scope. Agents read that file at the commit the import started
from, even after the mirror's served commit reaches the archive commit or a
later one. No lookup returns the file's archived copy before publication, even
one that asks for archived files. A refusal or failure before the archive push
leaves the Markdown unmoved and no DOCX that a lookup returns. A failure after
the archive push leaves a pending import that the human sees and can resume,
never a claim that nothing moved. An archive push whose result is unknown
counts as a failure after the archive push until the stack reads the result
back from the user's remote.
- Each stage of an import writes a logged event. The import's record on the
stack's host names the source file's path, commit and blob and the new
document id, and each event points to that record.
- After a conversion, a Markdown file at the converted file's old path is
neither canon nor playground. Lookups leave it out, the format map flags it,
and the human is told.
- A new Markdown story file in a book folder that holds converted files stays
canon until its import, unless it sits at a converted file's old path or under
a playground prefix. The Console flags it and offers the import. Nothing
converts it on its own.
- A hybrid's exclusion that covers a converted file's old path also covers its
DOCX document (REQ-LIB-3). An exclusion of a whole book folder also covers
every DOCX document in that book, including one started in the editor. An
exclusion can also name a DOCX document by its id.
- Only a human starts an import or a new story file, from the CLI or a Console
session signed in as that human. Both are human verbs outside the agent action
vocabulary. Neither is added to `ACTIONS` in the business vocabulary or to the
broker's always-gated list, including the import's action, `library.convert`.
No role holds them, no agent can request them, and the hard-wait list in
REQ-WAIT-1 doesn't change. In an organization with several humans, who may
start them is a setting only a human changes, and the default is the owner
only.
- Conversion is one way, with no parallel run. Neither the Console nor any agent
edits a converted story file as Markdown, and no DOCX edit syncs back to
Markdown. The Console's Markdown save refuses every file under the archive
folder. The user's own tools can still change the archived Markdown, and no
such change reaches the DOCX. The old Markdown stays in git history, and
nothing rewrites history. A promotion into a book folder (C2-19) runs the
import for a Markdown story file or is refused. A promotion of a playground
DOCX is refused in version 1.17.
- Agents get a format map: for each mapped folder and story file, its format,
scope and where it lives, archived files, flagged files and pending imports
included.
- The import and new story files ship closed. They open only after four things.
The editor ships. The human has set the writing store's remote, and the stack
has checked that it can push there. Agents can read committed DOCX story files
through the lookups and cite them (REQ-LIB-5, REQ-LIB-6). Any earlier agent
system that writes the user's files has stopped, which for Case 2 is the
Hermes retirement (#423 step 5). So the import itself never cuts agents off
from a chapter, the chapter's current text never lives only on the stack's
host, and no second system writes the story. The first import of a real user's
books waits for Jason's go.
(Q235, Q236, Q237: P1 to P6. Q222 for the setting. O2 design D10 to D12.
Version 1.17.)"
### New REQ-LIB-9
This bullet goes after REQ-LIB-8.
"- **REQ-LIB-9.** The Console's DOCX editor. The human edits a DOCX story file in
the Console's editor, in a split pane with the agent chat alongside it. The
human can pin an agent chat to a document. The human can select a word,
right-click it, and choose a synonym from a thesaurus. Only a human saves. Saves
happen on their own while the human types (Q226), at intervals only a human
changes, and each accepted save is one commit with the human as author, pushed
as REQ-LIB-4 says. A save made against an older version than the current one is
refused. Agents never write a DOCX. Versioning is the editor's tracked changes
plus one git commit per save. The editor's code is vendored and pinned, with a
hash per file and the licenses that its independent security review accepted. At
runtime the editor loads only files that the stack itself serves, and it
requests nothing from any other host. The editor's frame sends exactly the
content security policy Jason approved in Q234, and the WebUI shell's own header
is unchanged. REQ-PROJ-3's project docs editor is unchanged. (Q195, Q226, Q234,
Q236. O2 design D3, D4, D6, D8, D10, D13, D14, D16 and D22. Version 1.17.)"
### Version 1.17 notes
Added after the 1.16 notes:
"- Version 1.17:
- Jason confirmed the reading 'for now (subject to future change)' (Q237). The
rulings stand until he revises them.
- The 10-27 Case 2 release ships on Markdown as built (P6). The 1.11 line 'The
Case 2 MVP for 10-27 is the Markdown library (#416). The WYSIWYG editor (Q195,
Q196) is an add-on that doesn't gate it.' still holds. Conversion opens after
10-27, and only once REQ-LIB-8's four conditions are met. The editor ships,
the writing store's remote is set and the stack has checked that it can push
there, agents can read and cite committed DOCX story files through the
lookups, and Hermes is retired, which is #423 step 5.
- The 1.12 note says five bus write and Console editor rows, C2-02, C2-03b,
C2-11a, C2-11b and C2-19, don't gate 10-27. Jason's Q226 F42 later moved
C2-02, C2-03b and C2-11b into the 10-27 slice. The Case 2 design brings C2-11a
in with them, because C2-11b needs it. C2-19 stays outside the slice. Mos's
reading of F42 is that C2-02 and C2-03b now gate 10-27, because design 9.2
puts them in 'the smallest slice that lets her start'. C2-11a and C2-11b are
slice rows that still don't gate 10-27, because the editor is the Q195 add-on.
The DOCX change in 1.17 leaves this slice as it is, and C2-11b's Markdown
editor never edits a converted story file.
- Q236 narrows Q176's editor choice to DOCX for story files (REQ-LIB-9). The
1.12 note that the Case 2 design keeps Obsidian now holds only for Markdown
files, including story files not yet imported. A DOCX story file is edited
only in the Console's editor under REQ-LIB-9.
- This replaces two parts of the O2 design at 25c09f19f. The superseded-notice
proposal from Fenton's F1 in D12 is withdrawn, and the
keep-Markdown-at-its-path model of D11 is replaced. Gyro's rewrite of the O2
design for Vikunja 571, landed on `refactor` at b99ca86b9, carries the
details, and where it differs from this text, this text holds:
- the import and archive steps, the mark, and the new bus step;
- links from supporting files to a moved chapter;
- the DOCX reader;
- the user's unpushed or later changes to an archived file or at its old path,
and pushing and closing the file in Obsidian before each import;
- the writing store's remote in W4 section 7.3, which replaces the no-remote
and no-backup rule that W4 section 7.4 held before the rewrite, at
062646487;
- import events counted by a bus restore, and recovery when a bus restore or a
restore of the whole host predates an import;
- manifest order for the manuscript lookup and its next chapter;
- `library.convert` kept out of `ACTIONS`, out of the hard-wait note and out
of the pinned `GATED_ONLY` list in packages/business/src/vocabulary.mjs.
- Agents read a converted story file through the Case 2 lookups under the same
project and universe access as Markdown canon, in any thread or room. W4's
earlier O2-only conversations, per-document grants and per-send sharing don't
gate these lookups. The 571 rewrite replaced them in W4 sections 7.1 and 7.2.
The creative tool list in REQ-LIB-6 doesn't change.
- The six creative role contracts row 213 landed say 'Every item cites the
lines of the user's material it is about'. A build row under 571 changes that
line for DOCX story files (REQ-LIB-6).
- A new Markdown file in a book folder is still canon in 1.17. The 1.17
exception is a file at a converted file's old path, which REQ-LIB-2 makes
unmapped.
- Story files convert whether canon or playground. Type-folder and supporting
files stay Markdown.
- Measured 2026-10-23 at about 01:21Z: the Case 2 user's library repository
tracks 213 files, 203 of them Markdown, and none is a .docx or .doc. It has no
untracked files. The user's .doc files (Q196) are outside it. So the landed
code has no DOCX there to report as unreadable at 10-27.
- Text replaced in 1.17, kept here as in earlier notes:
- Creative library lead, the 1.16 sentence: "The library is the user's own
writing repository."
- REQ-LIB-2, the 1.16 sentences: "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." "so an agent
can't cite a playground or supporting file as canon" "The Console shows
each cite's scope."
- REQ-LIB-4, the 1.16 sentences: "The user commits and pushes with their own
tools, today Obsidian with obsidian-git." "Agents read only the mirror's
served commit and never hold a copy of their own, so they see the user's
push within about a minute."
- REQ-LIB-5, the 1.16 sentence: "The user sees them in Obsidian's graph and
backlinks." A converted chapter's connections show in Obsidian only as they
stood at conversion. The Console's Connections view shows their current
links.
- REQ-LIB-6, the 1.16 sentence: "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."
- REQ-LIB-1 only gains sentences.
- REQ-LIB-3's text and REQ-LIB-7 are unchanged. REQ-LIB-8 adds one form of
exclusion REQ-LIB-3 doesn't have: naming a DOCX document by its id. A path
exclusion also covers DOCX documents, through a converted file's old path or a
whole book folder. An archived file and a DOCX document keep a universe, and a
book where their source has one, so every lookup still names one universe.
REQ-PROJ-3, the Console editor for a project's spec and docs, is unchanged.
C2-11b opens the library's Markdown files in that same editor.
- In `packages/tasks/requirements.json` the titles of REQ-LIB-1, REQ-LIB-2 and
REQ-LIB-4 change, and those of REQ-LIB-5 and REQ-LIB-6 stay. REQ-LIB-1 becomes
'A human-set library maps the user's repository onto universes, books, types,
playgrounds, supporting and archive folders'. REQ-LIB-2 becomes 'Scope comes
from the path or a DOCX's source, lookups default to canon, and only canon
files are ever cited as canon'. REQ-LIB-4 becomes 'Git holds every change. The
bus fast-forwards a read-only mirror every 60 seconds, the one place agents
read Markdown'. REQ-LIB-8 and REQ-LIB-9 add two ids, so the count goes from 85
to 87. REQ-LIB-8 is titled 'Case 2 story files become DOCX by a human-only
one-way import or in the editor; Markdown stays for notes and docs', and
REQ-LIB-9 'The Console's DOCX editor: only a human saves, each save is one
commit, and the editor code is vendored and pinned'.
- Open points O1 to O4 of draft 1 were ruled by Mos in mos-1367 B1 to B4.
- Sage files the build rows under Vikunja 570 and 571 after the rewrite is
approved. This amendment adds the requirements only."
### Risks
The new lines go at the end of "## Risks and open questions", after the bullet
that begins "Trusted mode lets an agent" and before the "## Milestones" heading.
- "A DOCX file is a zip archive, so git can't show a line diff of a chapter.
Review of a story change goes through the editor and the committed reader,
not `git diff`. (Version 1.17.)"
- "A converted chapter's DOCX is not in Obsidian's graph. Obsidian shows the
chapter only through its archived Markdown, and no DOCX edit reaches that file's
links. The DOCX's current links show in the Console's editor and its
Connections view, not in Obsidian. (Version 1.17.)"
- "Conversion can't be undone in place. Front matter, wiki link forms and
unsupported blocks may not survive it, and the mirror can't refuse the user's
push to an archived file. The controls are the fidelity report, the human's
confirmation, an untouched original on refusal, and the kept archive.
(Version 1.17.)"
- "A restore of the stack's bus alone from a backup taken before an import drops
the import's logged events, while the archive commit and the DOCX stay. A
restore of the stack's whole host from such a backup also takes the writing
store and the host's import records back to before the import. The archive
commit stays in the user's Gitea repository and the DOCX stays on the writing
store's remote, but the host keeps no record of the import. A bus restore counts
import events, and the import's recovery covers both cases (Vikunja 571).
(Version 1.17.)"
## d9 changes (Q239 and Webby round 5)
- J-b yes (Q239, mos-1467): REQ-LIB-5's replacement ends "The Console shows a converted chapter's links out and in, in a Connections view." in place of "and no graph shows them yet". The REQ-LIB-5 note and the graph Risks line name the view as required, not later. J-b and the "Not taken" A6 line record the answer. Nothing else in the PRD text changes.
- N15: the D7 landing line gives R8's wording beside the impact map's quote.
- N16: the d7 changes line notes that R8 replaces "no agent credential reaches it" in d8.
- N17: the REQ-LIB-2 Replace quote and the REQ-LIB-8 old-path bullet are rewrapped under 82 columns. Their words are unchanged.
## d8 changes (Mos's d8 fix list, check wf_63bba879-180)
- R1: REQ-LIB-4's tail covers DOCX saves, which agents see at their next lookup after the editor reports them as committed. The notes quote the whole 1.16 sentence. Source: nit/jason/F10.
- R2: REQ-LIB-4's new title says the mirror is "the one place agents read Markdown". Source: decisions.n14.
- R3: J-b asks whether 1.17 requires the Console Connections view, with Mos's recommendation of yes. Sources: mos1372/F9, jason/F2, anchors/F5.
- R4: C2-02 and C2-03b gate 10-27, C2-11a and C2-11b are slice rows that don't, and "F42 wins" is gone. New J-k. Sources: anchors/F6, jason/F5.
- R5: where the landed 571 design differs, this text holds. Sources: anchors/F8, adversarial/F8 item 1, jason/F8, critic/C6, G16's design follow-on.
- R6: `library.convert` stays out of `ACTIONS`, and REQ-WAIT-1's hard-wait list doesn't change. Sources: gyro571/F1, adversarial/F8 item 3, critic/C6.
- R7: a repository on the stack's host never counts as the writing store's remote, and Item 2 says so. Sources: mos1372/F2, adversarial/F1, gyro571/F2.
- R8: "no agent credential reaches it" becomes "no agent can reach it with any credential". Source: Fenton's B1 under mos-1379.
- R9: no playground DOCX becomes canon in 1.17, and a promotion of one is refused. New J-i. Sources: mos1372/F8, adversarial/F2.
- R10: REQ-LIB-9 restates Q195's pin and right-click thesaurus, and its cite gains D4 and D22. Source: critic/C4.
- R11: REQ-LIB-9's license bar is the licenses its independent security review accepted. New J-l. Source: critic/C3.
- R12: no text for D16's narrow-window tabs. Mos records that reading in STATE. Sources: jason/F1, second verifier vote.
- R13: no lookup returns a file's archived copy before publication. Source: adversarial/F5 part 3.
- R14: a restore of the whole host from a backup taken before an import is a fourth recovery case. Source: adversarial/F6.
- M1: REQ-LIB-4's writing-store sentences follow the later bus rows sentence and add the off-host remote rules and DOCX read timing. The note quotes both 1.16 sentences. Sources: mos1372/F2, adversarial/F1, gyro571/F2, anchors/F4, nit/jason/F10, adversarial/F5 part 1, Fenton B1.
- M2: REQ-LIB-8's order bullet adds the remote's confirmation, the old-path read rule and "archive push". Sources: mos1372/F2 and the other remote findings, mos1372/F7, adversarial/F5 parts 2 to 4.
- M3: REQ-LIB-8's gate bullet has four conditions, adding the remote. Sources: the remote findings, critic/C1 and C2 edit 2.
- M4: the 1.17 note on when conversion opens restates the four conditions and drops W4b. Sources: jason/F5, the remote findings.
- M5: Item 2 rewritten with the remote rules. Sources: the remote findings.
- M6: the 1.12 gating note rewritten. Sources: anchors/F6, jason/F5.
- M7: REQ-LIB-9 gains the split pane, the pin, the thesaurus, the license bar and the runtime load rule, and cites more of the design. Sources: jason/F1, critic/C4, critic/C3, nit/anchors/F12, nit/gyro571/F9.
- M8: REQ-LIB-2, the one-way bullet and the C1 note keep a playground DOCX out of canon in 1.17. Sources: mos1372/F8, adversarial/F2.
- M9: REQ-LIB-5 says what the reader can't read, and the import turns web links into plain text. New J-j. Sources: critic/C1, critic/C2.
- M10: an exclusion of a whole book folder covers that book's DOCX documents. Source: adversarial/F3, with B5.
- M11: the human-verbs sentence and the 571 list item name `library.convert` and REQ-WAIT-1. Sources: gyro571/F1, adversarial/F8 item 3, critic/C6.
- M12: J-b rewritten. Sources: mos1372/F9, jason/F2, anchors/F5, gyro571/F3, critic/C6.
- M13: J-d puts the agent read model to Jason as his call. Source: mos1372/F1.
- M14: Status moves to version 1.17 and names REQ-LIB-9. Sources: anchors/F2, mos1372/F4, critic/C7.
- M15: the 1.17 source line quotes Q235 in full (mos-1446) and the REQ-LIB-9 sources, at b99ca86b9. Sources: critic/C5, anchors/F9, jason/F8 pin part, nit/gyro571/F8, critic/C6 pin part.
- M16: the 571 list lead names the two replaced design parts and the landed design. Sources: anchors/F9, anchors/F8, adversarial/F8 item 1, jason/F8, critic/C6.
- Landing swap: Gyro's docs round for R5, R6 and R14 landed as b99ca86b9 (Fenton fenton-0015), so M15 and M16 cite b99ca86b9 in place of 767bb62c7, as the d8 fix list's header says. J-b keeps 767bb62c7 for its line numbers.
- M17: W4 section numbers in the remote item and the lookups note. Sources: gyro571/F5, nit/adversarial/F11.
- M18: the D7 landing line. Sources: gyro571/F5, the remote findings.
- M19: a logged event for each import stage, in REQ-LIB-8 and A2. Source: gyro571/F7.
- M20: the Risks line on restores adds the whole-host case. Sources: adversarial/F6, gyro571/F7.
- M21: the 571 restore item adds the whole-host case. Source: adversarial/F6.
- M22: the graph Risks line and the REQ-LIB-5 note name a Console view. Sources: anchors/F5, jason/F2.
- M23: the d6 B3 line drops "F42 wins". Source: anchors/F6.
- M24: new Markdown in a converted book, with the old-path and playground exceptions. Source: mos1372/F6.
- M25: J-c's last sentence is Mos's reading. Source: mos1372/F10.
- M26: J-h rewritten with the D13 defaults. Source: jason/F3.
- M27: Item 4 rewritten. Sources: jason/F4, gyro571/F4, decisions.unmarked_folders.
- M28: the "Not taken" note on unmarked folders. Sources: jason/F4, gyro571/F4, decisions.unmarked_folders.
- M29: the import refuses an unmapped file. Sources: gyro571/F4, decisions.unmarked_folders.
- M30: placement notes for REQ-LIB-8, REQ-LIB-9 and the Risks lines. Sources: anchors/F3, nit/anchors/F14.
- M31: REQ-LIB-4's title and the D11 landing line. Source: decisions.n14.
- M32: the Q236 note limits the 1.12 Obsidian note to Markdown files. Source: critic/C8.
- M33: the exclusion note adds path exclusions of DOCX documents. Source: anchors/F7.
- M34: A9 moves from "Mine" to the impact-map list. Source: decisions.exclusion_by_id.
- M35: the D5 landing line. Sources: anchors/F10, mos1372/F5, nit/adversarial/F12.
- M36: the D9 and D14 landing lines. Source: mos1372/F1.
- M37: the O1 and C3 notes add the off-host remote and its confirmation. Sources: the remote findings.
- M38: the REQ-PROJ-3 note. Source: nit/anchors/F11.
- M39: REQ-LIB-5's freshness sentence keys on the editor reporting a save as committed. Source: nit/adversarial/F9.
- M40: REQ-LIB-6 bars agent requests for a conversion and allows a suggestion in chat. Source: nit/jason/F9.
- M41: REQ-LIB-2's opening and old-path rule, and the "Mine" note. Source: nit/adversarial/F10.
- M42: REQ-LIB-8's lead sentence on Markdown story files. Source: nit/mos1372/F12.
- M43: REQ-LIB-6's citation sentence. Source: nit/anchors/F13.
- M44: REQ-LIB-5's version tag uses plain quotes. Source: nit/anchors/F15.
- M45: reference codes B5, D12, D10 and B4 name their source. Source: nit/mos1372/F11.
- Files the row would own: four files, with the id count going to 87. Sources: anchors/F1, adversarial/F4, decisions.n14 F4.
## d7 changes (mos-1379, Fenton's 571 B2)
- REQ-LIB-5 gains Mos's three sentences after the extracted-text sentence. The text agents read has tracked changes accepted. Comments, and text with tracked deletions shown, each wait for a setting only a human turns on, off by default. Its version tag cites Q222 for the two settings, which is the only text here beyond Mos's.
- J-d gains Mos's sentence on comments and tracked deletions.
- Fenton's B1 is design only. d6's "no agent credential reaches it" holds (R8 replaces it in d8), and the shared helper stays #431.
## d6 changes (Webby round 3, webby-0207)
- B1: titles for REQ-LIB-8 and REQ-LIB-9 in the requirements.json note and the file list. REQ-LIB-9 takes Webby's title. REQ-LIB-8 keeps mine, because Webby's ("...one-way import that archives the Markdown under its old path") leaves out D2's story files started in the editor.
- B2: REQ-LIB-2 makes a Markdown file at a converted file's old path unmapped, ahead of the playground and canon rules, so a playground conversion is covered too. REQ-LIB-8's old-path bullet says "neither canon nor playground".
- B3: the slice note names Q226 F42's three rows (C2-02, C2-03b, C2-11b). C2-11a joined the slice with C2-11b, because C2-11b needs it. Both are slice rows that don't gate 10-27, as design 9.2, case2-rows.md:1655 and the impact map's A57 say. The 'F42 wins' sentence is gone from the note in d8, so no queue change follows from it.
- N10: the cite-scope replacement is scoped to REQ-LIB-2. The 1.14 note's copy stays.
- N11: the notes say REQ-LIB-8 adds the by-id exclusion form REQ-LIB-3 doesn't have.
- N12: J-h marks the autosave intervals for Jason.
- N13: J-b names REQ-LIB-5's "Connections are always visible" tag and Q226's "another way to handle the visual brain map".
- N14, not taken: REQ-LIB-4's title stays internal F3's text, as mos-1372 D11 ruled. Webby's alternative, "...and agents read Markdown from it alone" (120 chars), is Mos's call.
## Where each mos-1372 item landed
- D1: REQ-LIB-2's DOCX sentences, the REQ-LIB-8 lead and import bullet, C1 above, and the notes. "Playground files stay Markdown in 1.17" is gone.
- D2: REQ-LIB-2's "for one the human starts in the editor" and the REQ-LIB-8 new-story-file bullet. The universe-and-book note is now true.
- D3: the REQ-LIB-8 order bullet. This also settles N8.
- D4: REQ-LIB-8's one-way bullet, which carries the archive refusal and consequence F2's text, and the 571 list item.
- D5: it landed in REQ-LIB-2's "a Markdown file at a converted file's old path is unmapped" in Webby's B2 form, and in the REQ-LIB-8 old-path bullet.
- D6: REQ-LIB-5's freshness sentences.
- D7 and mos-1375: REQ-LIB-4's remote sentences, the remote step in REQ-LIB-8's order bullet, the fourth opening condition and the 1.17 note on when conversion opens, plus the 571 list item on W4 section 7.3, which replaces the no-remote rule of the old W4 section 7.4. The impact map's item 2 adds "only the stack's host pushes, and no agent credential reaches it", which R8 words in d8 as "no agent can reach it with any credential".
- D8: the REQ-LIB-5 replacement, the import bullet's wiki-link sentence, the Risks line, the note quoting the old sentence, and "REQ-LIB-1 only gains sentences".
- D9: the 1.17 note that agents read a converted story file through the Case 2 lookups, from the d4 check's consistency B2, and J-d, which puts the read model to Jason as his call.
- D10: the d4 check's B5 sentence, in REQ-LIB-8.
- D11: internal F3's clause in the REQ-LIB-4 section, and in the notes the title as Mos amended it for N14.
- D12: the whole 1.16 sentence replaced, and quoted in full in the notes.
- D13: consequence F1's text, in REQ-LIB-4 and REQ-LIB-8's first bullet.
- D14: the row text from the d4 check's consistency B1, in the mark-and-move bullet and C3 above.
## What d5 adds beyond mos-1372 (for Webby and Mos to check)
From the impact map, folded as mos-1368 item 1 asked:
- A1: the Console shows a cite's format and converted state (REQ-LIB-2).
- A2: the logged events and the several-humans setting, default owner only, under Q222.
- A3: the import is outside the vocabulary, the hard-wait list is unchanged, and the archive move isn't `data.delete`. The C6 code site is in the 571 list.
- A4: the section lead and REQ-LIB-1's writing-store sentence.
- A6: format and location in every answer, extracted text with DOCX locators, links across formats.
- A7: read-only extends to the store and the archive, no agent action on a story file in any format, no agent DOCX write, and role contracts state the formats. C1's role contract line is a 571 build item.
- A8: the DOCX cite shape, and a cite naming an archived file as current is refused.
- A9: a hybrid sees a source's DOCX canon through REQ-LIB-2's source scope, and REQ-LIB-8 lets an exclusion name a DOCX document by its id. The id form lets the human exclude a single DOCX started in the editor, which has no old path. An archived file isn't canon, so no hybrid sees it.
- A10: REQ-LIB-9, so the count is 87, not 86.
- A11: the Hermes gate, from item 3.
- A12: the C2-19 promotion sentence.
- A13: the broker's path check treats the archive folder as story.
- A14 and C5: two Risks lines.
- A15: the flagged-new-file bullet. It sits beside the note from the d4 check's B4, "a new Markdown file in a book folder is still canon". The file stays canon and is offered for import.
- A16: three titles change and two stay.
- C2: manifest order for the manuscript lookup.
- F3: the C2-02 gating note.
- F4: Mos's measurement.
Mine, beyond either source:
- REQ-LIB-2 opens "A Markdown file's scope comes from its path and from past imports". DOCX scope comes from the source, so "a file's" would be false.
- REQ-LIB-9's autosave sentence. It is Mos's reading of F41's "instantly committed", with human-set intervals. The exact intervals stay in the design.
Not taken:
- Impact map item 4's "files in unmarked folders are eligible one at a time", for folders outside every book folder and playground only. Their files are unmapped under REQ-LIB-2, so a DOCX made from one would have no universe or book to keep. The human maps such a folder into a book folder or a playground first, under REQ-LIB-1. A file in an unmarked folder inside a book folder or a playground is canon or playground, and the import takes it one file at a time.
- A6's named chapter-links view. D8 takes B8's "no graph shows them yet", and J-b puts the view to Jason. Jason's O2 (Q239) takes the view in d9.
## Marked for Jason (additions in the text he sees)
- J-a. Whether "We will not run the systems in parallel" applies per chapter or as one switch per book. His call. As written, it applies per chapter.
- J-b. A converted chapter's DOCX is not in Obsidian's graph. Obsidian shows the chapter only through its archived Markdown, and no DOCX edit reaches that file's links. REQ-LIB-5 still cites two TARGET lines, "Visualization of data via Obsidian or equivalent is required" and "Connections are always visible". Mos's reading is that 1.17 as written meets neither line for converted chapters. Their current links show to the user only as clickable text inside the editor, and no graph or list shows them. Q226 leaves room for "another way to handle the visual brain map". The O2 design that landed for Vikunja 571 at 767bb62c7 holds a Console Connections view and its tests as later work that waits for this answer. His call whether 1.17 requires that view. As written, it does not. Mos recommends that it does, because impact map A6 says "Recommended: name the view" and TARGET says "Connections are always visible". Jason answered O2 (Q239): 1.17 requires the view. d9 writes it into REQ-LIB-5, its note and the Risks line. The view comes with the conversion work after 10-27, the 10-27 Case 2 release stays on Markdown (Q235 P6, Q237), and the import does not wait for the view (mos-1443 R3).
- J-c (mos-1374): "The store pushes to a remote (D7), and the Case 2 VM is in the nightly PBS backup. For a fixed restore point before her first real import, a manual backup of VM 1012 with PBS protect runs first. That step is reversible and needs no reboot." Mos's reading is that this sits inside the P5 go step, so it needs no new question.
- J-d. How agents read a converted chapter, D9. His call. As written, an agent reads it through the ordinary Case 2 lookups in any thread or room, under the same project and universe access as Markdown canon. This is Mos's reading of F41 and REQ-LIB-7. The other choice is the model in the earlier O2 design, W4 sections 7.1 and 7.2. Under it, an agent reads a converted chapter only in a new writing conversation that holds one human and one agent, only after the business owner grants that agent access to that document, and by default only what the human attaches to each message. Comments and tracked deletions stay hidden from agents until a human turns on a setting for each. Markdown has neither, so the default keeps agents at the access Markdown gives them. Those two sentences are Mos's ruling mos-1379. A yes to the text as written settles it.
- J-e. Versioning means the editor's tracked changes plus one git commit per save.
- J-f. A converted chapter can be edited only in the Console while the stack is reachable. Obsidian no longer edits it offline.
- J-g. The import takes Markdown only. Importing .doc files stays a separate task.
- J-h. Autosave under REQ-LIB-9. Jason's Q226 F41 says "All changes are instantly committed and available to the agents." Mos's reading, recorded with that ruling, is "Each save is a commit at once, and agents read it at their next lookup." At the O2 design's D13 defaults, a save commits at most 2 seconds after a pause in typing or 15 seconds into steady typing, with no human action needed. Mos's reading in mos-1359 counts that delay as "instantly committed". Only a human changes the intervals. The PRD names no values, and the defaults stay in the design. Whether a delay of seconds fits his word "instantly" is his call, so this is marked for him.
- J-i. In 1.17 a playground story that is DOCX can't become canon. That covers a playground Markdown file the human imports, a story the human starts in a playground in the editor, and the DOCX of a draft universe after it is made real. Today Melanie promotes a playground file by moving it into a book folder in Obsidian, and a DOCX in the writing store can't be moved that way. She can start a new story in the book and paste the text in, but it gets a new document id and the playground copy keeps the history. A later version adds DOCX promotion with C2-19, which comes after the slice.
- J-j. Web links, text boxes and fields in a converted chapter. Jason's Q226 F41 says "All changes are instantly committed and available to the agents." The reader in this version can't read a web link, a text box, a field or hidden text. As written, the import turns each web link into plain text that keeps its label and address, and the human confirms that in the fidelity report. A web link that can't be kept safely as plain text refuses the import. If a later edit adds one of these, the save keeps it and the editor warns the human. Agents then get none of that part's text until a save takes it out.
- J-k. The 1.12 note Jason approved says bus writes, C2-02 and C2-03b, don't gate 10-27. His Q226 "F42: ok" moved them into the 10-27 slice, and design 9.2 counts them in the smallest slice that lets Melanie start. Mos reads that as making them gate 10-27. The editor rows C2-11a and C2-11b still don't gate it, per his Q195 words "we need to get it moving as an add-on".
- J-l. REQ-LIB-9 does not use REQ-PROJ-3's "permissive license" bar. It takes the licenses that the editor's independent security review accepted, because that review cleared fonts under the SIL Open Font License and the Ubuntu Font License, which not every reader counts as permissive. Mos's reading.
Marked as changes beyond P1 to P6, from the impact map (Q17, item 5):
- A1 (archived scope and canon cites)
- A2 (the conversion requirement, REQ-LIB-8)
- A3 (outside the vocabulary, hard-wait list unchanged)
- A6 (lookups across formats)
- A7 (agent bounds)
- A8 (DOCX cites)
- Item 2 and mos-1375: each writing-store commit is pushed to a remote off the stack's host. Only a human sets it, it starts unset, and a repository on the stack's host doesn't count. Only the stack's host pushes to it, and no agent can reach it with any credential. Import and new story files stay closed until the remote is set and checked, and each import's archive push waits until the remote holds the DOCX commit. This keeps "Git is used for all changes -- local and remote" true for DOCX chapters.
- Item 3 (the Hermes gate)
- Item 4. Canon and playground story files convert one file at a time, including files in unmarked folders inside a book folder or a playground. Type-folder and supporting files stay Markdown. A story file outside every book folder and playground has no universe or book, so it converts only after a human maps its folder into a book folder or a playground. The mapping step is Mos's reading of P1 and Q30.
The F4 measurement goes with them.
## Files the row would own
The id count goes from 85 to 87. 1.16 owned three files because its count stayed at 85. Like 1.13, the last version that added ids, the row owns four files:
- `docs/prd/mosaic-stack.md`
- `packages/tasks/requirements.json`: the version 1.17, the two new ids REQ-LIB-8 and REQ-LIB-9 with their titles, and the changed titles of REQ-LIB-1, REQ-LIB-2 and REQ-LIB-4. The new ids go after REQ-LIB-7 and before REQ-INST-1, in the same order as the PRD's bullets.
- `packages/tasks/tests/requirements.test.mjs`: the version pin 1.17, the id count of 87, and the duplicate-id message, which goes from `requirements[85].id: REQ-ROLE-1 twice` to `requirements[87].id: REQ-ROLE-1 twice`.
- `packages/bus/tests/requirements.test.mjs`: the list length, which goes from 85 to 87.
The gate would match 1.16's:
1. A reviewer approves the text.
2. Jason says yes to the exact text through Mos.
3. Both `requirements.test.mjs` files, in `packages/tasks/tests` and `packages/bus/tests`, and every `scripts/test-*.sh` that reads the PRD or `requirements.json` are green on Sage's gate.
4. Mos gets the landing commit.
agents/sage/work/prd-1-17/DRAFT.md
+647
View File
@@ -0,0 +1,647 @@
# PRD 1.17 draft: Case 2 story files are DOCX (Q235 to Q237, P1 to P6)
Sage, 2026-10-23, for mos-1366 item 1 and Vikunja 570. Draft 9. It is d8 plus Jason's Q41 answer O2 (DECISIONS Q239, mos-1467), which makes J-b yes, and Webby's round 5 N15 to N17 (webby-0210) (see "d9 changes"). d8 is d7 plus Mos's d8 fix list mos-1443 (see "d8 changes"). d7 is d6 plus Mos's ruling mos-1379 on Fenton's 571 B2 (see "d7 changes"). d6 is d5 with Webby's round 3 (webby-0207) fixed: B1 to B3 and N10 to N13, with N14 left for Mos (see "d6 changes"). d5 folds in:
- Mos's d4 check ruling mos-1372 (D1 to D14; D15 was dropped).
- mos-1374, which replaces J-c.
- The impact map mos-1368 (jason-master-restart d183246, `projects/mosaic-mvp/case2-docx-impact-map.md`: A1 to A16, critic items C1 to C6, items 2 to 7).
- Mos's F4 measurement.
Review order (mos-1367 B5): Webby, then Mos, then Jason. Base: PRD 1.16, `docs/prd/mosaic-stack.md` blob a6db9b4a at 482e865ac.
1.16 lands first (row 291), and this text is a new version on top of it. Nothing here is built or queued. The impact map's queue changes (A24, A57 to A59) go through `scripts/mosaic queue` after 1.17 is approved (C9).
Sources, verbatim in Mos's DECISIONS:
- Q235, Jason's Q36 answer.
- Q236: chapters are DOCX, Markdown for agent files and docs.
- Q237: "It is correct for now (subject to future change)".
- The P1 to P6 reading as restated to Jason in Q38.
## Settled points (mos-1367)
These stand as ruled. d5 changes only what mos-1372 changed.
- **O1. Where a converted chapter lives.** The DOCX lives in the writing store of
O2 design D12, and the archived Markdown stays in the user's repository under a
human-marked archive folder. Ruled yes in B1, on the condition that the text
says plainly that a converted chapter leaves the Gitea-mirrored repository and
lives in the stack's writing store. mos-1372 D7 and mos-1375 add a remote for
the store, off the stack's host.
- **O2. The unit of conversion.** One story file per import, refusing a file
that is already converted. Ruled yes in B2: each file gets its own fidelity
report, human confirmation, manifest and commit.
- **O3. Whether conversion is a vocabulary action.** A human-only verb outside
the agent vocabulary, with no role grant and no agent request path. Ruled yes
in B3.
- **O4. Reading archived Markdown.** A new `archived` scope. Lookups leave it out
unless the caller asks, every answer marks it archived, and a canon citation
can't name it. Ruled yes in B4.
## d3 choices after mos-1372
- **C1 is replaced by D1, keep-source-scope.** A DOCX keeps its source's scope:
universe, book, and canon or playground. A playground DOCX follows the
playground rules and is never returned as canon. The import accepts canon and
playground story files. Type-folder files and supporting files stay Markdown
(P4). This also settles the impact map's Q18, item 4. It leaves one narrowing
for Jason, J-i. A playground DOCX can't become canon in 1.17.
- **C2 stands.** The move keeps the file's path under the archive folder:
`book1/ch3.md` goes to `<archive>/book1/ch3.md`. An archived file's universe
and book are those of its old path.
- **C3 is replaced by D3 and D14.** The archive commit is written by a new
human-only bus step (Vikunja 571) on the C2-02 write plumbing and pushed through
C2-03b. The order is the store commit and the remote's confirmation that it
holds that commit, then the archive commit and its push, then publication to the
lookups.
- **N4 stands.** REQ-LIB-8 says "a real user's books". The PRD names no user
anywhere in Case 2.
## Text changes
### Status and sources
In the Status bullet's first line, "- Status: approved, version 1.16." becomes
"- Status: approved, version 1.17." Status gains, after the two 1.16 sentences at
the end of the bullet: "Version 1.17 records Jason's rulings Q235 to Q237 of
2026-10-23: Case 2 story files are DOCX, Markdown stays for agent files and
documentation, and a human-started import converts a Markdown story file one way.
It also adds REQ-LIB-9, the Console's DOCX editor, from Jason's rulings Q195, Q226
and Q234. It changes what Case 2 requirements allow, so Mos puts the text to Jason
as written, and it lands only after his yes (mos-1366, Vikunja 570)."
New source line, above the 1.16 one: "Version 1.17 source: Jason's Q235, answering
Q36: 'How about we see a markdown file, we convert the markdown file to docx, then
archive or mark the markdown file as converted. The new standard for files in the
creating writing use case is to use docx to handle versioning and WYSIWYG. We
eliminate the potential for confusion based on the files. Agents must understand
which files are what format and where they live. The system must allow for import
and conversion. We will not run the systems in parallel. There will be an
irreversible conversion of the files.' His Q236 says: 'For creative writing
chapters, we need to utilize docx as the standard. Markdown is acceptable for
agent files, instructions, PRDs, documentation, etc. The creative writing files
should be docx for familiarity for the user.' His Q237 says 'Q38: It is correct
for now (subject to future change)', which confirms Mos's reading P1 to P6.
REQ-LIB-9 rests on his Q195 request for 'a full WYSIWYG editor within Mosaic
Stack', his Q226 answer 'F41: We want to move editing into the WYSIWYG in the
WebUI. All changes are instantly committed and available to the agents.' and his
Q234 answer 'Q37: yes' to the exact security header for the editor's frame. The
storage follows the O2 design D10 to D12 as rewritten under Vikunja 571, at
b99ca86b9 on `refactor`."
### Creative library, section lead
Replace "The library is the user's own writing repository." with "The library is
the user's own writing repository plus the stack's writing store, which holds the
DOCX story files (REQ-LIB-8, version 1.17)."
### REQ-LIB-1
Add, before "(Design 1.1": "The mapping also names one archive folder, set by the
human, where converted Markdown story files go. A book's DOCX story files are in
the stack's writing store, under the same universe and book (REQ-LIB-8)." Version
tag, inside the closing parenthesis: "Version 1.15: supporting folders.)" becomes
"Version 1.15: supporting folders. Version 1.17: the archive folder and the
writing store.)"
### REQ-LIB-2
Replace "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." with:
"A Markdown file's scope comes from its path and from past imports, prefixes
first: a Markdown file under the archive folder is archived, one under a
supporting prefix is supporting, a Markdown file at a converted file's old path is
unmapped under REQ-LIB-8 but flagged in the format map, 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. The archive folder follows the same placement rules and may not
overlap another prefix or a book folder. An archived file keeps the path it had
under the archive folder, and its universe and book are those of that old path. A
DOCX document in the writing store keeps its source's scope: the universe, the
book if there is one, and canon or playground. Its source is the Markdown file it
was converted from or, for one the human starts in the editor, the universe and
book or the playground the human picks (REQ-LIB-8). A playground DOCX follows the
playground rules and is never returned as canon. It stays playground after its
draft universe is made real. In version 1.17 no promotion or mapping change makes
a playground DOCX canon. A later version of this PRD says how one becomes canon."
Replace "Lookups return canon unless the caller asks for playground or
supporting." with "Lookups return canon unless the caller asks for playground,
supporting or archived. Every answer marks an archived file as archived and names
the DOCX that replaced it."
Replace "so an agent can't cite a playground or supporting file as canon" with "so
an agent can't cite a playground, supporting or archived file as canon".
In REQ-LIB-2 only, replace "The Console shows each cite's scope." with "The Console shows each cite's
scope and format, and whether a cited Markdown file was converted."
Version tag, inside the closing parenthesis: "Version 1.15: supporting.)" becomes
"Version 1.15: supporting. Version 1.17: archived scope and DOCX scope.)"
### REQ-LIB-4
Replace "The user commits and pushes with their own tools, today Obsidian with
obsidian-git." with "The user commits and pushes Markdown with their own tools,
today Obsidian with obsidian-git. A converted story file's current text is no
longer in that repository, which keeps only its archived Markdown (REQ-LIB-8)."
Add, after "Bus writes and pushes come in later rows (C2-02, C2-03b).": "A DOCX
story file is saved in the Console's editor, and each accepted save is one commit
by the human in the stack's writing store (REQ-LIB-9). Each writing-store commit
is also pushed to a remote off the stack's host, never by force-push. The remote
is a setting only a human changes, and it starts unset. A repository on the
stack's host never counts as that remote. A missing remote or a failed push never
undoes a save, and the user sees each push that is pending or failed. Only the
stack's host pushes to that remote, and no agent can reach it with any credential.
Agents read the local commit."
Replace "Agents read only the mirror's served commit and never hold a copy of
their own, so they see the user's push within about a minute." with "Agents read
the user's repository only at the mirror's served commit, except a story file
during its import under REQ-LIB-8. They read a DOCX story file only at a committed
version in the writing store, under REQ-LIB-5. They never hold a copy of their
own, so they see the user's Markdown push within about a minute and a DOCX save at
their next lookup after the editor reports it as committed."
Version tag: "and the sync items.)" becomes "and the sync items. Version 1.17,
with Q222 for the remote setting.)"
### REQ-LIB-5
Add, after "Each answer names the commit it read.": "Each answer also names the
file's format and where it lives: its path, or its document id in the writing
store. A DOCX story file is read from its latest committed save, never from
unsaved text. A lookup that starts after the editor reports a save as committed
returns that save or a later one, even while its push to the remote is pending or
has failed, and the answer names the version. Get, search and manuscript read a
DOCX story file as its extracted text with DOCX locators, never as lines. That
text is the file with its tracked changes accepted. An agent reads a story file's
comments, or its text with tracked deletions shown, only after a human turns on
the matching setting. Both settings are off by default, and only a human changes
them. The reader in this version can't read some things a DOCX story file can
hold, such as a web link, a text box, a field or hidden text. The editor warns the
human when an edit adds one, and the human can still save it. Until a later save
takes it out, lookups give agents none of the text of the part that holds it,
whether that is the chapter's body, a note or a comment. The manuscript lookup
follows the book's chapter order across both formats (O2 design D10), and the next
chapter it names is never an archived file. Links out and in resolve across both
formats. The universe lookup returns the format map (REQ-LIB-8)."
Replace "The user sees them in Obsidian's graph and backlinks." with "The user sees
a Markdown file's links in Obsidian's graph and backlinks. A DOCX story file's
wikilinks stay clickable in the Console's editor (O2 design D11). The Console
shows a converted chapter's links out and in, in a Connections view."
Version tag: 'and "Connections are always visible".)' becomes 'and "Connections
are always visible". Version 1.17, with Q222 for the two settings.)'
### REQ-LIB-6
Replace "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." with
"A reply may cite lines of a Markdown file at a commit, a place in a committed
DOCX story file, or pages the agent fetched, and the broker checks every citation
before it stores the message. A DOCX citation never calls a paragraph a line. It
names the document id, the committed version and a DOCX locator. A citation that
names an archived file as current is refused. The `requireCitation` setting below
applies to Markdown and DOCX citations alike, and so does the rule for a citation
marked as canon."
Add, after "the broker refuses such a write before any git call.": "The writing
store and the archive folder are read-only to a creative agent as well, and the
broker's path check treats the archive folder as story. No agent creates, edits,
deletes, converts, archives or restores a story file in any format, and no agent
writes a DOCX. No creative agent starts or undoes a conversion, and none asks for
one through a tool or a decision it raises, as REQ-LIB-8 says. An agent may still
suggest a conversion to the human in chat. Each creative role's contract states
which files are DOCX and which are Markdown, and cites a DOCX story file by its
locator, never by line."
Version tag, inside the closing parenthesis: "Version 1.15.)" becomes "Version
1.15. Version 1.17.)"
### New REQ-LIB-8
This bullet goes after REQ-LIB-7 and before the "### Installer" heading.
"- **REQ-LIB-8.** Story files become DOCX. DOCX is the standard for chapters and
the other story text in a Case 2 writing project, canon and playground alike. A
story file becomes DOCX through a human's import (below), or when the human
starts it in the editor. From then on DOCX is its only working format, edited in
the Console's editor (REQ-LIB-9). A Markdown story file stays Markdown until its
import. Files in a type folder (REQ-LIB-1), such as character and place notes,
stay Markdown. So do supporting files, agent files, instructions, PRDs and
documentation, including the character sheets, summaries and cross-links agents
keep under REQ-LIB-6.
- A converted story file's current text leaves the user's Gitea-mirrored
repository. Its DOCX lives in the stack's writing store, on the stack's host,
and not in the repository the user pushes or opens in Obsidian. Only its
archived Markdown stays there.
- An import converts one Markdown story file, canon or playground, outside every
type folder (REQ-LIB-1), to a DOCX document in the writing store. It refuses
an unmapped, supporting, archived or type-folder file, and a file that is
already converted. Each import has its own fidelity report, the human's
confirmation of that report, a manifest naming the source file and its commit,
and one commit in the store. The DOCX keeps every wiki link of the source as
written, and a lost link to another library file fails the fidelity report. A
web link becomes plain text that keeps its label and address, and the fidelity
report lists it for the human to confirm. A web link that can't be kept safely
as plain text refuses the import.
- The human can also start a new story file in the editor, in a universe and
book or a playground the human picks. It is a DOCX document in the writing
store from its first commit, with no Markdown copy, and it opens under the
same gate as the import.
- The same import marks the Markdown file converted, naming the document, and
moves it to the archive folder under its old path (REQ-LIB-1, REQ-LIB-2).
The mark and the move are one commit authored by the human in the user's
repository. A new human-only bus step (Vikunja 571) on the C2-02 write
plumbing writes it, and C2-03b pushes it. The move keeps the bytes and the
git history, so it isn't `data.delete`.
- The store commit comes first, and the writing store's remote must confirm it
holds that commit. Then come the archive commit and its push, then publication
to the lookups. Until publication the Markdown at its old path keeps its canon
or playground scope. Agents read that file at the commit the import started
from, even after the mirror's served commit reaches the archive commit or a
later one. No lookup returns the file's archived copy before publication, even
one that asks for archived files. A refusal or failure before the archive push
leaves the Markdown unmoved and no DOCX that a lookup returns. A failure after
the archive push leaves a pending import that the human sees and can resume,
never a claim that nothing moved. An archive push whose result is unknown
counts as a failure after the archive push until the stack reads the result
back from the user's remote.
- Each stage of an import writes a logged event. The import's record on the
stack's host names the source file's path, commit and blob and the new
document id, and each event points to that record.
- After a conversion, a Markdown file at the converted file's old path is
neither canon nor playground. Lookups leave it out, the format map flags it,
and the human is told.
- A new Markdown story file in a book folder that holds converted files stays
canon until its import, unless it sits at a converted file's old path or under
a playground prefix. The Console flags it and offers the import. Nothing
converts it on its own.
- A hybrid's exclusion that covers a converted file's old path also covers its
DOCX document (REQ-LIB-3). An exclusion of a whole book folder also covers
every DOCX document in that book, including one started in the editor. An
exclusion can also name a DOCX document by its id.
- Only a human starts an import or a new story file, from the CLI or a Console
session signed in as that human. Both are human verbs outside the agent action
vocabulary. Neither is added to `ACTIONS` in the business vocabulary or to the
broker's always-gated list, including the import's action, `library.convert`.
No role holds them, no agent can request them, and the hard-wait list in
REQ-WAIT-1 doesn't change. In an organization with several humans, who may
start them is a setting only a human changes, and the default is the owner
only.
- Conversion is one way, with no parallel run. Neither the Console nor any agent
edits a converted story file as Markdown, and no DOCX edit syncs back to
Markdown. The Console's Markdown save refuses every file under the archive
folder. The user's own tools can still change the archived Markdown, and no
such change reaches the DOCX. The old Markdown stays in git history, and
nothing rewrites history. A promotion into a book folder (C2-19) runs the
import for a Markdown story file or is refused. A promotion of a playground
DOCX is refused in version 1.17.
- Agents get a format map: for each mapped folder and story file, its format,
scope and where it lives, archived files, flagged files and pending imports
included.
- The import and new story files ship closed. They open only after four things.
The editor ships. The human has set the writing store's remote, and the stack
has checked that it can push there. Agents can read committed DOCX story files
through the lookups and cite them (REQ-LIB-5, REQ-LIB-6). Any earlier agent
system that writes the user's files has stopped, which for Case 2 is the
Hermes retirement (#423 step 5). So the import itself never cuts agents off
from a chapter, the chapter's current text never lives only on the stack's
host, and no second system writes the story. The first import of a real user's
books waits for Jason's go.
(Q235, Q236, Q237: P1 to P6. Q222 for the setting. O2 design D10 to D12.
Version 1.17.)"
### New REQ-LIB-9
This bullet goes after REQ-LIB-8.
"- **REQ-LIB-9.** The Console's DOCX editor. The human edits a DOCX story file in
the Console's editor, in a split pane with the agent chat alongside it. The
human can pin an agent chat to a document. The human can select a word,
right-click it, and choose a synonym from a thesaurus. Only a human saves. Saves
happen on their own while the human types (Q226), at intervals only a human
changes, and each accepted save is one commit with the human as author, pushed
as REQ-LIB-4 says. A save made against an older version than the current one is
refused. Agents never write a DOCX. Versioning is the editor's tracked changes
plus one git commit per save. The editor's code is vendored and pinned, with a
hash per file and the licenses that its independent security review accepted. At
runtime the editor loads only files that the stack itself serves, and it
requests nothing from any other host. The editor's frame sends exactly the
content security policy Jason approved in Q234, and the WebUI shell's own header
is unchanged. REQ-PROJ-3's project docs editor is unchanged. (Q195, Q226, Q234,
Q236. O2 design D3, D4, D6, D8, D10, D13, D14, D16 and D22. Version 1.17.)"
### Version 1.17 notes
Added after the 1.16 notes:
"- Version 1.17:
- Jason confirmed the reading 'for now (subject to future change)' (Q237). The
rulings stand until he revises them.
- The 10-27 Case 2 release ships on Markdown as built (P6). The 1.11 line 'The
Case 2 MVP for 10-27 is the Markdown library (#416). The WYSIWYG editor (Q195,
Q196) is an add-on that doesn't gate it.' still holds. Conversion opens after
10-27, and only once REQ-LIB-8's four conditions are met. The editor ships,
the writing store's remote is set and the stack has checked that it can push
there, agents can read and cite committed DOCX story files through the
lookups, and Hermes is retired, which is #423 step 5.
- The 1.12 note says five bus write and Console editor rows, C2-02, C2-03b,
C2-11a, C2-11b and C2-19, don't gate 10-27. Jason's Q226 F42 later moved
C2-02, C2-03b and C2-11b into the 10-27 slice. The Case 2 design brings C2-11a
in with them, because C2-11b needs it. C2-19 stays outside the slice. Mos's
reading of F42 is that C2-02 and C2-03b now gate 10-27, because design 9.2
puts them in 'the smallest slice that lets her start'. C2-11a and C2-11b are
slice rows that still don't gate 10-27, because the editor is the Q195 add-on.
The DOCX change in 1.17 leaves this slice as it is, and C2-11b's Markdown
editor never edits a converted story file.
- Q236 narrows Q176's editor choice to DOCX for story files (REQ-LIB-9). The
1.12 note that the Case 2 design keeps Obsidian now holds only for Markdown
files, including story files not yet imported. A DOCX story file is edited
only in the Console's editor under REQ-LIB-9.
- This replaces two parts of the O2 design at 25c09f19f. The superseded-notice
proposal from Fenton's F1 in D12 is withdrawn, and the
keep-Markdown-at-its-path model of D11 is replaced. Gyro's rewrite of the O2
design for Vikunja 571, landed on `refactor` at b99ca86b9, carries the
details, and where it differs from this text, this text holds:
- the import and archive steps, the mark, and the new bus step;
- links from supporting files to a moved chapter;
- the DOCX reader;
- the user's unpushed or later changes to an archived file or at its old path,
and pushing and closing the file in Obsidian before each import;
- the writing store's remote in W4 section 7.3, which replaces the no-remote
and no-backup rule that W4 section 7.4 held before the rewrite, at
062646487;
- import events counted by a bus restore, and recovery when a bus restore or a
restore of the whole host predates an import;
- manifest order for the manuscript lookup and its next chapter;
- `library.convert` kept out of `ACTIONS`, out of the hard-wait note and out
of the pinned `GATED_ONLY` list in packages/business/src/vocabulary.mjs.
- Agents read a converted story file through the Case 2 lookups under the same
project and universe access as Markdown canon, in any thread or room. W4's
earlier O2-only conversations, per-document grants and per-send sharing don't
gate these lookups. The 571 rewrite replaced them in W4 sections 7.1 and 7.2.
The creative tool list in REQ-LIB-6 doesn't change.
- The six creative role contracts row 213 landed say 'Every item cites the
lines of the user's material it is about'. A build row under 571 changes that
line for DOCX story files (REQ-LIB-6).
- A new Markdown file in a book folder is still canon in 1.17. The 1.17
exception is a file at a converted file's old path, which REQ-LIB-2 makes
unmapped.
- Story files convert whether canon or playground. Type-folder and supporting
files stay Markdown.
- Measured 2026-10-23 at about 01:21Z: the Case 2 user's library repository
tracks 213 files, 203 of them Markdown, and none is a .docx or .doc. It has no
untracked files. The user's .doc files (Q196) are outside it. So the landed
code has no DOCX there to report as unreadable at 10-27.
- Text replaced in 1.17, kept here as in earlier notes:
- Creative library lead, the 1.16 sentence: "The library is the user's own
writing repository."
- REQ-LIB-2, the 1.16 sentences: "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." "so an agent
can't cite a playground or supporting file as canon" "The Console shows
each cite's scope."
- REQ-LIB-4, the 1.16 sentences: "The user commits and pushes with their own
tools, today Obsidian with obsidian-git." "Agents read only the mirror's
served commit and never hold a copy of their own, so they see the user's
push within about a minute."
- REQ-LIB-5, the 1.16 sentence: "The user sees them in Obsidian's graph and
backlinks." A converted chapter's connections show in Obsidian only as they
stood at conversion. The Console's Connections view shows their current
links.
- REQ-LIB-6, the 1.16 sentence: "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."
- REQ-LIB-1 only gains sentences.
- REQ-LIB-3's text and REQ-LIB-7 are unchanged. REQ-LIB-8 adds one form of
exclusion REQ-LIB-3 doesn't have: naming a DOCX document by its id. A path
exclusion also covers DOCX documents, through a converted file's old path or a
whole book folder. An archived file and a DOCX document keep a universe, and a
book where their source has one, so every lookup still names one universe.
REQ-PROJ-3, the Console editor for a project's spec and docs, is unchanged.
C2-11b opens the library's Markdown files in that same editor.
- In `packages/tasks/requirements.json` the titles of REQ-LIB-1, REQ-LIB-2 and
REQ-LIB-4 change, and those of REQ-LIB-5 and REQ-LIB-6 stay. REQ-LIB-1 becomes
'A human-set library maps the user's repository onto universes, books, types,
playgrounds, supporting and archive folders'. REQ-LIB-2 becomes 'Scope comes
from the path or a DOCX's source, lookups default to canon, and only canon
files are ever cited as canon'. REQ-LIB-4 becomes 'Git holds every change. The
bus fast-forwards a read-only mirror every 60 seconds, the one place agents
read Markdown'. REQ-LIB-8 and REQ-LIB-9 add two ids, so the count goes from 85
to 87. REQ-LIB-8 is titled 'Case 2 story files become DOCX by a human-only
one-way import or in the editor; Markdown stays for notes and docs', and
REQ-LIB-9 'The Console's DOCX editor: only a human saves, each save is one
commit, and the editor code is vendored and pinned'.
- Open points O1 to O4 of draft 1 were ruled by Mos in mos-1367 B1 to B4.
- Sage files the build rows under Vikunja 570 and 571 after the rewrite is
approved. This amendment adds the requirements only."
### Risks
The new lines go at the end of "## Risks and open questions", after the bullet
that begins "Trusted mode lets an agent" and before the "## Milestones" heading.
- "A DOCX file is a zip archive, so git can't show a line diff of a chapter.
Review of a story change goes through the editor and the committed reader,
not `git diff`. (Version 1.17.)"
- "A converted chapter's DOCX is not in Obsidian's graph. Obsidian shows the
chapter only through its archived Markdown, and no DOCX edit reaches that file's
links. The DOCX's current links show in the Console's editor and its
Connections view, not in Obsidian. (Version 1.17.)"
- "Conversion can't be undone in place. Front matter, wiki link forms and
unsupported blocks may not survive it, and the mirror can't refuse the user's
push to an archived file. The controls are the fidelity report, the human's
confirmation, an untouched original on refusal, and the kept archive.
(Version 1.17.)"
- "A restore of the stack's bus alone from a backup taken before an import drops
the import's logged events, while the archive commit and the DOCX stay. A
restore of the stack's whole host from such a backup also takes the writing
store and the host's import records back to before the import. The archive
commit stays in the user's Gitea repository and the DOCX stays on the writing
store's remote, but the host keeps no record of the import. A bus restore counts
import events, and the import's recovery covers both cases (Vikunja 571).
(Version 1.17.)"
## d9 changes (Q239 and Webby round 5)
- J-b yes (Q239, mos-1467): REQ-LIB-5's replacement ends "The Console shows a converted chapter's links out and in, in a Connections view." in place of "and no graph shows them yet". The REQ-LIB-5 note and the graph Risks line name the view as required, not later. J-b and the "Not taken" A6 line record the answer. Nothing else in the PRD text changes.
- N15: the D7 landing line gives R8's wording beside the impact map's quote.
- N16: the d7 changes line notes that R8 replaces "no agent credential reaches it" in d8.
- N17: the REQ-LIB-2 Replace quote and the REQ-LIB-8 old-path bullet are rewrapped under 82 columns. Their words are unchanged.
## d8 changes (Mos's d8 fix list, check wf_63bba879-180)
- R1: REQ-LIB-4's tail covers DOCX saves, which agents see at their next lookup after the editor reports them as committed. The notes quote the whole 1.16 sentence. Source: nit/jason/F10.
- R2: REQ-LIB-4's new title says the mirror is "the one place agents read Markdown". Source: decisions.n14.
- R3: J-b asks whether 1.17 requires the Console Connections view, with Mos's recommendation of yes. Sources: mos1372/F9, jason/F2, anchors/F5.
- R4: C2-02 and C2-03b gate 10-27, C2-11a and C2-11b are slice rows that don't, and "F42 wins" is gone. New J-k. Sources: anchors/F6, jason/F5.
- R5: where the landed 571 design differs, this text holds. Sources: anchors/F8, adversarial/F8 item 1, jason/F8, critic/C6, G16's design follow-on.
- R6: `library.convert` stays out of `ACTIONS`, and REQ-WAIT-1's hard-wait list doesn't change. Sources: gyro571/F1, adversarial/F8 item 3, critic/C6.
- R7: a repository on the stack's host never counts as the writing store's remote, and Item 2 says so. Sources: mos1372/F2, adversarial/F1, gyro571/F2.
- R8: "no agent credential reaches it" becomes "no agent can reach it with any credential". Source: Fenton's B1 under mos-1379.
- R9: no playground DOCX becomes canon in 1.17, and a promotion of one is refused. New J-i. Sources: mos1372/F8, adversarial/F2.
- R10: REQ-LIB-9 restates Q195's pin and right-click thesaurus, and its cite gains D4 and D22. Source: critic/C4.
- R11: REQ-LIB-9's license bar is the licenses its independent security review accepted. New J-l. Source: critic/C3.
- R12: no text for D16's narrow-window tabs. Mos records that reading in STATE. Sources: jason/F1, second verifier vote.
- R13: no lookup returns a file's archived copy before publication. Source: adversarial/F5 part 3.
- R14: a restore of the whole host from a backup taken before an import is a fourth recovery case. Source: adversarial/F6.
- M1: REQ-LIB-4's writing-store sentences follow the later bus rows sentence and add the off-host remote rules and DOCX read timing. The note quotes both 1.16 sentences. Sources: mos1372/F2, adversarial/F1, gyro571/F2, anchors/F4, nit/jason/F10, adversarial/F5 part 1, Fenton B1.
- M2: REQ-LIB-8's order bullet adds the remote's confirmation, the old-path read rule and "archive push". Sources: mos1372/F2 and the other remote findings, mos1372/F7, adversarial/F5 parts 2 to 4.
- M3: REQ-LIB-8's gate bullet has four conditions, adding the remote. Sources: the remote findings, critic/C1 and C2 edit 2.
- M4: the 1.17 note on when conversion opens restates the four conditions and drops W4b. Sources: jason/F5, the remote findings.
- M5: Item 2 rewritten with the remote rules. Sources: the remote findings.
- M6: the 1.12 gating note rewritten. Sources: anchors/F6, jason/F5.
- M7: REQ-LIB-9 gains the split pane, the pin, the thesaurus, the license bar and the runtime load rule, and cites more of the design. Sources: jason/F1, critic/C4, critic/C3, nit/anchors/F12, nit/gyro571/F9.
- M8: REQ-LIB-2, the one-way bullet and the C1 note keep a playground DOCX out of canon in 1.17. Sources: mos1372/F8, adversarial/F2.
- M9: REQ-LIB-5 says what the reader can't read, and the import turns web links into plain text. New J-j. Sources: critic/C1, critic/C2.
- M10: an exclusion of a whole book folder covers that book's DOCX documents. Source: adversarial/F3, with B5.
- M11: the human-verbs sentence and the 571 list item name `library.convert` and REQ-WAIT-1. Sources: gyro571/F1, adversarial/F8 item 3, critic/C6.
- M12: J-b rewritten. Sources: mos1372/F9, jason/F2, anchors/F5, gyro571/F3, critic/C6.
- M13: J-d puts the agent read model to Jason as his call. Source: mos1372/F1.
- M14: Status moves to version 1.17 and names REQ-LIB-9. Sources: anchors/F2, mos1372/F4, critic/C7.
- M15: the 1.17 source line quotes Q235 in full (mos-1446) and the REQ-LIB-9 sources, at b99ca86b9. Sources: critic/C5, anchors/F9, jason/F8 pin part, nit/gyro571/F8, critic/C6 pin part.
- M16: the 571 list lead names the two replaced design parts and the landed design. Sources: anchors/F9, anchors/F8, adversarial/F8 item 1, jason/F8, critic/C6.
- Landing swap: Gyro's docs round for R5, R6 and R14 landed as b99ca86b9 (Fenton fenton-0015), so M15 and M16 cite b99ca86b9 in place of 767bb62c7, as the d8 fix list's header says. J-b keeps 767bb62c7 for its line numbers.
- M17: W4 section numbers in the remote item and the lookups note. Sources: gyro571/F5, nit/adversarial/F11.
- M18: the D7 landing line. Sources: gyro571/F5, the remote findings.
- M19: a logged event for each import stage, in REQ-LIB-8 and A2. Source: gyro571/F7.
- M20: the Risks line on restores adds the whole-host case. Sources: adversarial/F6, gyro571/F7.
- M21: the 571 restore item adds the whole-host case. Source: adversarial/F6.
- M22: the graph Risks line and the REQ-LIB-5 note name a Console view. Sources: anchors/F5, jason/F2.
- M23: the d6 B3 line drops "F42 wins". Source: anchors/F6.
- M24: new Markdown in a converted book, with the old-path and playground exceptions. Source: mos1372/F6.
- M25: J-c's last sentence is Mos's reading. Source: mos1372/F10.
- M26: J-h rewritten with the D13 defaults. Source: jason/F3.
- M27: Item 4 rewritten. Sources: jason/F4, gyro571/F4, decisions.unmarked_folders.
- M28: the "Not taken" note on unmarked folders. Sources: jason/F4, gyro571/F4, decisions.unmarked_folders.
- M29: the import refuses an unmapped file. Sources: gyro571/F4, decisions.unmarked_folders.
- M30: placement notes for REQ-LIB-8, REQ-LIB-9 and the Risks lines. Sources: anchors/F3, nit/anchors/F14.
- M31: REQ-LIB-4's title and the D11 landing line. Source: decisions.n14.
- M32: the Q236 note limits the 1.12 Obsidian note to Markdown files. Source: critic/C8.
- M33: the exclusion note adds path exclusions of DOCX documents. Source: anchors/F7.
- M34: A9 moves from "Mine" to the impact-map list. Source: decisions.exclusion_by_id.
- M35: the D5 landing line. Sources: anchors/F10, mos1372/F5, nit/adversarial/F12.
- M36: the D9 and D14 landing lines. Source: mos1372/F1.
- M37: the O1 and C3 notes add the off-host remote and its confirmation. Sources: the remote findings.
- M38: the REQ-PROJ-3 note. Source: nit/anchors/F11.
- M39: REQ-LIB-5's freshness sentence keys on the editor reporting a save as committed. Source: nit/adversarial/F9.
- M40: REQ-LIB-6 bars agent requests for a conversion and allows a suggestion in chat. Source: nit/jason/F9.
- M41: REQ-LIB-2's opening and old-path rule, and the "Mine" note. Source: nit/adversarial/F10.
- M42: REQ-LIB-8's lead sentence on Markdown story files. Source: nit/mos1372/F12.
- M43: REQ-LIB-6's citation sentence. Source: nit/anchors/F13.
- M44: REQ-LIB-5's version tag uses plain quotes. Source: nit/anchors/F15.
- M45: reference codes B5, D12, D10 and B4 name their source. Source: nit/mos1372/F11.
- Files the row would own: four files, with the id count going to 87. Sources: anchors/F1, adversarial/F4, decisions.n14 F4.
## d7 changes (mos-1379, Fenton's 571 B2)
- REQ-LIB-5 gains Mos's three sentences after the extracted-text sentence. The text agents read has tracked changes accepted. Comments, and text with tracked deletions shown, each wait for a setting only a human turns on, off by default. Its version tag cites Q222 for the two settings, which is the only text here beyond Mos's.
- J-d gains Mos's sentence on comments and tracked deletions.
- Fenton's B1 is design only. d6's "no agent credential reaches it" holds (R8 replaces it in d8), and the shared helper stays #431.
## d6 changes (Webby round 3, webby-0207)
- B1: titles for REQ-LIB-8 and REQ-LIB-9 in the requirements.json note and the file list. REQ-LIB-9 takes Webby's title. REQ-LIB-8 keeps mine, because Webby's ("...one-way import that archives the Markdown under its old path") leaves out D2's story files started in the editor.
- B2: REQ-LIB-2 makes a Markdown file at a converted file's old path unmapped, ahead of the playground and canon rules, so a playground conversion is covered too. REQ-LIB-8's old-path bullet says "neither canon nor playground".
- B3: the slice note names Q226 F42's three rows (C2-02, C2-03b, C2-11b). C2-11a joined the slice with C2-11b, because C2-11b needs it. Both are slice rows that don't gate 10-27, as design 9.2, case2-rows.md:1655 and the impact map's A57 say. The 'F42 wins' sentence is gone from the note in d8, so no queue change follows from it.
- N10: the cite-scope replacement is scoped to REQ-LIB-2. The 1.14 note's copy stays.
- N11: the notes say REQ-LIB-8 adds the by-id exclusion form REQ-LIB-3 doesn't have.
- N12: J-h marks the autosave intervals for Jason.
- N13: J-b names REQ-LIB-5's "Connections are always visible" tag and Q226's "another way to handle the visual brain map".
- N14, not taken: REQ-LIB-4's title stays internal F3's text, as mos-1372 D11 ruled. Webby's alternative, "...and agents read Markdown from it alone" (120 chars), is Mos's call.
## Where each mos-1372 item landed
- D1: REQ-LIB-2's DOCX sentences, the REQ-LIB-8 lead and import bullet, C1 above, and the notes. "Playground files stay Markdown in 1.17" is gone.
- D2: REQ-LIB-2's "for one the human starts in the editor" and the REQ-LIB-8 new-story-file bullet. The universe-and-book note is now true.
- D3: the REQ-LIB-8 order bullet. This also settles N8.
- D4: REQ-LIB-8's one-way bullet, which carries the archive refusal and consequence F2's text, and the 571 list item.
- D5: it landed in REQ-LIB-2's "a Markdown file at a converted file's old path is unmapped" in Webby's B2 form, and in the REQ-LIB-8 old-path bullet.
- D6: REQ-LIB-5's freshness sentences.
- D7 and mos-1375: REQ-LIB-4's remote sentences, the remote step in REQ-LIB-8's order bullet, the fourth opening condition and the 1.17 note on when conversion opens, plus the 571 list item on W4 section 7.3, which replaces the no-remote rule of the old W4 section 7.4. The impact map's item 2 adds "only the stack's host pushes, and no agent credential reaches it", which R8 words in d8 as "no agent can reach it with any credential".
- D8: the REQ-LIB-5 replacement, the import bullet's wiki-link sentence, the Risks line, the note quoting the old sentence, and "REQ-LIB-1 only gains sentences".
- D9: the 1.17 note that agents read a converted story file through the Case 2 lookups, from the d4 check's consistency B2, and J-d, which puts the read model to Jason as his call.
- D10: the d4 check's B5 sentence, in REQ-LIB-8.
- D11: internal F3's clause in the REQ-LIB-4 section, and in the notes the title as Mos amended it for N14.
- D12: the whole 1.16 sentence replaced, and quoted in full in the notes.
- D13: consequence F1's text, in REQ-LIB-4 and REQ-LIB-8's first bullet.
- D14: the row text from the d4 check's consistency B1, in the mark-and-move bullet and C3 above.
## What d5 adds beyond mos-1372 (for Webby and Mos to check)
From the impact map, folded as mos-1368 item 1 asked:
- A1: the Console shows a cite's format and converted state (REQ-LIB-2).
- A2: the logged events and the several-humans setting, default owner only, under Q222.
- A3: the import is outside the vocabulary, the hard-wait list is unchanged, and the archive move isn't `data.delete`. The C6 code site is in the 571 list.
- A4: the section lead and REQ-LIB-1's writing-store sentence.
- A6: format and location in every answer, extracted text with DOCX locators, links across formats.
- A7: read-only extends to the store and the archive, no agent action on a story file in any format, no agent DOCX write, and role contracts state the formats. C1's role contract line is a 571 build item.
- A8: the DOCX cite shape, and a cite naming an archived file as current is refused.
- A9: a hybrid sees a source's DOCX canon through REQ-LIB-2's source scope, and REQ-LIB-8 lets an exclusion name a DOCX document by its id. The id form lets the human exclude a single DOCX started in the editor, which has no old path. An archived file isn't canon, so no hybrid sees it.
- A10: REQ-LIB-9, so the count is 87, not 86.
- A11: the Hermes gate, from item 3.
- A12: the C2-19 promotion sentence.
- A13: the broker's path check treats the archive folder as story.
- A14 and C5: two Risks lines.
- A15: the flagged-new-file bullet. It sits beside the note from the d4 check's B4, "a new Markdown file in a book folder is still canon". The file stays canon and is offered for import.
- A16: three titles change and two stay.
- C2: manifest order for the manuscript lookup.
- F3: the C2-02 gating note.
- F4: Mos's measurement.
Mine, beyond either source:
- REQ-LIB-2 opens "A Markdown file's scope comes from its path and from past imports". DOCX scope comes from the source, so "a file's" would be false.
- REQ-LIB-9's autosave sentence. It is Mos's reading of F41's "instantly committed", with human-set intervals. The exact intervals stay in the design.
Not taken:
- Impact map item 4's "files in unmarked folders are eligible one at a time", for folders outside every book folder and playground only. Their files are unmapped under REQ-LIB-2, so a DOCX made from one would have no universe or book to keep. The human maps such a folder into a book folder or a playground first, under REQ-LIB-1. A file in an unmarked folder inside a book folder or a playground is canon or playground, and the import takes it one file at a time.
- A6's named chapter-links view. D8 takes B8's "no graph shows them yet", and J-b puts the view to Jason. Jason's O2 (Q239) takes the view in d9.
## Marked for Jason (additions in the text he sees)
- J-a. Whether "We will not run the systems in parallel" applies per chapter or as one switch per book. His call. As written, it applies per chapter.
- J-b. A converted chapter's DOCX is not in Obsidian's graph. Obsidian shows the chapter only through its archived Markdown, and no DOCX edit reaches that file's links. REQ-LIB-5 still cites two TARGET lines, "Visualization of data via Obsidian or equivalent is required" and "Connections are always visible". Mos's reading is that 1.17 as written meets neither line for converted chapters. Their current links show to the user only as clickable text inside the editor, and no graph or list shows them. Q226 leaves room for "another way to handle the visual brain map". The O2 design that landed for Vikunja 571 at 767bb62c7 holds a Console Connections view and its tests as later work that waits for this answer. His call whether 1.17 requires that view. As written, it does not. Mos recommends that it does, because impact map A6 says "Recommended: name the view" and TARGET says "Connections are always visible". Jason answered O2 (Q239): 1.17 requires the view. d9 writes it into REQ-LIB-5, its note and the Risks line. The view comes with the conversion work after 10-27, the 10-27 Case 2 release stays on Markdown (Q235 P6, Q237), and the import does not wait for the view (mos-1443 R3).
- J-c (mos-1374): "The store pushes to a remote (D7), and the Case 2 VM is in the nightly PBS backup. For a fixed restore point before her first real import, a manual backup of VM 1012 with PBS protect runs first. That step is reversible and needs no reboot." Mos's reading is that this sits inside the P5 go step, so it needs no new question.
- J-d. How agents read a converted chapter, D9. His call. As written, an agent reads it through the ordinary Case 2 lookups in any thread or room, under the same project and universe access as Markdown canon. This is Mos's reading of F41 and REQ-LIB-7. The other choice is the model in the earlier O2 design, W4 sections 7.1 and 7.2. Under it, an agent reads a converted chapter only in a new writing conversation that holds one human and one agent, only after the business owner grants that agent access to that document, and by default only what the human attaches to each message. Comments and tracked deletions stay hidden from agents until a human turns on a setting for each. Markdown has neither, so the default keeps agents at the access Markdown gives them. Those two sentences are Mos's ruling mos-1379. A yes to the text as written settles it.
- J-e. Versioning means the editor's tracked changes plus one git commit per save.
- J-f. A converted chapter can be edited only in the Console while the stack is reachable. Obsidian no longer edits it offline.
- J-g. The import takes Markdown only. Importing .doc files stays a separate task.
- J-h. Autosave under REQ-LIB-9. Jason's Q226 F41 says "All changes are instantly committed and available to the agents." Mos's reading, recorded with that ruling, is "Each save is a commit at once, and agents read it at their next lookup." At the O2 design's D13 defaults, a save commits at most 2 seconds after a pause in typing or 15 seconds into steady typing, with no human action needed. Mos's reading in mos-1359 counts that delay as "instantly committed". Only a human changes the intervals. The PRD names no values, and the defaults stay in the design. Whether a delay of seconds fits his word "instantly" is his call, so this is marked for him.
- J-i. In 1.17 a playground story that is DOCX can't become canon. That covers a playground Markdown file the human imports, a story the human starts in a playground in the editor, and the DOCX of a draft universe after it is made real. Today Melanie promotes a playground file by moving it into a book folder in Obsidian, and a DOCX in the writing store can't be moved that way. She can start a new story in the book and paste the text in, but it gets a new document id and the playground copy keeps the history. A later version adds DOCX promotion with C2-19, which comes after the slice.
- J-j. Web links, text boxes and fields in a converted chapter. Jason's Q226 F41 says "All changes are instantly committed and available to the agents." The reader in this version can't read a web link, a text box, a field or hidden text. As written, the import turns each web link into plain text that keeps its label and address, and the human confirms that in the fidelity report. A web link that can't be kept safely as plain text refuses the import. If a later edit adds one of these, the save keeps it and the editor warns the human. Agents then get none of that part's text until a save takes it out.
- J-k. The 1.12 note Jason approved says bus writes, C2-02 and C2-03b, don't gate 10-27. His Q226 "F42: ok" moved them into the 10-27 slice, and design 9.2 counts them in the smallest slice that lets Melanie start. Mos reads that as making them gate 10-27. The editor rows C2-11a and C2-11b still don't gate it, per his Q195 words "we need to get it moving as an add-on".
- J-l. REQ-LIB-9 does not use REQ-PROJ-3's "permissive license" bar. It takes the licenses that the editor's independent security review accepted, because that review cleared fonts under the SIL Open Font License and the Ubuntu Font License, which not every reader counts as permissive. Mos's reading.
Marked as changes beyond P1 to P6, from the impact map (Q17, item 5):
- A1 (archived scope and canon cites)
- A2 (the conversion requirement, REQ-LIB-8)
- A3 (outside the vocabulary, hard-wait list unchanged)
- A6 (lookups across formats)
- A7 (agent bounds)
- A8 (DOCX cites)
- Item 2 and mos-1375: each writing-store commit is pushed to a remote off the stack's host. Only a human sets it, it starts unset, and a repository on the stack's host doesn't count. Only the stack's host pushes to it, and no agent can reach it with any credential. Import and new story files stay closed until the remote is set and checked, and each import's archive push waits until the remote holds the DOCX commit. This keeps "Git is used for all changes -- local and remote" true for DOCX chapters.
- Item 3 (the Hermes gate)
- Item 4. Canon and playground story files convert one file at a time, including files in unmarked folders inside a book folder or a playground. Type-folder and supporting files stay Markdown. A story file outside every book folder and playground has no universe or book, so it converts only after a human maps its folder into a book folder or a playground. The mapping step is Mos's reading of P1 and Q30.
The F4 measurement goes with them.
## Files the row would own
The id count goes from 85 to 87. 1.16 owned three files because its count stayed at 85. Like 1.13, the last version that added ids, the row owns four files:
- `docs/prd/mosaic-stack.md`
- `packages/tasks/requirements.json`: the version 1.17, the two new ids REQ-LIB-8 and REQ-LIB-9 with their titles, and the changed titles of REQ-LIB-1, REQ-LIB-2 and REQ-LIB-4. The new ids go after REQ-LIB-7 and before REQ-INST-1, in the same order as the PRD's bullets.
- `packages/tasks/tests/requirements.test.mjs`: the version pin 1.17, the id count of 87, and the duplicate-id message, which goes from `requirements[85].id: REQ-ROLE-1 twice` to `requirements[87].id: REQ-ROLE-1 twice`.
- `packages/bus/tests/requirements.test.mjs`: the list length, which goes from 85 to 87.
The gate would match 1.16's:
1. A reviewer approves the text.
2. Jason says yes to the exact text through Mos.
3. Both `requirements.test.mjs` files, in `packages/tasks/tests` and `packages/bus/tests`, and every `scripts/test-*.sh` that reads the PRD or `requirements.json` are green on Sage's gate.
4. Mos gets the landing commit.
agents/sage/work/prd-1-17/d8-to-d9.diff
+118
View File
@@ -0,0 +1,118 @@
--- DRAFT-d8.md 2026-10-23 06:16:54.374694135 -0500
+++ DRAFT-d9.md 2026-10-23 10:25:28.160826165 -0500
@@ -1,6 +1,6 @@
# PRD 1.17 draft: Case 2 story files are DOCX (Q235 to Q237, P1 to P6)
-Sage, 2026-10-23, for mos-1366 item 1 and Vikunja 570. Draft 8. It is d7 plus Mos's d8 fix list mos-1443 (see "d8 changes"). d7 is d6 plus Mos's ruling mos-1379 on Fenton's 571 B2 (see "d7 changes"). d6 is d5 with Webby's round 3 (webby-0207) fixed: B1 to B3 and N10 to N13, with N14 left for Mos (see "d6 changes"). d5 folds in:
+Sage, 2026-10-23, for mos-1366 item 1 and Vikunja 570. Draft 9. It is d8 plus Jason's Q41 answer O2 (DECISIONS Q239, mos-1467), which makes J-b yes, and Webby's round 5 N15 to N17 (webby-0210) (see "d9 changes"). d8 is d7 plus Mos's d8 fix list mos-1443 (see "d8 changes"). d7 is d6 plus Mos's ruling mos-1379 on Fenton's 571 B2 (see "d7 changes"). d6 is d5 with Webby's round 3 (webby-0207) fixed: B1 to B3 and N10 to N13, with N14 left for Mos (see "d6 changes"). d5 folds in:
- Mos's d4 check ruling mos-1372 (D1 to D14; D15 was dropped).
- mos-1374, which replaces J-c.
- The impact map mos-1368 (jason-master-restart d183246, `projects/mosaic-mvp/case2-docx-impact-map.md`: A1 to A16, critic items C1 to C6, items 2 to 7).
@@ -103,10 +103,11 @@
### REQ-LIB-2
-Replace "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." with:
+Replace "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." with:
"A Markdown file's scope comes from its path and from past imports, prefixes
first: a Markdown file under the archive folder is archived, one under a
@@ -190,8 +191,8 @@
Replace "The user sees them in Obsidian's graph and backlinks." with "The user sees
a Markdown file's links in Obsidian's graph and backlinks. A DOCX story file's
-wikilinks stay clickable in the Console's editor (O2 design D11), and no graph
-shows them yet."
+wikilinks stay clickable in the Console's editor (O2 design D11). The Console
+shows a converted chapter's links out and in, in a Connections view."
Version tag: 'and "Connections are always visible".)' becomes 'and "Connections
are always visible". Version 1.17, with Q222 for the two settings.)'
@@ -273,8 +274,9 @@
- Each stage of an import writes a logged event. The import's record on the
stack's host names the source file's path, commit and blob and the new
document id, and each event points to that record.
- - After a conversion, a Markdown file at the converted file's old path is neither
- canon nor playground. Lookups leave it out, the format map flags it, and the human is told.
+ - After a conversion, a Markdown file at the converted file's old path is
+ neither canon nor playground. Lookups leave it out, the format map flags it,
+ and the human is told.
- A new Markdown story file in a book folder that holds converted files stays
canon until its import, unless it sits at a converted file's old path or under
a playground prefix. The Console flags it and offers the import. Nothing
@@ -413,8 +415,8 @@
push within about a minute."
- REQ-LIB-5, the 1.16 sentence: "The user sees them in Obsidian's graph and
backlinks." A converted chapter's connections show in Obsidian only as they
- stood at conversion, until a Console view of their links exists. Q226
- records that view as a later option.
+ stood at conversion. The Console's Connections view shows their current
+ links.
- REQ-LIB-6, the 1.16 sentence: "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."
@@ -451,8 +453,8 @@
not `git diff`. (Version 1.17.)"
- "A converted chapter's DOCX is not in Obsidian's graph. Obsidian shows the
chapter only through its archived Markdown, and no DOCX edit reaches that file's
- links. The DOCX's current links show only in the Console's editor until a
- Console view of them exists. (Version 1.17.)"
+ links. The DOCX's current links show in the Console's editor and its
+ Connections view, not in Obsidian. (Version 1.17.)"
- "Conversion can't be undone in place. Front matter, wiki link forms and
unsupported blocks may not survive it, and the mirror can't refuse the user's
push to an archived file. The controls are the fidelity report, the human's
@@ -467,6 +469,13 @@
import events, and the import's recovery covers both cases (Vikunja 571).
(Version 1.17.)"
+## d9 changes (Q239 and Webby round 5)
+
+- J-b yes (Q239, mos-1467): REQ-LIB-5's replacement ends "The Console shows a converted chapter's links out and in, in a Connections view." in place of "and no graph shows them yet". The REQ-LIB-5 note and the graph Risks line name the view as required, not later. J-b and the "Not taken" A6 line record the answer. Nothing else in the PRD text changes.
+- N15: the D7 landing line gives R8's wording beside the impact map's quote.
+- N16: the d7 changes line notes that R8 replaces "no agent credential reaches it" in d8.
+- N17: the REQ-LIB-2 Replace quote and the REQ-LIB-8 old-path bullet are rewrapped under 82 columns. Their words are unchanged.
+
## d8 changes (Mos's d8 fix list, check wf_63bba879-180)
- R1: REQ-LIB-4's tail covers DOCX saves, which agents see at their next lookup after the editor reports them as committed. The notes quote the whole 1.16 sentence. Source: nit/jason/F10.
@@ -535,7 +544,7 @@
- REQ-LIB-5 gains Mos's three sentences after the extracted-text sentence. The text agents read has tracked changes accepted. Comments, and text with tracked deletions shown, each wait for a setting only a human turns on, off by default. Its version tag cites Q222 for the two settings, which is the only text here beyond Mos's.
- J-d gains Mos's sentence on comments and tracked deletions.
-- Fenton's B1 is design only. d6's "no agent credential reaches it" holds, and the shared helper stays #431.
+- Fenton's B1 is design only. d6's "no agent credential reaches it" holds (R8 replaces it in d8), and the shared helper stays #431.
## d6 changes (Webby round 3, webby-0207)
@@ -556,7 +565,7 @@
- D4: REQ-LIB-8's one-way bullet, which carries the archive refusal and consequence F2's text, and the 571 list item.
- D5: it landed in REQ-LIB-2's "a Markdown file at a converted file's old path is unmapped" in Webby's B2 form, and in the REQ-LIB-8 old-path bullet.
- D6: REQ-LIB-5's freshness sentences.
-- D7 and mos-1375: REQ-LIB-4's remote sentences, the remote step in REQ-LIB-8's order bullet, the fourth opening condition and the 1.17 note on when conversion opens, plus the 571 list item on W4 section 7.3, which replaces the no-remote rule of the old W4 section 7.4. The impact map's item 2 adds "only the stack's host pushes, and no agent credential reaches it".
+- D7 and mos-1375: REQ-LIB-4's remote sentences, the remote step in REQ-LIB-8's order bullet, the fourth opening condition and the 1.17 note on when conversion opens, plus the 571 list item on W4 section 7.3, which replaces the no-remote rule of the old W4 section 7.4. The impact map's item 2 adds "only the stack's host pushes, and no agent credential reaches it", which R8 words in d8 as "no agent can reach it with any credential".
- D8: the REQ-LIB-5 replacement, the import bullet's wiki-link sentence, the Risks line, the note quoting the old sentence, and "REQ-LIB-1 only gains sentences".
- D9: the 1.17 note that agents read a converted story file through the Case 2 lookups, from the d4 check's consistency B2, and J-d, which puts the read model to Jason as his call.
- D10: the d4 check's B5 sentence, in REQ-LIB-8.
@@ -593,12 +602,12 @@
Not taken:
- Impact map item 4's "files in unmarked folders are eligible one at a time", for folders outside every book folder and playground only. Their files are unmapped under REQ-LIB-2, so a DOCX made from one would have no universe or book to keep. The human maps such a folder into a book folder or a playground first, under REQ-LIB-1. A file in an unmarked folder inside a book folder or a playground is canon or playground, and the import takes it one file at a time.
-- A6's named chapter-links view. D8 takes B8's "no graph shows them yet", and J-b puts the view to Jason.
+- A6's named chapter-links view. D8 takes B8's "no graph shows them yet", and J-b puts the view to Jason. Jason's O2 (Q239) takes the view in d9.
## Marked for Jason (additions in the text he sees)
- J-a. Whether "We will not run the systems in parallel" applies per chapter or as one switch per book. His call. As written, it applies per chapter.
-- J-b. A converted chapter's DOCX is not in Obsidian's graph. Obsidian shows the chapter only through its archived Markdown, and no DOCX edit reaches that file's links. REQ-LIB-5 still cites two TARGET lines, "Visualization of data via Obsidian or equivalent is required" and "Connections are always visible". Mos's reading is that 1.17 as written meets neither line for converted chapters. Their current links show to the user only as clickable text inside the editor, and no graph or list shows them. Q226 leaves room for "another way to handle the visual brain map". The O2 design that landed for Vikunja 571 at 767bb62c7 holds a Console Connections view and its tests as later work that waits for this answer. His call whether 1.17 requires that view. As written, it does not. Mos recommends that it does, because impact map A6 says "Recommended: name the view" and TARGET says "Connections are always visible".
+- J-b. A converted chapter's DOCX is not in Obsidian's graph. Obsidian shows the chapter only through its archived Markdown, and no DOCX edit reaches that file's links. REQ-LIB-5 still cites two TARGET lines, "Visualization of data via Obsidian or equivalent is required" and "Connections are always visible". Mos's reading is that 1.17 as written meets neither line for converted chapters. Their current links show to the user only as clickable text inside the editor, and no graph or list shows them. Q226 leaves room for "another way to handle the visual brain map". The O2 design that landed for Vikunja 571 at 767bb62c7 holds a Console Connections view and its tests as later work that waits for this answer. His call whether 1.17 requires that view. As written, it does not. Mos recommends that it does, because impact map A6 says "Recommended: name the view" and TARGET says "Connections are always visible". Jason answered O2 (Q239): 1.17 requires the view. d9 writes it into REQ-LIB-5, its note and the Risks line. The view comes with the conversion work after 10-27, the 10-27 Case 2 release stays on Markdown (Q235 P6, Q237), and the import does not wait for the view (mos-1443 R3).
- J-c (mos-1374): "The store pushes to a remote (D7), and the Case 2 VM is in the nightly PBS backup. For a fixed restore point before her first real import, a manual backup of VM 1012 with PBS protect runs first. That step is reversible and needs no reboot." Mos's reading is that this sits inside the P5 go step, so it needs no new question.
- J-d. How agents read a converted chapter, D9. His call. As written, an agent reads it through the ordinary Case 2 lookups in any thread or room, under the same project and universe access as Markdown canon. This is Mos's reading of F41 and REQ-LIB-7. The other choice is the model in the earlier O2 design, W4 sections 7.1 and 7.2. Under it, an agent reads a converted chapter only in a new writing conversation that holds one human and one agent, only after the business owner grants that agent access to that document, and by default only what the human attaches to each message. Comments and tracked deletions stay hidden from agents until a human turns on a setting for each. Markdown has neither, so the default keeps agents at the access Markdown gives them. Those two sentences are Mos's ruling mos-1379. A yes to the text as written settles it.
- J-e. Versioning means the editor's tracked changes plus one git commit per save.