@matteeh/osq 0.1.0 → 0.2.0

package/dist/watcher/verify.js

@@ -0,0 +1,156 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveScope } from '../core/run/scope.js';
+import { runVerificationCommand } from '../core/run/verification.js';
+import { asRecord } from '../harness/stream.js';
+import { appendHarnessEvent } from '../harness/types.js';
+/** Last first-class `text` event on the agent stream, or null when absent. */
+export async function extractFinalTextFromStream(specFolderPath, taskNumber) {
+    const eventFilePath = path.join(specFolderPath, '.run', 'events', `${taskNumber}.jsonl`);
+    let content = '';
+    try {
+        content = await fs.readFile(eventFilePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let finalText = null;
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const event = asRecord(parsed);
+        if (event?.type !== 'text')
+            continue;
+        const text = asRecord(event.data)?.text;
+        if (typeof text === 'string' && text.trim().length > 0) {
+            finalText = text;
+        }
+    }
+    return finalText?.trim() ? finalText : null;
+}
+/** Write a result file synthesized from the agent's final stream message. */
+export async function synthesizeResultFile(resultsDir, taskNumber, finalText) {
+    await fs.mkdir(resultsDir, { recursive: true });
+    const resultPath = path.join(resultsDir, `${taskNumber}.md`);
+    const body = finalText.endsWith('\n') ? finalText : `${finalText}\n`;
+    const content = [
+        '---',
+        'synthesized: true',
+        '---',
+        "<!-- Synthesized by the osq watcher from the agent's final stream message.",
+        '     The agent exited without writing a result file. -->',
+        '',
+        body,
+    ].join('\n');
+    await fs.writeFile(resultPath, content, 'utf8');
+    return resultPath;
+}
+const TEST_DIR_NAME = 'tests';
+function hashFileContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** Snapshot preexisting `tests/` files as path -> content hash. */
+export async function snapshotTestFiles(projectRoot) {
+    const snapshot = new Map();
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                const relative = path.relative(projectRoot, full).split(path.sep).join('/');
+                snapshot.set(relative, hashFileContent(await fs.readFile(full)));
+            }
+        }
+    };
+    await walk(path.join(projectRoot, TEST_DIR_NAME));
+    return snapshot;
+}
+/** Pre-spawn test gate: preexisting `tests/**` hashes plus resolved scope authorization. */
+export async function captureTestGate(projectRoot, scope, testsModify) {
+    const snapshot = await snapshotTestFiles(projectRoot);
+    const authorized = new Set();
+    for (const entry of await resolveScope(projectRoot, scope)) {
+        if (entry.absolutePath !== null)
+            authorized.add(entry.relativePath);
+    }
+    return { snapshot, testsModify, authorized };
+}
+/** Diagnostics for preexisting test files changed or deleted since `snapshot`. */
+export async function findUndeclaredTestChanges(projectRoot, snapshot, options) {
+    const changes = [];
+    for (const [relative, expectedHash] of snapshot) {
+        let state = null;
+        try {
+            const hash = hashFileContent(await fs.readFile(path.join(projectRoot, relative)));
+            if (hash !== expectedHash)
+                state = 'modified';
+        }
+        catch {
+            state = 'deleted';
+        }
+        const authorized = options?.testsModify === true && options.authorized.has(relative);
+        if (state === null || authorized)
+            continue;
+        changes.push(options ? `${relative} (${state}); authorizing scope: ${relative}` : `${relative} (${state})`);
+    }
+    return changes.sort();
+}
+/**
+ * Run the verify command through the shared core executor, then append exactly
+ * one `verify_ran` event. This is the single watcher verification entrypoint;
+ * every watcher gate delegates here so event emission stays on one path.
+ */
+export async function runVerificationGateResult(projectRoot, verifyCommand, verifyTimeoutSeconds, context) {
+    const result = await runVerificationCommand(projectRoot, verifyCommand, verifyTimeoutSeconds);
+    const error = result.timedOut
+        ? `Verify command timed out after ${verifyTimeoutSeconds}s`
+        : (result.error ??
+            (result.exitCode !== 0
+                ? result.output || `Process exited with code ${result.exitCode}`
+                : undefined));
+    if (context) {
+        await appendHarnessEvent(context.specFolderPath, context.taskNumber, {
+            type: 'verify_ran',
+            timestamp: new Date().toISOString(),
+            data: {
+                command: verifyCommand,
+                exitCode: result.exitCode,
+                duration: result.duration,
+                ...(result.output.trim() ? { output: result.output } : {}),
+                ...(context.extraData ? context.extraData(result) : {}),
+            },
+        });
+    }
+    return {
+        ...result,
+        passed: result.exitCode === 0 && !result.error,
+        ...(error ? { error } : {}),
+    };
+}
+/** Compatibility projection retaining the established `runVerificationGate` shape. */
+export async function runVerificationGate(projectRoot, verifyCommand, verifyTimeoutSeconds, context) {
+    const result = await runVerificationGateResult(projectRoot, verifyCommand, verifyTimeoutSeconds, context);
+    return {
+        passed: result.passed,
+        timedOut: result.timedOut,
+        ...(result.error ? { error: result.error } : {}),
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/watcher/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/watcher/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matteeh/osq",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Strict spec queue. Spec-driven development with two kinds of agent and a human gate between them.",
   "type": "module",
   "sideEffects": false,
@@ -16,11 +16,18 @@
     "osq": "dist/cli/bin.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "lint": "biome check src tests",
-    "format": "biome format --write src tests",
-    "test": "node --import tsx --test tests/**/*.test.ts",
-    "verify": "pnpm tsc --noEmit && pnpm test && pnpm lint",
+    "build": "pnpm build:ui && pnpm stage:ui && pnpm build:cli",
+    "build:cli": "tsc -p tsconfig.build.json",
+    "build:ui": "pnpm --filter @osq/ui build",
+    "stage:ui": "node scripts/stage-ui.mjs",
+    "clean:ui": "node scripts/stage-ui.mjs --clean",
+    "lint": "biome check src tests packages/ui/src",
+    "format": "biome format --write src tests packages/ui/src",
+    "test": "node --import tsx --test 'tests/**/*.test.ts' && TSX_TSCONFIG_PATH=packages/ui/tsconfig.runtime.json node --import tsx --test 'tests/**/*.test.tsx'",
+    "test:golden": "node --import tsx --test tests/golden-events.test.ts",
+    "typecheck:cli": "tsc --noEmit -p packages/ui/tsconfig.cli.json",
+    "typecheck:ui": "pnpm --filter @osq/ui typecheck",
+    "verify": "pnpm typecheck:cli && pnpm typecheck:ui && pnpm build && pnpm test && pnpm lint",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -31,7 +38,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
-    "@types/node": "^22.13.9",
+    "@fission-ai/openspec": "1.13.1",
+    "@types/node": "^24.13.6",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2"
   },
@@ -46,7 +54,7 @@
   "author": "Mathias",
   "license": "MIT",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -58,9 +66,13 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "ui"
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "@fission-ai/openspec": ">=1.13.1 <2"
   }
 }

