@uniqbit/mate-core 0.15.4 → 0.15.5-canary.1

package/src/lib/orchestrator/yaml-file-store.ts

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 
@@ -22,8 +23,16 @@ export abstract class YamlFileStore<T> {
     }
   }
 
+  /** Writes via a sibling temp file + `fs.rename()` so a process killed mid-write cannot leave a truncated/corrupt file. */
   async save(data: T): Promise<void> {
     await fs.mkdir(path.dirname(this.configPath), { recursive: true });
-    await fs.writeFile(this.configPath, stringify(data), "utf8");
+    const tempPath = `${this.configPath}.${crypto.randomUUID()}.tmp`;
+    try {
+      await fs.writeFile(tempPath, stringify(data), "utf8");
+      await fs.rename(tempPath, this.configPath);
+    } catch (error) {
+      await fs.rm(tempPath, { force: true }).catch(() => {});
+      throw error;
+    }
   }
 }

package/src/templates/capabilities/openspec-cap/mate-v1/schema.yaml

@@ -1,5 +1,5 @@
 name: mate-v1
-version: 3
+version: 6
 description: Mate's repository- and Area-scoped OpenSpec workflow - explore → proposal → specs → design → tasks
 artifacts:
   - id: explore
@@ -46,7 +46,9 @@ artifacts:
        - Scopes are recorded ONLY in the frontmatter `scopes` list — do not add a `## Scopes` body section. Every change MUST name at least one scope.
        - Every `scopes` entry MUST pair `repository: org/repository` with an `area` selected according to the repository layout: the owning workspace/package root in a monorepo — the directory containing that package's manifest (`package.json`, `Cargo.toml`, `go.mod`, etc.) nearest the affected path (for example, `acme`, `apps/storefront`, or `packages/ui`, not `acme/src/sub-1/sub-2` or `apps/storefront/src/features/checkout`), or the exact affected path in a non-monorepo repository (for example, `docs`); use `.` only when the repository root itself is affected.
        - Repository identity MUST come from the Git remote. Normalize SSH and HTTPS forms such as `git@github.com:org/repository.git` and `https://github.com/org/repository.git` to `org/repository`.
-       - Area identity is metadata, never part of a change or capability folder name.
+       - Default a new capability to one package root: prefer one capability per owning package root over a single capability spanning several Areas.
+       - A change MAY declare scopes in several repositories, but each capability spec names exactly one. When a change spans repositories, list one capability per repository under Capabilities.
+       - Area identity is metadata: scope is read only from the frontmatter `scopes`, never from a change or capability folder name, though a descriptive name aligned with its package root is permitted.
        - Do not use a local checkout directory basename, Mate's internal repository ID, a synthetic Area token, or `N/A` as durable metadata.
 
       **Obsidian**: Emit this YAML frontmatter at the very top of the file. Replace `<change-name>` with the actual change folder name (e.g. `my-change`):
@@ -85,14 +87,14 @@ artifacts:
        **Path and scope rules** — spec files are ALWAYS flat; paired scope metadata is required, never a folder:
       - Every spec lives at `specs/<capability>/spec.md`. Never interpose an Area folder. `specs/<area>/<capability>/spec.md` breaks the OpenSpec CLI: it parses spec deltas only at the flat path, so an Area folder makes `openspec show`/`validate` report zero deltas.
        - Every delta and canonical spec MUST record a `scopes` frontmatter list whose entries pair `repository: org/repository` with an `area` selected according to the repository layout. Monorepo Areas stop at workspace/package roots such as `acme`, `apps/storefront`, or `packages/ui` — the directory containing that package's manifest (`package.json`, `Cargo.toml`, `go.mod`, etc.) nearest the affected path; non-monorepo Areas remain exact paths such as `docs` or `.`.
