freeharness 0.4.1

package/canonical/hooks/hooks.cost-tracker.claude-code.json

@@ -0,0 +1,37 @@
+{
+  "$comment": "FreeHarness cost-tracker for Claude Code (cost capability). Merged additively into settings.json. Stop fires at the end of every assistant turn and SessionEnd when the session closes; each run appends a cumulative snapshot of the session's token usage + estimated USD (cost-prices.json, editable) to ~/.claude/freeharness/cost/usage.jsonl, then backfills any subagent dispatch missing from .freeharness/sdd/<change>/ledger.jsonl as a late: true line. SubagentStop appends one ledger line per finished dispatch instead of a usage.jsonl snapshot. The SessionEnd entry carries timeout 10: Claude Code gives SessionEnd hooks a shared 1.5 s budget by default and raises it to the highest per-hook timeout in a settings file. The SubagentStop entry carries the same timeout so the ledger read and write fit. Never blocks, never writes to stdout. Report: `freeharness cost report`.",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-cost-tracker.mjs\""
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-cost-tracker.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-cost-tracker.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/canonical/hooks/hooks.memory-guard.claude-code.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "FreeHarness PreToolUse memory guard for Claude Code. Merged additively into <project>/.claude/settings.json. Denies hand-written memory .md writes (the free-mem plugin owns memory; saves output tokens).",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-memory-guard.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/canonical/hooks/hooks.output-pruner.claude-code.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "FreeHarness output pruner for Claude Code (cost capability). Merged additively into settings.json. PostToolUse on Bash: when stdout exceeds --max-bytes (8 KB) or --max-lines (200), the full output is written to ~/.claude/freeharness/tool-output/<session>/<n>.txt and the model receives head + tail with `[freeharness: N lines pruned, full output at <path>]` markers via `updatedToolOutput` (the command is never rewritten, so permission rules and exit codes are untouched). Diff/patch previews pass through; pytest / node --test / vitest failure blocks stay whole; a {kind:\"pruned\"} line lands in the cost log for `freeharness cost report --sinks`. Disk copy failure = output passed through. Disable: FREEHARNESS_HOOK_OUTPUT_PRUNER=off or remove this entry.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-output-pruner.mjs\" --max-bytes 8192 --max-lines 200"
+          }
+        ]
+      }
+    ]
+  }
+}

package/canonical/hooks/hooks.precompact.claude-code.json

@@ -0,0 +1,15 @@
+{
+  "$comment": "FreeHarness PreCompact hook for Claude Code (rules capability; memory-independent). Merged additively into settings.json. Before /compact or auto-compaction it writes ~/.claude/freeharness/state/<session>.precompact.md (the eight-section checkpoint skeleton built from the transcript, identifiers verbatim) and <session>.fileops.json (Read/Edit/Write/MultiEdit/NotebookEdit list) for the SessionStart re-orientation, and asks a running memory worker to store a session summary (POST /api/sessions/summarize). Worker down = skipped; exit 0, no output. Disable: FREEHARNESS_HOOK_PRECOMPACT=off.",
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-precompact.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/canonical/hooks/hooks.repeat-tool.claude-code.json

@@ -0,0 +1,25 @@
+{
+  "$comment": "FreeHarness repeat-tool reminder for Claude Code (rules capability; rewritten from the dsh repeat-tool-reminder guard, MIT). Merged additively into settings.json. PreToolUse on every tool: hashes (tool, key-sorted input), keeps the run length in ~/.claude/freeharness/state/<session>.json, counts denied calls, and returns an additionalContext reminder at --thresholds 3,5,8 consecutive identical calls (short at 3, detailed with a --preview-chars 500 argument preview at 5 and 8). Advisory only, never blocks. UserPromptSubmit runs the same script to reset the chain. Thresholds are validated at load (integers >= 2, ascending); an invalid list falls back to the defaults with a stderr line. Disable: FREEHARNESS_HOOK_REPEAT_TOOL=off or remove both entries.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-repeat-tool.mjs\" --thresholds 3,5,8 --preview-chars 500"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-repeat-tool.mjs\" --thresholds 3,5,8 --preview-chars 500"
+          }
+        ]
+      }
+    ]
+  }
+}