package/templates/PLANNER.md

@@ -0,0 +1,77 @@
+<!-- OSQ:START -->
+## Planning a change
+
+You write the change folder; a cheaper executor runs it one task at a time,
+sees only what you wrote, and reads it literally.
+
+### Interactive planning
+
+When a human is in the session:
+
+1. Read `AGENTS.md`, the capability specs this change touches, and one recent
+   archived change end to end.
+2. Reply with the parent spec, the task list (titles only), the capability specs
+   this change will write, and any `## Human steps`. Stop there.
+3. Write the change folder only after the human approves the list.
+
+### Working from the handoff
+
+When `osq plan` started you, `plan-prompt.md` in the selected change folder is
+your complete prompt; read it and follow it exactly.
+
+### Either way
+
+- Write only inside that change folder.
+- Run `osq lint <slug>` and fix every finding before you finish.
+- Never run `osq approve`; a human owns that gate.
+- Grep for what already exists; verify every version, flag, or API before use.
+- Write files with the file tool, never through a shell echo.
+
+### Tasks
+
+- One task per coherent unit. Title is "When X, Y".
+- Every task names its `scope` and `verify` (no TTY, no network). A task that changes a preexisting
+  test sets `tests.modify: true` and lists that test in `scope`; every other preexisting test is
+  frozen. `osq lint` enforces the configured limits on scope patterns and acceptance lines.
+- `osq init` and `osq new` seed `verify: node -e "process.exit(0)"` as a
+  planning sentinel, not trusted coverage. `osq lint` rejects it; replace it
+  before approval with a command that verifies the completed change's final tree.
+- Every task's `verify` exercises its slice through the real entry point, wiring included. If closing
+  the loop requires a file outside the task's `scope`, the scope is wrong; widen it or merge the task.
+  An executor result that says the work is outside its scope is a planning failure.
+- Every task's `verify` must stay re-runnable against the final tree of the
+  completed change, because the watcher and archive recertification run it there after
+  later tasks land. A command that passes only mid-change is a planning failure.
+- By default the watcher also runs the change-level `verify` after each task, and
+  a red result kills that task. Every task must leave it green; tasks that pass
+  only together are one task.
+- The watcher runs each task's `verify` once before the first attempt and expects
+  it to fail. A task whose `verify` should already pass before any change, such as
+  a refactor, declares `verify_starts: green`. A task whose `verify` names a test
+  the task creates declares `verify_starts: red`; a new test file may share that
+  verify with existing tests. `any` is only for a task that can honestly start
+  either way.
+- A file belongs to one task. Before each later task, the watcher re-hashes the
+  resolved `scope` of every done task; any change halts the change until a human
+  runs `osq retry`. Globs resolve again at every audit, so a broad glob also
+  captures files that later tasks create. When a later task must extend a file,
+  order that later task after the owner, name the shared file in the proposal,
+  and list the expected `osq retry` under `## Human steps`.
+- Task bodies carry acceptance lines and the names of existing code to reuse,
+  without signature blocks, numbered implementation steps, or line numbers. Write
+  full signatures only for ports.
+- Refer to functions and files by name, never by line number.
+
+### Parent spec
+
+- `## Goal`, then the change-level `verify` every proposal declares as the first
+  thing written after the goal, then `## Non-goals` and the contract as
+  requirements with scenarios.
+- `## Surface` follows `## Non-goals` and lists the user-facing names the change
+  adds, changes, or removes: commands, flags, config keys, frontmatter fields,
+  document sections, dead reasons, and event types. Write `None` when there are
+  none; `osq lint` rejects a proposal without the section.
+- The delta is the exact text the capability spec will contain after the change,
+  never an instruction to update something.
+- Anything a task must not do itself goes under `## Human steps`.
+<!-- OSQ:END -->