-       - Each scope pair is independent. Preserve every repository/Area pair for monorepos and multiple repositories; never use separate parallel `repositories` and `areas` arrays.
-       - Example paired scopes: `{ repository: org/product, area: acme }`, `{ repository: org/product, area: apps/storefront }`, `{ repository: org/product, area: packages/api }`, and `{ repository: org/other, area: docs }`.
+       - Each scope pair is independent. Preserve every repository/Area pair; never use separate parallel `repositories` and `areas` arrays.
+       - Example paired scopes for one spec: `{ repository: org/product, area: acme }`, `{ repository: org/product, area: apps/storefront }`, and `{ repository: org/product, area: packages/api }` — same repository throughout. A capability in `org/other` is its own spec.
        - Do not split a monorepo Area into deeper entries such as `acme/src`, `acme/public`, or `apps/storefront/src/features/checkout`; those paths remain inside the `acme` Area (or `apps/storefront`, `packages/ui`, etc.) regardless of how many source subfolders the change touches. A non-monorepo repository may use exact subpaths such as `docs` to identify the affected Area.
-       - Scopes cascade: every requirement inherits all frontmatter `scopes` entries by default and needs no inline markers.
-       - Add a direct `**Area:**` marker to a requirement ONLY when its effective scope is narrower than the document scopes. The marker may list multiple Areas as backtick-quoted, comma-separated values (for example, `**Area:** \`acme\`, \`packages/api\``), and every listed Area MUST appear in the frontmatter `scopes`.
-       - Add a direct `**Repository:**` marker ONLY when the spec's frontmatter names more than one repository and the requirement binds fewer of them; every listed value MUST appear in the frontmatter `scopes`. In a single-repository spec, requirement-level `**Repository:**` markers are forbidden — the frontmatter already says it.
-       - Prefer single-repository specs: a cross-repo feature SHOULD use one capability spec per repository, with shared contracts in a capability owned by one repository. A deliberately multi-repository spec MUST label every requirement that does not bind all listed repositories with a `**Repository:**` marker.
-       - Capability names are opaque, kebab-case labels with no scope semantics: repository and Area meaning comes ONLY from the frontmatter `scopes`, never from the capability name. Names are unique per OpenSpec root (`specs/<capability>/spec.md` is flat); when two linked repositories would want the same name, choose distinct descriptive names rather than encoding a repository or Area into the name. State each repository's own observable obligation as its own requirement, and put shared contracts in a capability owned by one repository.
+       - Default a new capability to a single scope entry for the owning package root. When a change affects two package roots, write two capability specs rather than one spec with two Areas; reserve multi-Area specs for behavior genuinely shared across those roots.
+       - EVERY requirement MUST carry an `**Area:**` marker naming the Areas it binds — in every spec, including a spec whose frontmatter names only one Area and a requirement that binds all of them. The marker may list several as backtick-quoted, comma-separated values (for example, `**Area:** \`acme\`, \`packages/api\``), and every listed Area MUST appear in the frontmatter `scopes`.
+       - Mark unconditionally, never by cascade: a requirement's Area is then readable without consulting the frontmatter, it survives archive creating a new main spec (which discards frontmatter but copies requirement blocks verbatim), and a spec that later gains an Area needs no edit to its existing requirements.
+       - A spec MUST name exactly one repository: every `scopes` entry in one spec repeats the same `repository`, and requirement-level `**Repository:**` markers do not exist in this model. Cross-repository work is specified as one capability per repository, with shared contracts in a capability owned by one of them. A change's proposal MAY still declare scopes in several repositories — this rule binds each spec, not the change.
+       - Capability names are unique per OpenSpec root (`specs/<capability>/spec.md` is flat) and carry no authority over scope: repository and Area are read ONLY from the frontmatter `scopes`, never from the capability name. A descriptive name aligned with its package root is permitted where it aids uniqueness.
        - Do not use a local checkout directory basename, Mate's internal repository ID, a synthetic Area token, or `N/A`.
       - Modified capabilities: match the existing `specs/<capability>/spec.md` path exactly.
 
@@ -105,11 +107,13 @@ artifacts:
       Format requirements:
       - Each requirement: `### Requirement: <name>` followed by description
       - Use SHALL/MUST for normative requirements (avoid should/may)
-       - Narrowing markers, when needed, go after the requirement's SHALL/MUST statement and before its first scenario — `**Repository:**` first, then `**Area:**`. For a REMOVED requirement without a normative statement, put them after `**Migration**`.
+       - An `**Area:**` marker, when required, goes after the requirement's SHALL/MUST statement and before its first scenario. For a REMOVED requirement without a normative statement, put it after `**Migration**`.
       - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
       - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
       - Every requirement MUST have at least one scenario.
 