package/canonical/hooks/hooks.security-guidance.claude-code.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "FreeHarness PreToolUse security guidance for Claude Code (safety capability). Merged additively into settings.json. Warns (additionalContext, never blocks) when an Edit/Write introduces a known vulnerability sink: shell exec, eval, DOM XSS, unsafe deserialization, SQL string building, path traversal, hardcoded secrets, TLS off, weak crypto, Actions script injection, untrusted text in prompts, model output reaching an execution sink.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-security-guidance.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/canonical/mcp/servers.json

@@ -0,0 +1,20 @@
+{
+  "$comment": "Neutral MCP server list. Each adapter registers its own way (claude mcp add, OpenCode config); targets says where to apply.",
+  "servers": [
+    {
+      "name": "context7",
+      "description": "Up-to-date library/framework docs (avoids hallucinated APIs).",
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ],
+      "targets": [
+        "claude-code",
+        "opencode"
+      ],
+      "optional": false
+    }
+  ]
+}

package/canonical/openspec/config.base.yaml

@@ -0,0 +1,89 @@
+# OpenSpec project config — base for the FreeHarness spec-driven override.
+# Optional: copy to <project>/openspec/config.yaml only to add project-specific
+# context. The house rules already travel with the schema, so this file is not
+# required. `context` is injected into every artifact; `rules` only for the
+# matching artifact id.
+
+schema: spec-driven
+
+context: |
+  Engineering profile: Software / AI / Data Engineering.
+  Stack: Python 3.11+, FastAPI, LangGraph, multi-agent systems, RAG pipelines,
+  PostgreSQL + pgvector, SQLite, Oracle (OCI), Docker. Pydantic v2 for models
+  and settings (BaseModel with extra="forbid"; BaseSettings only for secrets).
+
+  Conventions:
+  - PEP 8, full type hints, prefer editing existing files over new ones.
+  - Structured logging of agent decisions and RAG retrieval; no print() in
+    production code.
+  - Specs are the source of truth; code is a byproduct. Anti-over-specification:
+    define the WHAT, the WHY, and the architectural limits of the HOW. Do not
+    write final application code or exhaustive pseudo-code in artifacts.
+  - INVEST: thin, vertical, independent slices to avoid context overload.
+  - Always anticipate edge cases and failure modes explicitly.
+
+  AI Safety:
+  - Sanitize inputs against prompt injection.
+  - Version models and prompts; record eval thresholds.
+
+  Research discipline:
+  - Never hallucinate API signatures for fast-moving frameworks (LangGraph,
+    pgvector, OCI SDKs). Verify against current docs (Context7 / Gemini MCP)
+    before specifying exact APIs.
+
+  Formatting of generated artifacts:
+  - Do not use bold markdown markers. Use headers, lists, and code blocks only.
+  - LLM-to-LLM tone: no conversational filler.
+
+rules:
+  proposal:
+    - State Intent (WHY) in 1-2 sentences and What Changes as a specific list.
+    - Scope MUST list in-scope, out-of-scope, and explicit non-goals.
+    - Include a Boundaries section with three tiers - Always do (mandatory
+      structural/security actions), Ask first (pause for human confirmation),
+      Never do (absolute prohibitions, anti-patterns, libraries to avoid).
+    - Keep implementation detail out; it belongs in design.
+
+  specs:
+    - Use delta sections - ADDED / MODIFIED / REMOVED Requirements.
+    - Requirement headers use "### Requirement:"; scenarios use exactly four
+      hashtags "#### Scenario:" with GIVEN/WHEN/THEN. Every requirement has at
+      least one scenario.
+    - Use RFC 2119 keywords SHALL/MUST for normative behavior; avoid should/may
+      for acceptance.
+    - Acceptance criteria MUST be binary (Pass/Fail) and translatable to an
+      automated test.
+    - Default to a lite spec; expand only for high-risk changes (contract/API
+      changes, migrations, security/privacy).
+
+  design:
+    - Record architecture decisions ADR-style - decision plus rationale plus
+      alternatives rejected.
+    - Define data models (Pydantic v2 / TypedDict), state and persistence
+      (PostgreSQL/pgvector, SQLite, Oracle/OCI), integrations, and data flow.
+    - Enumerate edge cases and failure modes explicitly with the expected
+      handling.
+
+  eval-plan:
+    - Define evaluation datasets and the metric thresholds as binary gates
+      (e.g. WER <= target, cosine >= target, exact-match, latency budget).
+    - Specify grader type (exact / semantic / LLM-judge) and pass@k where
+      relevant.
+    - Define regression gates and where results are logged/observed.
+
+  data-contract:
+    - Specify source and sink schemas, field types, and nullability.
+    - State idempotency and atomicity guarantees, partitioning, and lineage.
+    - Define SLAs and the behavior on contract violation (reject / quarantine).
+
+  tasks:
+    - Tasks MUST be atomic and INVEST-sliced; hierarchical numbering (1, 1.1)
+      under headings, with checkboxes.
+    - Each task MUST name its verification step (e.g. pytest target, mypy,
+      output validation).
+
+operations:
+  archive:
+    guidance:
+      - "Compound step: one dogfood line in .freeharness/dogfood.md (the evidence log; committed), a rules or skill delta when a correction repeated during the change, and one memory observation with the change id and the verbatim identifiers. No new agent or skill."
+

