Plans can point at other plans. A plan can need another plan, inform it, or supersede it. A plan can also have a deadline the owner picked. These facts live in mozak.annotations.json, a sidecar next to mozak.json.
- A change to plan content needs a new direction approval. That clears the spec and the implementation grant. A dependency or a deadline must not cost that.
- A new field in
mozak.jsonwould need a format bump, and a 0.4.0 client would then refuse the scope. - The sidecar is invisible to 0.4.0 clients.
mozak.mdstays byte-identical with and without it. - Agent writes never carry the sidecar hash, so an annotation never makes an agent stale.
{
"format": "mozak.annotations/v1",
"scopeId": "ID",
"revision": "uuid of the last write",
"updatedAt": "UTC timestamp",
"plans": {
"PLAN": {
"refs": [
{ "id": "ref-...", "target": "scope/plan#outcome", "relation": "needs", "fromOutcome": "optional", "evidence": "the sentence that justifies it",
"provenance": { "ownerRef": "...", "ownerMessageAt": "...", "recordedAt": "...", "operationId": "...", "itemDigest": "..." } }
],
"deadline": { "date": "YYYY-MM-DD", "evidence": "...", "provenance": { } }
}
},
"receipts": { "OPERATION": { "requestDigest": "...", "revision": "...", "recordedAt": "...", "result": { "action": "annotate", "ids": [] } } }
}Objects are closed. An unknown key makes the file invalid. check reports it and annotate refuses to write until it is fixed by hand. Plans are never hidden by a broken sidecar.
Only the owner route mozak annotate writes the file. It takes the scope lock, writes one temp file and renames it once. The CAS input is the sidecar token in expectedAnnotations. graph returns the current token per scope in annotations. A retried identical request replays its receipt. The same operation ID with other input is refused (operation-conflict). See skills/mozak/references/routes.md for the request shape and the item kinds.
At write time each ref must resolve: the source plan and fromOutcome exist, the target scope is in the inventory, and the target plan (and outcome) exists or was merged into a live plan. A self reference and a duplicate ref are refused.
Temp files are named mozak.annotations.json.<uuid>.tmp. init and projection repair add mozak.annotations.json.*.tmp to .gitignore. The next write removes a leftover one, and check lists it meanwhile.
mozak-settings.json sits next to the inventory file. It is optional. There is one per installation. mozak never reads a mozak-settings.json inside a scope folder, because a scope folder can be a public repo. check reports such a file as settings-scope-file-deprecated.
{ "format": "mozak.settings/v1",
"concurrency": { "rebase": false },
"scopes": { "research": { "annotations": true }, "anpit": { "concurrency": { "rebase": true } } } }- Annotations are off by default (since 0.5.0). A scope without
"annotations": truebehaves like 0.4.7:mozak.annotations.jsonis never read,graph,ready,plans --sort deadline,checkand the Obsidian sidebar ignore it,mozak.mddoes not change, andannotateis refused withannotations-disabled. - Turn them on per scope with
scopes.<id>.annotations: true. annotations.personalVaultsfrom older settings files is accepted and has no effect.concurrency.rebaseturns on the experimental read-set rebase (seedocs/installation.md, Parallel writes). A per-scopescopes.<id>.concurrency.rebasewins over the top-level value. The default is off.- The key reserved for a later slice (
indexRoots) is accepted. Any other key is asettings-unknown-keyfinding with no effect. - A wrong value type or a missing
formatmakes the file invalid.annotatethen refuses withsettings-invalid,checkreports it, and rebase stays off.
A target scope/plan[#outcome] resolves in this order:
- The plan exists in the target scope.
- A live plan recorded folding it in (
decision.mergedPlanId). The ref then points at that plan. - Otherwise it is reported:
dangling(scope not in the inventory, plan missing, outcome missing) orunavailable(the target scope cannot be read now).
Reads never fetch for resolution. Every scope is read from its vault folder.
A date counts only when it directly follows a cue: before, by, deadline, deadline is, due, until, rok, rok je, do, prije. A weekday may sit in between, and a colon may follow the cue. Formats: YYYY-MM-DD, D Mon YYYY, D. M. YYYY., D. <Croatian month> YYYY. A date without a year is not a date.
The rule reads the title, purpose, rationale, constraints and every outcome that is not done. Past dates are dropped. A completed plan has no deadline. One future date left gives an inferred deadline. Several give candidates, and the agent proposes one deadline item for the owner to pick. An owner deadline always wins.
mozak graph (--scope ID | --all): plans, refs and their resolution, with counts.mozak ready (--scope ID | --all): open plans whoseneedsare met. A plan-level need blocks while the target plan is not completed. An outcome target blocks while that outcome is not done. A need fromfromOutcomeblocks only while that outcome is the plan's current outcome. Ready plans sort by deadline, then by how many plans need them. Plans superseded by a plan that is not rejected are listed apart.mozak plans --sort deadline: the usual groups, ordered by deadline. Rows gaindeadlineanddeadlineStatus.- MCP:
mozak_plan_graph,mozak_ready, andsortonmozak_plans. There is no MCP annotate tool. - The Obsidian sidebar lists outgoing and incoming refs under each plan row.
ref-dangling, ref-target-unavailable, annotation-plan-missing, needs-cycle, needs-closed-target (a need on a rejected or completed plan), superseded-open (an open plan superseded by an open plan), superseded-next-action (a superseded plan still has a next action), annotations-invalid, annotations-on-remote, settings-invalid, settings-unknown-key, settings-unknown-scope. Findings only. Nothing is repaired.
- Prune records (
plan prune, a later slice) are not consulted yet. A ref to a pruned plan is reported as dangling. readyand supersede detection only see refs stored in the selected scopes. Use--allto include refs from every scope.- The deadline rule is lexical. It can pick a cued date that is not a deadline, for example "data until 2026-11-15".