package/templates/openspec/config.yaml

@@ -0,0 +1,24 @@
+schema: osq
+
+context: |
+  This project follows the osq profile of OpenSpec. Living capability specs
+  live under openspec/specs/<capability>/spec.md. In-flight changes live under
+  openspec/changes/<id>-<slug>/ with a proposal.md, delta specs, and tasks.md.
+  Runtime state is derived exclusively from .run/ markers, never from tasks.md.
+
+  Execution and archive authority belong strictly to osq: tasks are executed
+  only by osq watch after human approval, archiving is owned exclusively by osq
+  and never openspec archive, and checkboxes in tasks.md are write-only runner
+  projections that prevent bypassing the approval hash.
+
+rules:
+  proposal:
+    - "Follow the proposal template's sections in order: Goal, Verify, Non-goals, Surface, Contract, Human steps, Delta."
+    - Declare the change-level verify command in frontmatter; the human gate reads the proposal before approving.
+  specs:
+    - Write one delta spec per capability at specs/<capability>/spec.md.
+    - Use exactly four hashtags for #### Scenario: blocks with WHEN/THEN bullets.
+  tasks:
+    - Break work into small tasks/<n>.md execution units that each state a verify command.
+    - Keep tasks.md checkboxes as a write-only projection of runtime state.
+    - Execute tasks exclusively through osq watch; never edit tasks.md checkboxes and never run openspec archive.

package/templates/openspec/schemas/osq/README.md

@@ -0,0 +1,30 @@
+# osq OpenSpec schema
+
+This is a fork of the built-in `spec-driven` schema. It keeps the same artifact
+graph shape but drops the optional `design` artifact:
+
+```
+proposal -> specs -> tasks
+```
+
+The `apply` phase waits for `tasks` and tracks `tasks.md`.
+
+## tasks/<n>.md is an osq-specific execution unit
+
+`tasks/<n>.md` sits outside the schema artifact graph. OpenSpec only knows about
+the `proposal.md`, `specs/**/*.md`, and `tasks.md` artifacts declared in
+`schema.yaml`; `tasks/<n>.md` is an osq-specific execution unit, not an OpenSpec
+artifact. Each `tasks/<n>.md` is the single unit of work handed to a coding
+agent: it carries the task title, a `verify` command, `scope`, `entry`,
+`skills`, and an acceptance checklist. Runtime completion is derived from
+`.run/` markers and the watcher's independent verify run, while `tasks.md` is
+only a write-only checkbox projection.
+
+## Execution and archive authority
+
+Agents that load the generated OpenSpec skills must not execute tasks on their
+own. Task execution belongs exclusively to `osq watch`, which runs only after
+human approval. `tasks.md` checkboxes are a write-only projection written by
+the osq runner from its independent verification run; agents must never edit
+them. Archiving is owned exclusively by `osq` and is never performed with
+`openspec archive`.