package/canonical/openspec/schema.spec-driven.yaml

@@ -0,0 +1,277 @@
+# Override bundle: install this as the user-global "spec-driven" schema so that
+# `openspec init` (which always defaults to spec-driven) resolves to THIS content
+# in every project, with no per-project config copy required.
+#
+# Install: copy this file as schema.yaml plus the templates/ dir into
+#   ${XDG_DATA_HOME:-$HOME/.local/share}/openspec/schemas/spec-driven/
+#
+# House rules (stack, formatting, AI safety) are embedded in each artifact's
+# instruction so they travel globally with the schema. openspec/config.yaml stays
+# OPTIONAL — use it only to add project-specific context on top.
+
+name: spec-driven
+version: 1
+description: >
+  Spec-driven workflow for Software / AI / Data Engineering (override of the
+  built-in spec-driven). Hybrid of the SDD format (SPECIFY / BOUNDARIES / PLAN /
+  ATOMIC TASKS) with OpenSpec delta specs, archive, and relevance-gated eval-plan
+  and data-contract artifacts. Stack: Python, FastAPI, LangGraph,
+  PostgreSQL/pgvector, SQLite, Oracle (OCI), multi-agent systems, RAG pipelines.
+
+# Repeated at the top of every artifact instruction (one artifact is generated at
+# a time, so the rules must live in each instruction to be reliably present).
+# Keep edits here in sync across artifacts.
+#
+# Constitution (Spec Kit's term for the project's non-negotiable principles) is
+# the project CLAUDE.md invariants block. It is referenced from the instructions
+# below, never duplicated here: one source, read by every artifact.
+#
+# V4-P4 ports from OpenSpec 1.12 (e062b957, MIT): inspect-before-drafting (#1737)
+# in proposal and design; per-task verification (#1660) in tasks. FreeHarness
+# additions: supersession check, Consequences (cost and bought), EARS scenarios,
+# Global Constraints and per-task annotation lines, scope/depth dial.
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    template: proposal.md
+    description: >
+      Intent (WHY), Scope (in / out / non-goals), Approach, and Boundaries
+      (Always do / Ask first / Never do). Maps the legacy SPECIFY + BOUNDARIES.
+    instruction: |
+      House rules (apply to every artifact): Specs are the source of truth; code
+      is a byproduct. Anti-over-specification - define the WHAT, the WHY, and the
+      architectural limits of the HOW; do not write final application code or
+      exhaustive pseudo-code. INVEST: thin, vertical, independent slices.
+      Anticipate edge cases and failure modes explicitly. Formatting: no bold
+      markdown markers - use headers, lists, and code blocks only; LLM-to-LLM
+      tone, no conversational filler. Stack: Python 3.11+, FastAPI, LangGraph,
+      Pydantic v2 (BaseModel extra="forbid"; BaseSettings only for secrets),
+      PostgreSQL+pgvector, SQLite, Oracle (OCI). Never hallucinate API signatures
+      for fast-moving frameworks - verify against current docs (Context7 / Gemini
+      MCP). AI safety: sanitize inputs against prompt injection; version models
+      and prompts.
+
+      Inspect the relevant project before drafting: read the project CLAUDE.md
+      (its invariants block is the constitution this change must respect - do
+      not restate it, cite it), openspec/specs and the closest similar feature,
+      then the relevant implementation, nearby tests, configuration and
+      documentation outside openspec/. Keep the inspection read-only and
+      proportional to the change; reuse the findings for later artifacts.
+      Ground scope, approach and tasks in what you find; distinguish observed
+      behavior from assumptions and proposed additions; surface conflicts with
+      existing specs instead of silently deciding which is correct. Do this
+      discovery now rather than leaving generic "explore the codebase" tasks.
+
+      Supersession check, before writing: search openspec/specs and
+      openspec/changes/archive for an existing decision or mechanism on the
+      same subject. When one exists, this change supersedes it explicitly and
+      cross-links both ways: the design names the superseded change in a
+      `Supersedes: <change-id>` line, and the archived record keeps its text.
+      Never edit a published decision in place into a different decision; a
+      partially superseded decision stays active and cross-linked.
+
+      Follow-ups: run `openspec follow-up list` before drafting and name every
+      item this change claims (`openspec follow-up claim <change-id> <index>
+      --by <this change>`); declare `depends_on` and `supersedes` in the
+      change's `.openspec.yaml` when the change waits on or replaces another.
+
+      This artifact: capture WHY this change is needed and WHAT changes at a high
+      level. Set the scope/depth dial line (lite: default, thin artifacts;
+      expanded: high-risk changes - contracts, migrations, security, privacy -
+      get full specs, design and data-contract). Define Scope with in-scope,
+      out-of-scope, and explicit non-goals.
+      Include a Boundaries section with three tiers - Always do (mandatory
+      structural/security actions), Ask first (scenarios where you must pause for
+      human confirmation), Never do (absolute prohibitions, anti-patterns,
+      libraries to avoid).
+
+      Research existing specs before listing Capabilities: run
+      `openspec list --specs` for the project's capability inventory, then
+      `openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
+      look related - that returns a capability's purpose and requirement texts
+      without pulling whole spec files into context. Keep `--type spec`: a
+      change and a spec sharing a name is otherwise an ambiguous-item error.
+      `openspec list` without `--specs` lists in-flight changes, not specs - it
+      never shows what the project already covers. Reuse an existing
+      capability's exact path instead of introducing a near-duplicate name.
+      The filtered read is only an overview. Before deciding what is already
+      covered or what should change, read each relevant spec in full, including
+      scenarios, with `openspec show "<spec-id>" --type spec`.
+
+      List Capabilities (new and modified) - each new one
+      becomes specs/<name>/spec.md. Keep implementation detail out of the proposal.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    template: spec.md
+    description: >
+      Behavior contract as delta specs (ADDED / MODIFIED / REMOVED) with RFC 2119
+      requirements and GIVEN/WHEN/THEN scenarios. Binary acceptance criteria.
+    instruction: |
+      House rules (apply to every artifact): Specs are the source of truth.
+      Anti-over-specification. INVEST slices. Anticipate edge cases. No bold
+      markdown - headers/lists/code only; LLM-to-LLM tone, no filler. Never
+      hallucinate API signatures - verify via Context7 / Gemini MCP. AI safety:
+      sanitize prompt injection; version models and prompts.
+
+      This artifact: write behavior-first requirements. One spec file per
+      capability from the proposal. For a modified capability, use the exact
+      existing path from openspec/specs/<capability-path>/ when creating the
+      delta - run `openspec list --specs` to confirm that path before writing
+      the delta: a mistyped or invented path targets a capability that does
+      not exist rather than the one you meant. Do not move or rename the
+      capability. Use delta sections with "## " headers - ADDED
+      Requirements, MODIFIED Requirements (copy the ENTIRE requirement block and
+      edit; partial content loses detail at archive), REMOVED Requirements
+      (include Reason and Migration). Requirement header "### Requirement: <name>"
+      using SHALL/MUST (avoid should/may). Scenario header uses EXACTLY four
+      hashtags "#### Scenario: <name>" with GIVEN/WHEN/THEN bullets (3 hashtags or
+      bullets fail silently). The EARS form is accepted as an alternative:
+      "#### Scenario: WHEN <event> THE SYSTEM SHALL <behavior>" (also
+      WHILE/WHERE/IF), with the behavior in the header and an optional body;
+      GIVEN/WHEN/THEN stays the default. Every requirement has at least one
+      scenario.
+      Acceptance MUST be binary (Pass/Fail) and translatable to an automated test.
+      Default to a lite spec; expand only for high-risk changes (contract/API
+      changes, migrations, security/privacy). Keep implementation detail out.
+    requires: [proposal]
+
+  - id: design
+    generates: design.md
+    template: design.md
+    description: >
+      Technical approach: open questions resolved, candidate approaches compared
+      and one chosen, ADR-style decisions, file-level blueprint (files,
+      interfaces, data flow, test points), data models, state/persistence,
+      integrations, edge cases. Maps the legacy PLAN section.
+    instruction: |
+      House rules (apply to every artifact): Specs are the source of truth.
+      Anti-over-specification - architectural limits of the HOW, not final code.
+      INVEST slices. No bold markdown - headers/lists/code only; LLM-to-LLM tone.
+      Stack: Python 3.11+, FastAPI, LangGraph, Pydantic v2, PostgreSQL+pgvector,
+      SQLite, Oracle (OCI). Never hallucinate API signatures - verify via
+      Context7 / Gemini MCP. AI safety: sanitize prompt injection; version
+      models and prompts.
+
+      This artifact: before writing, list the underspecified points (edge
+      cases, error behavior, integration points, backward compatibility, scope
+      boundaries) and resolve them with the user; never bury an assumption in
+      the design. Inspect the relevant project before drafting: the project
+      CLAUDE.md invariants (the constitution), openspec/specs, the closest
+      similar feature, then implementation, tests, configuration and docs
+      outside openspec/ - read-only, proportional, findings reused from the
+      proposal. Ground the design in the existing codebase: name the
+      conventions and the closest similar feature with file:line citations
+      (dispatch explorer-ai-engineer-analyst for unknown or large areas).
+      Compare 2-3 candidate approaches (for example minimal change, clean
+      architecture, pragmatic balance) in a short table, pick one, and record
+      the rationale and the rejected alternatives. Document the key
+      architecture decisions ADR-style (decision + rationale + alternatives
+      rejected). Alternatives are recorded from what was actually considered,
+      never invented to fill the section; an empty alternatives line is
+      honest, a fabricated one is a defect. After Decisions, write a
+      "## Consequences (cost and bought)" section with one line per decision
+      stating what the decision costs and what it buys. When this change
+      supersedes a published decision (found by the proposal's supersession
+      check), add a `Supersedes: <change-id>` line (one or more archived
+      change ids, comma-separated) at the top of the design; archive prints
+      the link, writes the reverse link into the archived record, and refuses
+      a MODIFIED requirement that repeats the superseded text unchanged.
+      Then give a file-level blueprint: files to create or modify
+      with the concrete change per file, public interfaces (signatures) and
+      their dependencies respecting the dependency rule (infra -> core <-
+      entry), data flow naming the types at each hop, and the test points
+      (seams and the test cases that prove each slice; the slices become
+      tasks.md). Define data models (Pydantic v2 / TypedDict), state and
+      persistence (PostgreSQL/pgvector, SQLite, Oracle/OCI), and integrations.
+      Enumerate edge cases and failure modes explicitly with the expected
+      handling so the execution agent never has to guess. When the design
+      involves agent topology (agents, graphs, routing, tool boundaries),
+      apply the agentic-architecture skill and dispatch the agentic-architect
+      agent; fold its blueprint - pattern choice, context strategy,
+      reliability and observability plan - into this design.
+    requires: [proposal]
+
+  - id: eval-plan
+    generates: eval-plan.md
+    template: eval-plan.md
+    description: >
+      Evaluation plan for changes affecting LLM/model/RAG behavior. Datasets,
+      metric thresholds, grader, pass@k, regression gates, observability.
+    instruction: |
+      House rules (apply to every artifact): no bold markdown; LLM-to-LLM tone.
+      AI safety: sanitize prompt injection; version models and prompts. Never
+      hallucinate API signatures - verify via Context7 / Gemini MCP.
+
+      Create this artifact ONLY if the change affects LLM, model, agent, or RAG
+      behavior; otherwise skip it. Define evaluation datasets, metrics with binary
+      pass/fail thresholds (e.g. WER <= target, cosine >= target, exact-match,
+      latency budget), grader type (exact / semantic / LLM-judge), pass@k where
+      relevant, regression gates, and where results are logged/observed.
+    requires: [specs]
+
+  - id: data-contract
+    generates: data-contract.md
+    template: data-contract.md
+    description: >
+      Data interface contract for changes that create or alter a data interface.
+      Source/sink schemas, types, nullability, partitioning, lineage,
+      idempotency/atomicity, SLAs.
+    instruction: |
+      House rules (apply to every artifact): no bold markdown; LLM-to-LLM tone.
+      Stack persistence: PostgreSQL+pgvector, SQLite, Oracle (OCI). Anticipate
+      edge cases and failure modes explicitly.
+
+      Create this artifact ONLY if the change introduces or alters a data
+      interface (table, queue, file layout, API payload, external contract);
+      otherwise skip it. Specify source and sink schemas, field types and
+      nullability, partitioning, lineage, idempotency and atomicity guarantees
+      (e.g. tmp -> fsync -> os.replace), SLAs, and behavior on contract violation
+      (reject / quarantine / alert).
+    requires: [proposal]
+
+  - id: tasks
+    generates: tasks.md
+    template: tasks.md
+    description: >
+      Implementation checklist of atomic, INVEST-sliced tasks with hierarchical
+      numbering and a verification step per group. Maps the legacy ATOMIC TASKS.
+    instruction: |
+      House rules (apply to every artifact): Anti-over-specification. INVEST
+      slices. No bold markdown - headers/lists/code only; LLM-to-LLM tone.
+      Verify discipline: pytest, mypy, validate outputs.
+
+      This artifact: open with a Global Constraints block (the invariants from
+      the project CLAUDE.md that every task must respect, cited not copied,
+      plus the change-wide rules: write scopes, forbidden paths, required
+      gates). Then break the work into thin, vertical, independent tasks
+      (INVEST) small enough to implement and validate without losing context. Use
+      hierarchical numbering (1, 1.1, 1.2) grouped under headings, with
+      checkboxes. Each task MUST state how to verify completion (a test,
+      command, observable behavior, or delivered artifact): put the
+      verification in that task's checkbox description or in a `Verify:` line
+      directly under it; use a separate verification task only when it checks
+      broader integration spanning multiple tasks. Optional per-task lines,
+      indented under the checkbox and never checkboxes themselves:
+      `Verify: <test or command>`, `Interfaces: <signatures touched>`,
+      `Boundary: <write scope>`, `Depends: <task ids>`. The validator accepts
+      them without counting them as tasks; the converge hook reads `Verify:`.
+    requires: [specs, design]
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+
+# Archive operation guidance (advisory; printed by `openspec instructions archive`).
+# Compound step: the archive writes the change's learnings back into the harness so the
+# next change starts from them; it never creates a new agent or skill.
+archive:
+  guidance:
+    - "Compound step, before the specs fold: append the retrospective line to the change's proposal.md under `## Retrospective` (what worked | what wasted tokens | candidate eval case); the quantitative side is the project telemetry file `.freeharness/telemetry.jsonl` written by the cost tracker at session end, never typed by hand."
+    - "Compound step: when a correction repeated during the change (the same reviewer finding twice, the same user correction twice), write the rules or skill delta that prevents it (a line in the project CLAUDE.md, a checklist item in the owning skill, or an eval case under the skill's evals/cases.yaml); never a new agent or skill."
+    - "Compound step: record one memory observation naming the change id, the decision that mattered and the exact identifiers (paths, commands, error strings) a later session must find verbatim."
+    - "Supersession check: search openspec/specs and openspec/changes/archive for a decision on the same mechanism; when the design carries a `Supersedes: <change-id>` line, archive prints the link and writes `Superseded-by: <this change>` into the archived record; supersede and cross-link both ways, never edit a published decision in place; a partially superseded decision stays active and cross-linked."
+    - "Follow-ups: archive prints the change's unclaimed follow-ups; claim each one by a change or record it with `openspec follow-up add` before archiving; an unclaimed item never blocks."
+

