Row 138 round 2, Rocko's candidate e3f9a400 (43 paths) on26a0b0fab. Dewey approved (comment 28754) after round 1 changes (comment 28752): D1-D5 mutants killed, the 17 touched test files run singly passed 124/124. Rocko's own run: 753 tests and 59/59 mutants killed. The bus gains the project adapter through runtime.mjs, the way it already injects the organization, so broker.mjs takes no new imports and refuses with project-not-configured when no adapter is set. The project socket timeout is 120s. Roles gain record.write. The schema moves from 3e to 3f; the live migration follows MIGRATION.md and needs Mos's window. Sage's landing gate ran onc842686d5plus the candidate: 25 steps, all rc 0 (15 packages, 10 script suites), network sage-r138_default removed. Co-Authored-By: Claude Opus 5.5 <[email protected]>
146 lines
7.9 KiB
Markdown
146 lines
7.9 KiB
Markdown
# Project record repository — layout 1
|
||
|
||
A project's records live in a separate local git repository. This is distinct
|
||
from its code checkout (`business.projects[project].root`) and the working bare
|
||
repository used for code review. No remote is created or contacted.
|
||
|
||
Set an optional normalized absolute `repo` in the business project entry:
|
||
|
||
```json
|
||
{"projects":{"stack":{"root":"/work/code","repo":"/work/project-records"}}}
|
||
```
|
||
|
||
Without `repo`, records live at
|
||
`<dataRoot>/projects/<business>/<project>/`. The records path must not overlap any declared project's code root,
|
||
including another project's root (in either direction). Record paths and their existing ancestors must not be symlinks.
|
||
|
||
```sh
|
||
mosaic project init acme stack
|
||
mosaic project check acme stack
|
||
```
|
||
|
||
Init failure removes its own files and Git directory, allowing retry. A target
|
||
that existed empty is preserved; newly created empty parent directories are
|
||
removed. Unrelated files at the root or inside a layout directory are preserved,
|
||
so a concurrent human save can leave a non-empty target that needs inspection
|
||
before retry. Changed ownership of an initializer path refuses
|
||
`project-init-cleanup` and preserves that path for reconciliation. The private
|
||
`.git` created by this initializer is removed as a unit; external tools must not
|
||
modify Git metadata during initialization.
|
||
|
||
Both commands use the existing system and business config loaders. Init requires
|
||
an outside-agent CLI environment, a declared project and an empty directory. It
|
||
creates `main` and the first commit as the business's human, with a local
|
||
`<human>@mosaic.invalid` email. Check is read-only; it exits 2 and lists all
|
||
problems found. An otherwise valid layout with no readable HEAD commit refuses
|
||
`project-no-commit` (CLI exit 2), rather than reporting success. Usage exits 4; configuration problems exit 3. No bus is needed.
|
||
|
||
## Layout
|
||
|
||
| Path | Contents |
|
||
| --- | --- |
|
||
| `project.json` | `layoutVersion: 1`, business, project, name, createdAt |
|
||
| `spec/north-star.md` | Human-editable Markdown north star |
|
||
| `docs/` | Markdown documentation; check accepts nested docs |
|
||
| `requirements/ID.json` | One requirement per file |
|
||
| `decisions/ID.json` | One decision per file |
|
||
| `templates/` | project.json, requirement.json, decision.json, document.md, north-star.md |
|
||
|
||
Empty requirements and decisions directories contain an empty `.gitkeep`, so the
|
||
layout survives git checkout. That marker is checked separately from records.
|
||
Init makes no example requirements or fictional decisions. The initial project
|
||
name is its project ID; the user can edit the display name in project.json.
|
||
|
||
A requirement has `recordVersion: 1`, `id`, `title`, `text`, and `status`
|
||
(`draft`, `accepted`, `complete`). A decision has `recordVersion: 1`, `id`,
|
||
`question`, `options` (2–9 distinct `{key,text}` entries), `recommendation`,
|
||
`status` (`open`, `accepted`, `rejected`) and `choice` (null while open, an option
|
||
key when closed). These are local reference records, not bus authorization or
|
||
approval. Decision spec citations and settlement policy belong to row 138.
|
||
|
||
Schemas are fixed in `packages/project/schemas/`, never loaded from the project.
|
||
Every JSON template validates against its record schema. Editing templates
|
||
cannot weaken validation; adding a project-local schema is refused. The schema
|
||
validator implements a closed subset of JSON Schema 2020-12 matching these
|
||
schemas and refuses any unsupported schema keyword. Dates use canonical
|
||
millisecond UTC. Files are bounded to 1 MiB, valid UTF-8 without NULs, regular,
|
||
and not hard-linked. JSON record names must equal their IDs. Unknown top-level
|
||
paths, missing required paths, unexpected templates and non-Markdown docs refuse.
|
||
The git directory is inspected separately, without reading project data as git
|
||
configuration or running hooks.
|
||
|
||
## Shared APIs
|
||
|
||
Import from `packages/project/src/index.mjs`:
|
||
|
||
```js
|
||
const context = { business, project: 'stack', dataRoot };
|
||
projectRepo(context); // absolute repo path; no writes
|
||
await initProject(context); // {repo, commit}
|
||
await checkProject(context); // {ok, repo, problems}
|
||
validateRecord('requirement', value); // array of problem strings
|
||
await writeRecord({
|
||
...context,
|
||
path: 'requirements/REQ-PROJECT-1.json',
|
||
record: value,
|
||
author: { definition: 'coder', instance: 'builder' },
|
||
}); // {repo, path, commit}
|
||
```
|
||
|
||
`writeRecord` is the single agent record writer. It accepts `docs/NAME.md`,
|
||
`requirements/ID.json` and `decisions/ID.json`, validates first, and makes a
|
||
local commit authored and committed as `<definition>.<instance>` with a local
|
||
`.invalid` email. Actor metadata is trusted caller input whose shape is
|
||
validated here; row 138's broker must derive it from the bound role. This
|
||
package neither authenticates an agent nor grants it authority.
|
||
|
||
An author with definition `human` refuses `project-author`; this agent writer
|
||
provides no human record write path. Every agent path under `spec/` refuses with `project-spec-human-only`. Agents
|
||
cannot write project.json, templates or git metadata through this API. A valid
|
||
but unchanged record refuses `project-record-unchanged` without an empty commit.
|
||
|
||
Stricter safeguards agreed with Sage (sage-0400): a remote refuses
|
||
`project-remote`; pending tracked, staged, untracked or ignored files and hidden
|
||
index flags refuse `project-dirty`. The writer never folds human edits into its
|
||
commit. Concurrent writers refuse `project-busy` through an exclusive local
|
||
lock; no stale lock is automatically removed. Links, indirect git stores and
|
||
unsupported local git config refuse. Git uses no inherited global/system
|
||
configuration, no hooks, fsmonitor, filters or transports, and runs in bounded
|
||
process groups using the existing seat git runner.
|
||
|
||
Records publish with a temporary file, fsync and rename, then a commit of only
|
||
that path. On git failure with HEAD unchanged, only the writer's file/index
|
||
change is restored. If HEAD changed while an error occurred, the writer refuses
|
||
`project-commit-uncertain` and preserves evidence for reconciliation; it never
|
||
rewinds history. Locking serializes this writer, not arbitrary human editors:
|
||
callers must coordinate simultaneous human saves. No destructive repair, push,
|
||
remote creation, role grant, spec-confirmation mechanism or live action ships.
|
||
|
||
Tests: `node --test packages/project/tests/*.test.mjs`. Fixtures only.
|
||
|
||
## Committed file reads (row 138)
|
||
|
||
`readProjectFile({business,project,dataRoot,path,commit?})` reads only
|
||
spec/north-star.md or a named docs/NAME.md; `readSpec({business,project,dataRoot,commit?})`
|
||
fixes the spec path. Both are async and read-only, share repository/path checks,
|
||
refuse remotes and unsafe Git metadata, and validate committed project.json
|
||
identity. Working-tree edits do not replace committed content. A supplied full
|
||
SHA-1 must be a commit reachable from a captured HEAD.
|
||
|
||
The result is {repo,path,head,revision,commit,content,author,log,truncated}.
|
||
commit is the last commit changing the file at revision, not necessarily HEAD;
|
||
content preserves exact valid UTF-8 including trailing newlines, up to 1 MiB with
|
||
no NUL. Log has at most 100 entries, newest first, each
|
||
{commit,author:{name,email},at,subject}; at is canonical UTC. truncated says more
|
||
entries exist. Reads reject nonregular Git blobs, missing paths and invalid
|
||
content. History output is separately bounded to 256 KiB.
|
||
|
||
readSpec adds confirmed=true exactly when the file commit author.name equals
|
||
business.human. An agent-authored latest change stays unconfirmed. This is local
|
||
Git provenance, not a cryptographic identity proof. Broker citation validation
|
||
compares a fresh current snapshot and never uses an older read as authority.
|
||
Read errors are ProjectError: project-read-path, project-read-commit,
|
||
project-read-missing, project-read-content, project-invalid, plus existing
|
||
project-id/path/not-declared/repository/remote/git codes. No write or spec save
|
||
API is added; row 148 owns the human editor writer and its stale-base check.
|