@uniqbit/mate-core 0.15.4-canary.8 → 0.15.4

package/src/opencode/companion-hooks.ts

@@ -179,15 +179,12 @@ function detectCommandArchive(input: unknown, output: unknown): string | null {
 
 function detectNewlyArchivedChanges(archiveDir: string, snapshot: Set<string>): string[] {
   const current = readArchiveEntries(archiveDir);
-  const newlyArchived = [...current].filter((entry) => !snapshot.has(entry)).toSorted();
-  snapshot.clear();
-  for (const entry of current) snapshot.add(entry);
-  return newlyArchived;
+  return [...current].filter((entry) => !snapshot.has(entry)).toSorted();
 }
 
 function appendOpenSpecFinishNudge(
   context: CompanionContext,
-  archiveSnapshot: Set<string>,
+  archiveSnapshot: Set<string> | undefined,
   nudgedCommandChanges: Set<string>,
   input: { tool?: unknown },
   output: { output?: string },
@@ -196,8 +193,10 @@ function appendOpenSpecFinishNudge(
 
   const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
   const changes: string[] = [];
-  for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
-    changes.push(entry.slice("YYYY-MM-DD-".length));
+  if (archiveSnapshot) {
+    for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
+      changes.push(entry.slice("YYYY-MM-DD-".length));
+    }
   }
   const commandChange =
     String(input.tool ?? "").toLowerCase() === "bash" ? detectCommandArchive(input, output) : null;
@@ -313,22 +312,36 @@ async function runReactDoctorScan(
 }
 
 type PluginEventInput = Parameters<NonNullable<Hooks["event"]>>[0];
+type ToolBeforeInput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[0];
+type ToolBeforeOutput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[1];
 type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
 type ToolAfterOutput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[1];
 
+interface ArchiveCallSnapshot {
+  sessionID: string;
+  entries: Set<string>;
+}
+
 export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
   const { client, $ } = pluginInput;
   const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
   if (!context.companionPath || !context.repositoryPath) return {};
 
   const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
-  const archiveSnapshot = readArchiveEntries(archiveDir);
+  const archiveCallSnapshots = new Map<string, ArchiveCallSnapshot>();
   const nudgedCommandChanges = new Set<string>();
   const dirtyReactDoctorSessions = new Set<string>();
   const reactDoctorScansInFlight = new Set<string>();
 
   return {
     event: async ({ event }: PluginEventInput) => {
+      if (event.type === "session.deleted") {
+        const sessionID = event.properties.info.id;
+        for (const [callID, snapshot] of archiveCallSnapshots) {
+          if (snapshot.sessionID === sessionID) archiveCallSnapshots.delete(callID);
+        }
+        return;
+      }
       if (event.type !== "session.idle") return;
       const sessionID = event.properties.sessionID;
       if (
@@ -340,10 +353,7 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
       }
       await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
     },
-    "tool.execute.before": async (
-      input: { tool: unknown },
-      output: { args: { filePath?: unknown; patchText?: unknown } | undefined },
-    ) => {
+    "tool.execute.before": async (input: ToolBeforeInput, output: ToolBeforeOutput) => {
       const toolName = String(input.tool ?? "");
       const args = output.args ?? {};
       if (["write", "edit"].includes(toolName)) {
@@ -359,13 +369,24 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
           }
         }
       }
+      if (context.gitAutoModeEnabled) {
+        archiveCallSnapshots.set(input.callID, {
+          sessionID: input.sessionID,
+          entries: readArchiveEntries(archiveDir),
+        });
+      }
     },
     "tool.execute.after": async (input: ToolAfterInput, output: ToolAfterOutput) => {
       if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
         dirtyReactDoctorSessions.add(input.sessionID);
       }
+      const archiveSnapshot = archiveCallSnapshots.get(input.callID)?.entries;
+      archiveCallSnapshots.delete(input.callID);
       appendOpenSpecFinishNudge(context, archiveSnapshot, nudgedCommandChanges, input, output);
     },
+    dispose: async () => {
+      archiveCallSnapshots.clear();
+    },
   };
 };
 

package/src/playbooks/companion-guidance.ts