package/canonical/openspec/templates/data-contract.md

@@ -0,0 +1,36 @@
+<!--
+Create this artifact ONLY if the change introduces or alters a data interface
+(table, queue, file layout, API payload, external contract). Otherwise skip it.
+-->
+
+## Scope
+
+<!-- Which data interface is created or changed, and who the producers/consumers are. -->
+
+## Source Schema
+
+<!-- Input schema: fields, types, nullability, units, example record. -->
+
+## Sink Schema
+
+<!-- Output schema: fields, types, nullability, units, example record. -->
+
+## Partitioning and Layout
+
+<!-- Partition keys, file/dir layout, naming, ordering guarantees. -->
+
+## Lineage
+
+<!-- Upstream sources and downstream consumers. How a record is traced end to end. -->
+
+## Idempotency and Atomicity
+
+<!-- Reprocessing semantics, dedup keys, atomic write guarantees (e.g. tmp -> fsync -> os.replace). -->
+
+## SLAs
+
+<!-- Freshness, throughput, availability targets. -->
+
+## Violation Handling
+
+<!-- Behavior on contract violation: reject, quarantine, alert. Exit/return semantics. -->

package/canonical/openspec/templates/design.md

@@ -0,0 +1,84 @@
+Supersedes: <!-- archived change id(s) this design replaces, comma-separated; delete the line when none. Found by the proposal's supersession check over openspec/specs and openspec/changes/archive. -->
+
+## Context
+
+<!-- Background and current state relevant to this change. Existing conventions and the closest similar feature, with file:line citations (explorer-ai-engineer-analyst for unknown or large areas). -->
+
+## Goals / Non-Goals
+
+Goals:
+<!-- What this design aims to achieve. -->
+
+Non-Goals:
+<!-- Explicitly out of scope for this design. -->
+
+## Open Questions Resolved
+
+<!-- Underspecified points (edge cases, error behavior, integration points, backward compatibility, scope) and the answer agreed with the user before writing. No assumption stays implicit. -->
+
+## Candidate Approaches
+
+<!-- 2-3 candidates grounded in existing codebase patterns (e.g. minimal change / clean architecture / pragmatic balance). One row each: approach, diff size, reuse, testability, risk. -->
+
+| Approach | Summary | Trade-offs |
+|---|---|---|
+| A | | |
+| B | | |
+
+Chosen: <!-- which one and why; rejected alternatives in one line each -->
+
+## Decisions
+
+<!-- ADR style. One block per significant decision. -->
+
+### Decision: <!-- title -->
+Decision: <!-- what was decided -->
+Rationale: <!-- why -->
+Alternatives rejected: <!-- only options that were actually considered, and why not; never invented to fill the line -->
+
+## Consequences (cost and bought)
+
+<!-- One line per decision: what it costs (complexity, tokens, coupling, a phase that cannot close) and what it buys. -->
+
+- <decision title>: costs <...>; buys <...>.
+
+## Blueprint
+
+<!-- File-level plan for the chosen approach. Dependencies point inward (infra -> core <- entry); a new port names its adapter. -->
+
+Files to create / modify:
+<!-- path -> concrete change per file -->
+
+Interfaces:
+<!-- public signatures per component and their dependencies -->
+
+Test points:
+<!-- seams (injectable dependency, pure function, fake adapter) and the test cases that prove each slice; slices become tasks.md -->
+
+## Data Models
+
+<!-- Pydantic v2 models / TypedDict / dataclasses. Names, fields, types, constraints (extra="forbid", etc.). -->
+
+## State and Persistence
+
+<!-- Where state lives and how: PostgreSQL/pgvector, SQLite, Oracle/OCI. Tables/collections, keys, indexes, checkpointing. -->
+
+## Integrations
+
+<!-- External services, APIs, queues, schedulers. Verify exact API signatures against current docs before fixing them here. -->
+
+## Data Flow
+
+<!-- End-to-end flow naming the types at each hop. ASCII diagram or ordered steps. Inputs, transforms, outputs. -->
+
+## Edge Cases and Failure Modes
+
+<!-- Enumerate abnormal conditions and the expected handling so the execution agent never has to guess. -->
+
+## Agent Topology
+
+<!-- Only when the design involves agents, graphs, routing, or tool boundaries: apply the agentic-architecture skill, dispatch agentic-architect, and fold its blueprint here (pattern, context strategy, reliability, observability). Otherwise delete this section. -->
+
+## Risks / Trade-offs
+
+<!-- Known risks, trade-offs, and mitigations. -->