+      New capabilities only: after the frontmatter and backlink lines, start the delta spec body with a `## Purpose` section - one or two sentences (50+ characters, or `openspec validate --strict` reports it as too brief) describing what the capability is for. Archive copies it into the main spec it creates; without it the new main spec is left with a `TBD ... Update Purpose after archive.` placeholder to fill in by hand. Do NOT add `## Purpose` to a delta for an existing capability - that spec already has one and the delta's is ignored. To change an existing capability's Purpose - including a leftover `TBD` placeholder - edit `openspec/specs/<capability>/spec.md` directly.
+
       MODIFIED requirements workflow:
       1. Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
       2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
@@ -118,13 +122,14 @@ artifacts:
 
       Common pitfall: Using MODIFIED with partial content loses detail at archive time. If adding new concerns without changing existing behavior, use ADDED instead.
 
-      Example (frontmatter scopes cover `acme` and `packages/api`; the first requirement inherits both, the second narrows to one):
+      Example (frontmatter scopes cover `acme` and `packages/api`; every requirement carries an `**Area:**` marker, as always — the first binds both, the second one):
 
       ```
       ## ADDED Requirements
 
       ### Requirement: User can export data
       The system SHALL allow users to export their data in CSV format.
+      **Area:** `acme`, `packages/api`
 
       #### Scenario: Successful export
       - **WHEN** user clicks "Export" button
@@ -156,12 +161,33 @@ artifacts:
 
       After the file's `#` title line, add a backlink on the next line: `← [[proposal]]`. If modifying an existing main spec, add on the line after: `Applies to: [[openspec/specs/<capability>/spec]]`.
 
+       **Canonical spec frontmatter** — a DIFFERENT block, used ONLY by canonical specs at `openspec/specs/<capability>/spec.md`. A canonical spec uses flat scalars, never a nested `scopes` list:
+
+      ```
+      ---
+      type: spec
+      capability: <capability>
+      repository: org/repository
+      areas: [<area>, <area>]
+      tags: [openspec/spec]
+      ---
+      ```
+
+       Which block applies where: change artifacts — explore brief, proposal, delta spec, design, and tasks — keep paired `scopes`, because a change MAY declare scopes in several repositories. Canonical specs use the flat block above and MUST NOT carry a `scopes` key, because the one-repository-per-spec rule leaves no repository/Area pair to bind. Flat scalars are also the only shape Obsidian properties, property search, and Bases can filter or group; a list of mappings is an unsupported property type.
+
+       Projection from a delta spec to its canonical spec — both the agent-driven merge and any deterministic reconciliation MUST derive the canonical block this way, so the two agree:
+       1. Read the delta spec's `scopes` entries.
+       2. Assert every `repository` value is identical. If they differ, projection FAILS — never pick one and never emit a list; correct the delta by splitting it into one capability per repository.
+       3. Emit that repository as the scalar `repository`, and the distinct `area` values as `areas` in their original order.
+       4. Set `capability` from the spec's directory name and `tags` to `[openspec/spec]`. Delta-only keys — `change` and the delta tags `openspec/change`/`openspec/delta` — MUST NOT carry over.
+
        Migration rules for existing artifacts and canonical specs:
        1. Normalize each Area to the owning workspace/package root for monorepos — the directory containing that package's manifest (`package.json`, `Cargo.toml`, `go.mod`, etc.) nearest the affected path, e.g. collapse `apps/storefront/src/features/checkout` to `apps/storefront`; for non-monorepos, retain the exact affected repository-relative path and use `.` only when the repository root is the intended Area.
        2. Replace local, internal, synthetic, or otherwise non-portable repository and Area values with canonical Git remote identities and exact repository-relative paths.
