6. The state model

.familiar/core/state-schema.md defines schema version 1.0. A generated report is a view. It is never another source of truth.

6.1 Authoritative surfaces

Surface	What it holds	How it changes
5-System/project-config.md	Stable settings, workspace path, schema version, installed extensions, capability record	In place, through setup or maintenance only
5-System/project-context.md	Background, objectives, stakeholders, lasting constraints	In place, for important lasting changes only
5-System/Memory/status-snapshot.md	Current phase, blockers, next actions, latest revision	Replaced whole, in one step
5-System/Memory/status-log.md	Important events in date order	Append only
4-Trackers/tasks.md	Action, owner, status, due information, blockers	In place, by task routes
4-Trackers/timeline.md	Milestones and dates	In place when a date moves
4-Trackers/meetings.md	Planned internal and client meetings: series rules, single meetings, moves and cancellations by date, and each meeting’s agenda (optional)	In place. Rows are never deleted.
5-System/Decisions/*.md	Approved decision, reasons, date, consequences	A new record. Changes keep the history.
5-System/Handoffs/*.md	Temporary instructions for the next session on unfinished work	A new record. Its status can change in place.
5-System/user-preferences.md	How the user wants familiar to work in this project	In place. The referencing method is set once, on the first Word draft that cites. Everything else changes through save → To memory only. A signature for this project only is a hand edit. The shared signature is in ~/.familiar/user-preferences.md, written by system-settings → Preferences.
5-System/notes.md	Loose notes that fit no other file	Append or in place, through save → To memory

5-System/Memory/save-progress.md, overview reports, briefings and dashboards are views that can be rebuilt. They never override the files above.

Freshness and session provenance

Knowledge pages record last_verified and review_by, and the index shows both. The check-in health check reports pages past their review_by date. It does not rewrite project knowledge on its own. An agent’s own built-in memory is not a source of truth and never overrides these files.

Core does not keep a log of every model session. The model name and effort setting are operating details, not project facts. Record them only as provenance for important research, decisions or deliverables.

6.2 Required metadata

Every state file that changes opens with:

1.0

<!-- revision: <non-negative integer; 0 is an unwritten scaffold> -->
<!-- last-updated: <ISO-8601 timestamp or date> -->

The activity log is append-only and uses no revisions. Entries go from oldest to newest. Each entry has its own date and the task or decision IDs it affects.

6.3 The stale-write protocol

Before a route writes, it records the revision it read. The new version adds one to the revision. If the revision on disk is no longer the one the route read, CORE-STALE-WRITE applies: stop, read again, reconcile, and report the conflict. Do not overwrite. Where the agent supports it, write to a temporary file beside the original and then replace the original in one step.

This protocol detects conflicts, and only some of them. It catches a second writer that also follows the protocol. It does not lock, merge, or stop a writer that ignores it. familiar supports one active writer at a time.

It also does not work across a synced folder, which is the case you are most likely to hit. The revision check reads the local disk. OneDrive, SharePoint, Dropbox, iCloud Drive and similar apps sync after a write. Two computers can both read revision 3 and both write revision 4, and neither check stops them. The sync app then keeps the last write, or makes a conflict copy.

The conflict-copy check knows these name patterns:

• a computer name added to the file name
• “conflicted copy”
• iCloud Drive’s name 2.md form (a space and a number before the extension)

A conflict copy lands inside the project folder. CORE-NO-DELETE forbids the agent to remove it, and a later read could mistake it for the real state. file-handling.md therefore requires a check for a conflict copy before each write, and a stop and report when the agent finds one. That check is the only part of this that familiar can enforce. The rest is a limit on how you work, described in INSTALL.md → Synced folders and concurrent use.

6.4 No cross-project exception

CORE-WORKSPACE-SILO has no exception for other projects. The workspace folder is a hard boundary in both directions. The agent never reads anything in another project, and never writes outside the active workspace.

A project never reads another project. The view across projects is the fleet hub. It is a separate folder, outside every project, that reads each registered project as data and keeps its own list (§5.4a). Nothing inside a project can name another project to read from.

6.5 Extension state surfaces

An extension declares its own state files. Each one is an object with four fields:

• path: relative to the workspace, never a plugin-cache path
• schema_version: the extension’s own version, separate from core’s 1.0
• update_behavior: plain text, in the style of the table above
• scaffold: whether the extension’s folder already includes the file

A scaffolded file ships at revision 0 with the extension’s schema version. Adding the same extension again later never replaces it. Package files are replaced. State files are not.

---