package/templates/openspec/schemas/osq/schema.yaml

@@ -0,0 +1,133 @@
+name: osq
+version: 1
+description: osq profile - proposal → specs → tasks (design dropped; tasks/<n>.md is the execution unit)
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    instruction: |
+      Create the proposal a human reads before approving the change. Follow the
+      template's frontmatter and sections exactly.
+
+      Frontmatter:
+      - `verify`: the change-level command that verifies the completed change's
+        final tree. `osq lint` rejects the seeded planning sentinel.
+      - `features.reads`: the living capabilities the change reads.
+
+      Sections, in this order:
+      - **Goal**: the problem this change solves and why now.
+      - **Verify**: the change-level `verify` command again, and what it proves.
+      - **Non-goals**: what the change deliberately does not do.
+      - **Surface**: the user-facing names the change adds, changes, or removes:
+        commands, flags, config keys, frontmatter fields, document sections,
+        dead reasons, and event types. Write `None` when there are none.
+      - **Contract**: requirements, each with `#### Scenario:` blocks using
+        WHEN/THEN bullets.
+      - **Human steps**: everything a task must not do itself, including running
+        `osq approve <id>`.
+      - **Delta**: one line per delta spec, and any file two tasks share.
+
+      Each capability the change adds or modifies needs a delta spec file at
+      `specs/<capability-path>/spec.md`. Run `openspec list --specs` to review the
+      project's capability inventory before introducing a near-duplicate. Never
+      run `osq approve` yourself; a human owns that gate.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Detailed delta specifications for the change
+    template: spec.md
+    instruction: |
+      Create delta specification files that define WHAT the system should do.
+
+      Create one spec file per capability listed in the proposal's Capabilities
+      section, at `specs/<capability-path>/spec.md`. New capabilities use the
+      exact path from the proposal; modified capabilities use the exact existing
+      path from `openspec/specs/<capability-path>/`.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features - MUST include **Reason**
+        and **Migration**
+      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+      Format requirements:
+      - Each requirement: `### Requirement: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`).
+      - Every requirement MUST have at least one scenario.
+
+      New capabilities only: the delta spec's first section is `## Purpose` -
+      one or two sentences (50+ characters) describing what the capability is
+      for. Do NOT add `## Purpose` to a delta for an existing capability.
+
+      MODIFIED requirements workflow:
+      1. Locate the existing requirement in
+         `openspec/specs/<capability-path>/spec.md`
+      2. Copy the ENTIRE requirement block (from `### Requirement:` through all
+         scenarios)
+      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+      4. Ensure header text matches exactly (whitespace-insensitive)
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks
+    template: tasks.md
+    instruction: |
+      Create the task list that breaks down the implementation work.
+
+      **IMPORTANT: Follow the template below exactly.** The apply phase parses
+      checkbox format to track progress. A box holding only `x` counts as done,
+      upper or lower case and with any spacing. Every other marker reads as
+      unfinished. A line with no checkbox is not tracked at all.
+
+      Guidelines:
+      - Group related tasks under ## numbered headings
+      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Tasks should be small enough to complete in one session
+      - Order tasks by dependency (what must be done first?)
+      - Each task MUST state how to verify completion
+
+      In osq, each checklist entry is backed by a `tasks/<n>.md` execution unit
+      that carries its own `verify` command, `scope`, `entry`, `skills`, and
+      acceptance checklist. `tasks/<n>.md` is not an OpenSpec artifact; it is the
+      osq execution unit, and `tasks.md` remains a write-only projection of
+      runtime state.
+
+      Execution authority:
+      - Tasks are executed ONLY by osq watch after human approval. Archiving is
+        owned exclusively by osq and NEVER openspec archive. Task checkboxes in
+        tasks.md are strictly written by the osq runner as a write-only
+        projection of runtime verification, preventing bypass of the approval
+        hash. Agents MUST NOT execute tasks directly or edit checkboxes in
+        tasks.md.
+
+      Example:
+      ```
+      # Tasks
+
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure and verify expected files are present
+      - [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function and verify the export test passes
+      ```
+    requires:
+      - specs
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Tasks in osq are executed strictly by running `osq watch`. Do not execute
+    tasks directly, do not edit tasks.md checkboxes, and never run
+    `openspec archive` or `openspec apply`. Task checkboxes are updated
+    automatically by the runner upon passing independent verification.