-       3. Add mandatory paired `scopes` frontmatter to every delta and canonical spec that lacks it.
-       4. Remove requirement-level `**Repository:**` markers and any `**Area:**` marker that merely repeats the full document scope; keep or add `**Area:**` markers only where a requirement's effective scope is narrower than the frontmatter `scopes`.
-       5. Preserve paired scope metadata and narrowing Area markers when archiving, validating, displaying, or finishing artifacts.
+       3. Add mandatory scope frontmatter to every delta and canonical spec that lacks it — paired `scopes` on a delta spec, the flat `repository`/`areas` block on a canonical spec.
+       4. Remove every requirement-level `**Repository:**` marker; if a legacy spec names more than one repository, split it into one capability per repository. Add an `**Area:**` marker to every requirement that lacks one, including in a spec whose frontmatter names only one Area.
+       5. Preserve paired scope metadata and requirement-level Area markers when archiving, validating, displaying, or finishing artifacts.
+       6. Convert a canonical spec still carrying a nested `scopes` list to the flat block: collapse the repeated `repository` value to the scalar `repository`, list the distinct `area` values as `areas`, and delete the `scopes` key. Strip leaked delta-only keys — `change`, a flat legacy `area`, and the `openspec/change`/`openspec/delta` tags — and add `type: spec` and `capability` where missing. A canonical spec that predates this rule stays readable until converted; do not treat the legacy shape as a validation failure.
     requires:
       - proposal
   - id: design

package/src/templates/capabilities/openspec-cap/mate-v1/templates/spec.md

@@ -8,16 +8,19 @@ scopes:
     area: .
 ---
 
+## Purpose
+
+<!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->
+
 ## ADDED Requirements
 
 ### Requirement: <!-- requirement name -->
 
-<!-- requirement text. The requirement inherits every frontmatter `scopes` entry by default.
-Only when its effective scope is narrower, add marker lines here with values from the
-frontmatter scopes, e.g.:
-**Area:** `.`
-A **Repository:** marker is allowed only when the frontmatter names more than one
-repository and this requirement binds fewer of them. -->
+<!-- requirement text. EVERY requirement carries an **Area:** marker naming the Areas it
+binds, using values from the frontmatter scopes — always, even when there is only one
+Area. Put it on the line below, e.g.:
+**Area:** `packages/ui`
+Every scopes entry names the same repository, so no **Repository:** marker is ever used. -->
 
 #### Scenario: <!-- scenario name -->
 

package/src/templates/root/TEMPLATE_AGENTS.md

@@ -1,13 +1,5 @@
 <!-- MATE:COMPANION:START -->
 
-You are operating in a Mate-managed session.
-
-Canonical companion policy is injected through `<companion-policy framework="mate" priority="mandatory">`.
-This block is kept for AGENTS.md compatibility and must not restate that policy.
-
-## Agent Notes
-
-- Use absolute paths when a tool needs a file path. Do not create literal `$MATE_REPO_PATH` or `$MATE_ARTIFACT_PATH` directories.
 - When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc.
 - Code comments: JSDoc format only (`/** ... */`), never `//`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.

package/src/templates/root/TEMPLATE_CLAUDE.md

@@ -1,17 +1,7 @@
 <!-- MATE:COMPANION:START -->
 
-You are operating in a Mate-managed session.
-
-Canonical companion policy is injected through `<companion-policy framework="mate" priority="mandatory">`.
-This block is kept for Claude/AGENTS.md compatibility and must not restate that policy.
-
-## Claude Notes
-
-- Use absolute paths when a tool needs a file path. Do not create literal `$MATE_REPO_PATH` or `$MATE_ARTIFACT_PATH` directories.
 - When reporting information to me, be extremely concise and sacrifice grammar for the sake of concision. Apply this same preference to JSDoc.
 - Code comments: JSDoc format only (`/** ... */`), never `//`. Sparse — only non-obvious invariants or constraints, never restated artifact rationale.
-- Claude Code receives `$MATE_ARTIFACT_PATH` via `--add-dir`; if `@` autocomplete does not show companion artifacts, reference them by absolute path.
-- The root `CLAUDE.md` in the companion repo is intentional and loaded by Mate. Do not create another project-level `CLAUDE.md` in the working repo unless the user explicitly asks for one.
 - Never add a `Co-Authored-By: <model>` trailer or model-attribution footer to commit messages.
 - Never commit, push, or open a pull request in the working repo (`$MATE_REPO_PATH`) unless the user explicitly asks for it.
 - Never connect to a database (local or remote), touch live/external systems (deploys, infra), or take destructive/irreversible actions without asking the user first.