@@ -103,7 +103,7 @@ export function buildCompanionPolicyXml(
 
   if (hasOpenspecCapability(context.capabilities)) {
     lines.push(
-      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes ONLY with: ${FRAMEWORK_NAME} artifact finish "<name>" --json — never hand-commit or hand-tag a finish. Finishing a still-active change applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
+      `    <rule id="openspec-finish" severity="critical">Finish OpenSpec changes by archiving them: the archive triggers a nudge directing you to run ${FRAMEWORK_NAME} artifact finish "<name>" --json — if no nudge arrives, invoke that command yourself. It is the only sanctioned completion; never hand-commit or hand-tag a finish. Finishing a still-active change archives it and applies its delta specs itself, so do not pre-apply them to openspec/specs right before finishing. Finishing an already-archived change resumes without re-applying delta specs, so an archive flow that already synced specs (e.g. openspec-sync-specs) composes fine with a finish afterwards.</rule>`,
     );
   }
 

package/src/templates/capabilities/openspec-cap/mate-skills/agents/mate-openspec-backfill/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: mate-openspec-backfill
+description: Reverse-engineer an OpenSpec spec for one existing feature and emit a ready-to-finish backfill change. Use when the user wants to backfill, document, or spec existing or legacy behavior that has no spec yet.
+allowed-tools: Bash(openspec:*), Bash(mate:*)
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+Create a spec for one feature that already exists in the working repository. The run ends with a standard ready-to-finish change — it never edits main specs and never finishes.
+
+## Scope rules
+
+- **One named feature per run.** Refuse Area-wide or repository-wide sweeps; ask the user to name a single feature and run the skill once per feature.
+- **Interactive by design.** Every ambiguity and every suspected bug becomes a user question. Do not run this skill unattended.
+
+## Steps
+
+1. **Scope.** Map the named feature to code: entry points, callees, tests. Use whatever exploration tooling this project has enabled (code-graph or index tools when present, otherwise search and targeted reading) — assume no specific capability is installed. Then check `openspec/specs/` for an existing capability covering this domain — prefer extending it (`MODIFIED`/`ADDED` deltas) over minting a new capability id.
+
+2. **Sweep.** Extract candidate behaviors and tag each finding:
+   - `[test-backed]` — an existing test verifies it (strongest; scenarios translate almost directly from tests)
+   - `[code-only]` — observable in code but untested
+   - `[inferred]` — assumed intent without direct evidence
+
+   Every candidate requirement needs at least one citation: a test name or `file:line`. Docs and comments corroborate but never stand alone. `[inferred]` findings are not requirements — they become questions for step 3.
+
+3. **Ask.** Batch the open questions to the user:
+   - Behavior that looks unintended → the user rules **spec the actual behavior** or **spec the intent** (with a follow-up fix change). Suspected bugs never silently become requirements.
+   - `[inferred]` findings → confirm, demote to out-of-scope, or convert to a question the emitted proposal records as open.
+
+4. **Emit.** Create the change and build its artifacts in dependency order:
+
+   ```bash
+   openspec new change "backfill-spec-<capability>"
+   openspec status --change "backfill-spec-<capability>" --json
+   openspec instructions <artifact-id> --change "backfill-spec-<capability>" --json
+   ```
+
+   The artifact set comes from the active schema (`schemaName` in the status JSON) — never assume a fixed artifact list. Follow each artifact's returned instructions and template, and state the active schema in the proposal so reviewers know which workflow produced the change. Map the backfill roles onto whatever artifacts the schema defines:
+
+   | Backfill role                                                                                  | Typical artifact (mate-v1 example) |
+   | ---------------------------------------------------------------------------------------------- | ---------------------------------- |
+   | Scope decisions and rulings from step 3                                                        | explore-brief.md                   |
+   | "Documents existing behavior, no code changes" + open questions                                | proposal.md                        |
+   | `ADDED`/`MODIFIED` requirements, behavior only, one citation each                              | specs/                             |
+   | As-built evidence dossier: entry points, test inventory, `file:line` citations per requirement | design.md                          |
+   | Verification checklist: one task per requirement, "confirm behavior at <citation>"             | tasks.md                           |
+
+   The verification task artifact MUST open with this rule, verbatim, so the applying agent sees it without knowing this skill: "These are verification tasks for a docs-only backfill change. If a requirement fails verification, update the delta spec (reword, drop, or re-cite the requirement) — never modify code in this change. A real bug found here becomes a separate fix change."
+
+   Requirements state observable contracts, never implementation detail ("propagates the child exit code", not "uses spawnSync").
+
+5. **Stop.** Report the change as ready-to-finish and hand off:
+   - Verify: `openspec-apply-change` works through tasks.md, checking each requirement against the code.
+   - Finish: `mate-artifact-finish` applies the deltas to main specs and anchors the change.
+
+## Guardrails
+
+- Never write files under `openspec/specs/` — main specs change only through finished changes.
+- Never invoke any finish flow (`mate artifact finish`, `openspec archive`); stop at ready-to-finish.
+- Never emit a requirement without a citation, and never spec a suspected bug without the user's ruling.
+- Keep capability ids opaque kebab-case; extend existing capabilities before creating new ones.

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

@@ -273,4 +273,5 @@ apply:
   instruction: |
     Read context files and work through pending tasks only within the proposal's affected Areas. Mark complete as you go.
     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.
     Pause if you hit blockers or need clarification.

package/src/templates/root/TEMPLATE_AGENTS.md

@@ -9,7 +9,9 @@ This block is kept for AGENTS.md compatibility and must not restate that policy.
 
 - 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.
 - 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.
 
 <!-- MATE:COMPANION:END -->

package/src/templates/root/TEMPLATE_CLAUDE.md

@@ -9,9 +9,11 @@ This block is kept for Claude/AGENTS.md compatibility and must not restate that
 
 - 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.
 
 <!-- MATE:COMPANION:END -->