package/templates/openspec/schemas/osq/templates/proposal.md

@@ -0,0 +1,66 @@
+---
+title: Change title
+depends_on: []
+verify: node -e "process.exit(0)"
+features:
+  reads: []
+---
+## Goal
+
+What problem this change solves and why.
+
+## Verify
+
+`node -e "process.exit(0)"`
+
+Replace this planning sentinel, here and in the frontmatter, with the command
+that verifies the completed change's final tree, and say what it proves.
+
+## Non-goals
+
+- What this change deliberately does not do.
+
+## Surface
+
+<!-- User-facing names this change adds, changes, or removes: commands, flags,
+config keys, frontmatter fields, document sections, dead reasons, and event
+types. Replace None with one line per name, such as
+"- Added: `osq init --refresh-schema` (flag)". -->
+None
+
+## Contract
+
+### Requirement: <requirement name>
+
+The system SHALL <observable behavior>.
+
+#### Scenario: <scenario name>
+- **WHEN** <condition>
+- **THEN** <outcome>
+
+## Human steps
+
+- Review the proposal, delta specs, and task bodies, then run `osq approve <id>`
+  yourself.
+
+## Delta
+
+Delta specs live beside the proposal as `specs/<capability>/spec.md`. Each holds
+the exact text the capability spec will contain after the change, under
+`## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`,
+or `## RENAMED Requirements`; a modified requirement repeats its full text. List
+each delta here in one line and name any file two tasks share.
+
+A delta that introduces a new capability also declares the files it owns in a
+`### Requirement: Code ownership` block. Its `<!-- source: ... -->` comment lists
+the owned path globs, comma-separated, and its scenario restates them:
+
+```markdown
+### Requirement: Code ownership
+<!-- source: src/core/example.ts, src/cli/example.ts -->
+The <capability> capability SHALL own <subsystems>.
+
+#### Scenario: Codebase ownership boundaries
+- **WHEN** file ownership is resolved for <capability>
+- **THEN** system maps `src/core/example.ts` and `src/cli/example.ts` to <capability>
+```

package/templates/openspec/schemas/osq/templates/spec.md

@@ -0,0 +1,13 @@
+# Spec Delta
+
+## 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 -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

package/templates/openspec/schemas/osq/templates/tasks.md

@@ -0,0 +1,11 @@
+# Tasks
+
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->

package/templates/proposal.md

@@ -0,0 +1,66 @@
+---
+title: Change title
+depends_on: []
+verify: node -e "process.exit(0)"
+features:
+  reads: []
+---
+## Goal
+
+What problem this change solves and why.
+
+## Verify
+
+`node -e "process.exit(0)"`
+
+Replace this planning sentinel, here and in the frontmatter, with the command
+that verifies the completed change's final tree, and say what it proves.
+
+## Non-goals
+
+- What this change deliberately does not do.
+
+## Surface
+
+<!-- User-facing names this change adds, changes, or removes: commands, flags,
+config keys, frontmatter fields, document sections, dead reasons, and event
+types. Replace None with one line per name, such as
+"- Added: `osq init --refresh-schema` (flag)". -->
+None
+
+## Contract
+
+### Requirement: <requirement name>
+
+The system SHALL <observable behavior>.
+
+#### Scenario: <scenario name>
+- **WHEN** <condition>
+- **THEN** <outcome>
+
+## Human steps
+
+- Review the proposal, delta specs, and task bodies, then run `osq approve <id>`
+  yourself.
+
+## Delta
+
+Delta specs live beside the proposal as `specs/<capability>/spec.md`. Each holds
+the exact text the capability spec will contain after the change, under
+`## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`,
+or `## RENAMED Requirements`; a modified requirement repeats its full text. List
+each delta here in one line and name any file two tasks share.
+
+A delta that introduces a new capability also declares the files it owns in a
+`### Requirement: Code ownership` block. Its `<!-- source: ... -->` comment lists
+the owned path globs, comma-separated, and its scenario restates them:
+
+```markdown
+### Requirement: Code ownership
+<!-- source: src/core/example.ts, src/cli/example.ts -->
+The <capability> capability SHALL own <subsystems>.
+
+#### Scenario: Codebase ownership boundaries
+- **WHEN** file ownership is resolved for <capability>
+- **THEN** system maps `src/core/example.ts` and `src/cli/example.ts` to <capability>
+```

package/templates/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+## 1. Section title
+
+- [ ] 1. When initial condition, expected outcome