stack/packages/project/README.md

# 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. These reads write
nothing; the human writer is the next section.

## The human editor writer (row 148)

`listProjectFiles({business,project,dataRoot})` returns `{head, files:[{path}]}`:
spec/north-star.md and the Markdown files directly under docs/ (name
`[A-Za-z0-9][A-Za-z0-9._-]{0,127}.md`), as committed at HEAD and in path order. An
uncommitted file, a subdirectory, a non-Markdown file and a link are not listed.
`documentPath(path)` is the one definition of those paths, shared by the reads and
the writer.

`writeHumanFile({business,project,dataRoot,path,content,base})` is the Console
editor's save. It replaces the whole text of an existing document with `content` and
makes one local commit, `Edit <path>`, authored by `business.human`. Only the human
bus verb `project.file.save` calls it; the agent writer (`writeRecord`) is
unchanged and still refuses spec/. It never creates a file, never pushes and
creates no remote.

`base` is the full commit the editor opened: the file's last commit at HEAD. If the
file's last commit is any other, the writer refuses `stale-base` and writes nothing,
whoever made the newer commit. The check runs under the same exclusive lock and the
same clean-tree rules as the agent writer, so a tree with pending changes refuses
`project-dirty` and a concurrent writer `project-busy`. Other refusals:
`project-record-path` (a path outside the two), `project-record-invalid` (empty
content, a NUL, text that is not well-formed UTF-8, over 1 MiB, or a `base` that is
not a full commit id) and `project-read-missing` (no such document).

Tests: `packages/project/tests/human-file.test.mjs`.