agent-orchestrator-kit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-18
+
+### Added
+- **`npx agent-orchestrator-kit archive <name>`** — deterministic archive CLI: gates (APPROVE, all tasks `[x]`, free target), delta-spec merge into main specs with `--sync` (ADDED append / MODIFIED replace / REMOVED delete), explicit refusal without a sync decision (`--sync` or `--no-sync --force`), snapshot + full rollback when `openspec validate --all --strict` fails, final `handoff.md` (`next_command: none`) + memory upsert
+- **Task contract lint** — `gate-check --tasks <name>` enforces `Files:` / `Do:` / `Done-when:` per task, rejects vague phrasing and nonexistent `Files:` paths without `new file:`; controlled by `pipeline.task_contract: warn|strict|off` (default `warn`, mvp `off`)
+- **Tiered review** — `gate-check --review <name> [--json]` is deterministic Tier 1 (strict validation, task-contract lint, proposal `Non-goals`/`Acceptance criteria`, non-empty delta sections); `spec-reviewer` runs only after Tier 1 passes and writes `apply-notes.md` (≤ 20 lines) on APPROVE
+
+### Changed
+- **Lean delegation model** — apply is parent-driven (implementer reads `tasks.md` + `apply-notes.md`, spawns subagents only for ≥ 2 independent tasks or on request, STOP escape valve instead of improvisation); archive is CLI-only with `spec-archiver` demoted to fallback; propose/review specialists remain mandatory
+- **Parent-driven session handoff** — canonical Session Start/Exit protocol consolidated in `.agents/rules/session-handoff.mdc`; `/opsx:*` commands reference it instead of duplicating it; `session-handoff` subagent and Memory MCP mirror are fallbacks (`handoff.spawn_handoff_subagent: false` in all profiles); `opsx-archive.md` slimmed to a ≤ 1.5 KB CLI wrapper
+
+## [0.2.0] - 2026-08-18
+
 ### Changed
 - **Context budget** — thinned always-apply rules and `AGENTS.md` / `CLAUDE.md`; details stay in on-demand skills. `figma-token-setup.mdc` is no longer `alwaysApply`. Restore spawn of `session-handoff` is skipped when `handoff --restore` already printed a briefing.
 
@@ -168,8 +181,17 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.3.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.14...v0.2.0
+[0.1.14]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.13...v0.1.14
+[0.1.13]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.12...v0.1.13
+[0.1.12]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.11...v0.1.12
+[0.1.11]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.10...v0.1.11
+[0.1.10]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.9...v0.1.10
+[0.1.9]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.2...v0.1.3

package/README.md

@@ -34,17 +34,18 @@ Each role runs in a **separate agent session**. The parent `/opsx:*` session is
 | `spec-archiver` | Delta merge and completed-change archive |
 | `session-handoff` | Restore/persist Memory + `handoff.md` + expanded next-thread prompt |
 
-The conductor uses one exclusive route per signal:
+Delegation is **differentiated per phase** (lean model): thinking-heavy phases spawn a mandatory specialist, apply is parent-driven, archive is a deterministic CLI:
 
-| Phase / signal | Subagent |
-|----------------|----------|
+| Phase / signal | Delegation |
+|----------------|------------|
 | Status / gates / next command | `openspec-guide` |
-| Session start restore / session exit persist | `session-handoff` |
+| Session start restore / session exit persist | parent-driven CLI (`handoff --restore` / `handoff <name>`); `session-handoff` is a fallback only |
 | Kit / MCP / sync repair | `setup-doctor` |
-| Explore repository research | `codebase-explorer` |
-| Design / propose / spec review | `design-intake` / `spec-architect` / `spec-reviewer` |
-| Apply UI / ordinary task / tests / pre-PR review | `design-implementer` / `code-writer` / `test-writer` / `code-reviewer` |
-| Archive | `spec-archiver` |
+| Explore repository research | `codebase-explorer` (mandatory) |
+| Design / propose / spec review | `design-intake` / `spec-architect` / `spec-reviewer` (mandatory) |
+| Apply | parent implements from `tasks.md` + `apply-notes.md`; `code-writer` / `test-writer` optional for ≥ 2 independent tasks or explicit request; `design-implementer` for design-brief/Figma tasks |
+| Pre-PR code review | `code-reviewer` |
+| Archive | `npx agent-orchestrator-kit archive <name>` (CLI — no subagent; `spec-archiver` is a fallback when the CLI is unavailable) |
 
 - **Cursor** → `.cursor/agents/` (native subagents)
 - **Claude Code** → `.claude/agents/` (native subagents)
@@ -73,7 +74,7 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (hardened handoff CLI + Memory launcher in v0.1.14+, conductor in v0.1.13+, Figma PAT in v0.1.11+):**
+**🔄 Already have the kit installed? Upgrade to latest (lean pipeline v2 / archive CLI in v0.3.0+, handoff CLI in v0.1.14+, Figma PAT in v0.1.11+):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -188,7 +189,7 @@ your-project/
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
 | IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills/subagents) |
 | Subagents | 12 exclusive routes: guide/setup/session-handoff, explore/design/propose/review/archive stage agents, and apply implementation/test/code-review agents — native in Cursor + Claude Code, isolated Amp `subagent-*` wrappers |
-| CLI gates | `npx agent-orchestrator-kit status` / `gate-check` / `handoff` / `memory-setup` — deterministic review-gate and session-handoff (always via `npx`; see `cli-via-npm.mdc`) |
+| CLI gates | `npx agent-orchestrator-kit status` / `gate-check` / `archive` / `handoff` / `memory-setup` — deterministic review-gate, archive, and session-handoff (always via `npx`; see `cli-via-npm.mdc`) |
 | CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook, both run `gate-check` |
 | AI Spec Verifier | `spec-verify.yml` + verifier scripts — GitLab or GitHub, opt-in (`--spec-verify`) |
 | MCP templates | Memory MCP for Cursor and Amp |
@@ -351,13 +352,13 @@ npx openspec validate <name> --strict --type change  # must be ✓
 **Model:** medium or strong.
 **Purpose:** Review artifacts. Output **Approve ✓** or **Request Changes ✗**.
 
-The conductor spawns `spec-reviewer` (not `code-reviewer`) and verifies its `review.md`.
+Review is **two-tiered**. Tier 1 is deterministic: `npx agent-orchestrator-kit gate-check --review <name>` runs strict OpenSpec validation, the task-contract lint, and structural checks (Non-goals / Acceptance criteria in `proposal.md`, non-empty delta-spec sections). If Tier 1 fails, the verdict is REQUEST CHANGES without spawning anyone. Only on a Tier 1 pass does the conductor spawn `spec-reviewer` (not `code-reviewer`) for Tier 2 judgment and verify its `review.md`. On APPROVE the reviewer also writes `apply-notes.md` (≤ 20 lines of constraints and pitfalls for the implementer).
 
-Checks:
-- Acceptance criteria are testable
-- Tasks ≤ ~2 hours each
+Tier 2 checks (judgment only — no duplication of Tier 1):
+- Consistency proposal ↔ design ↔ tasks
 - No scope creep vs Non-goals
 - No conflicts with existing domain specs
+- Tasks self-sufficient for a blind implementer (Files / Do / Done-when)
 
 ```
 /opsx:review add-bulk-camera-export
@@ -475,6 +476,18 @@ npx agent-orchestrator-kit gate-check [change-name] [--src-glob src/] [--base HE
 
 Fails (non-zero exit) when `pipeline.require_spec_review: true`, the diff against `--base` touches `--src-glob`, and the active change has no `review.md` with `Verdict: APPROVE`. When `pipeline.require_design_brief: true` and `src/` changed, it also requires `design-brief.md` (or a `Design: none` line in `proposal.md` for non-UI changes). It degrades gracefully to exit 0 (with a message, not silently) when: `.agents/orchestrator.yaml` is missing, neither review nor design brief is required, the diff can't be computed (e.g. shallow clone), or nothing under `--src-glob` changed. It also warns (never fails) when active changes exceed `pipeline.max_active_changes`. Both `agent-verify.yml` fragments (GitHub and GitLab) call `gate-check` automatically.
 
+```bash
+npx agent-orchestrator-kit gate-check --tasks <change-name>
+```
+
+Lints the task contract in `tasks.md`: every task needs `Files:` / `Do:` / `Done-when:`, no vague phrasing (`as needed`, `if necessary`, …), and every `Files:` path must exist unless prefixed `new file:`. Behavior follows `pipeline.task_contract` in `orchestrator.yaml`: `warn` (default) exits 0 with warnings, `strict` exits 1 on violations, `off` skips the lint.
+
+```bash
+npx agent-orchestrator-kit gate-check --review <change-name> [--json]
+```
+
+Deterministic Tier 1 of the review phase: strict OpenSpec validation, the task-contract lint, `Non-goals` / `Acceptance criteria` sections in `proposal.md`, and non-empty ADDED/MODIFIED/REMOVED sections in delta specs. Human-readable stdout, or `--json` for a `{pass, errors[]}` report.
+
 ---
 
 ### Design intake: `/opsx:design`
@@ -525,7 +538,13 @@ After PR merged + CI green:
 /opsx:archive add-bulk-camera-export
 ```
 
-Merges delta specs into `openspec/specs/` and moves change to `archive/`.
+Archive is a **deterministic CLI**, not an agent workflow:
+
+```bash
+npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
+```
+
+It checks the gates (APPROVE in `review.md` when required, all tasks `[x]`, target folder free), merges delta specs into `openspec/specs/` (`--sync`: ADDED append, MODIFIED replace, REMOVED delete), moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>`, and runs `npx openspec validate --all --strict` with a full rollback on failure (main specs restored, new spec files deleted, move reverted). With delta specs present you must decide: `--sync` merges, `--no-sync --force` archives without merging, and no flag refuses with exit 1. It finishes by writing the final `handoff.md` (`next_command: none`) and updating memory. The `/opsx:archive` command is a thin wrapper that calls this CLI; the `spec-archiver` subagent remains only as a fallback when the CLI is unavailable.
 
 ## Configuration
 
@@ -674,7 +693,7 @@ Handoff:add-bulk-export    next_role: implementer, next_command: /opsx:apply add
                            session_count: 2, summary: ..., blocked: none
 ```
 
-Every `/opsx:*` session restores via `npx agent-orchestrator-kit handoff --restore`, then Memory `Change:<name>`, `Handoff:<name>`, `Decision:*`, falling back to `handoff.md` if Memory is unavailable. At exit it MUST spawn `session-handoff`, write `handoff.md`, run `npx agent-orchestrator-kit handoff <name>` (upserts `.cursor/memory.json` with an absolute path), and paste the CLI stdout prompt. The prompt is self-contained — Amp often skips Memory MCP, so the next thread must be able to work from the pasted text alone. Never configure Memory with a relative `MEMORY_FILE_PATH`; use `scripts/memory-mcp-launcher.cjs` (`npx agent-orchestrator-kit memory-setup`). The next phase always starts in a new chat.
+Session boundaries are **parent-driven** (no routine subagent): every `/opsx:*` session restores via `npx agent-orchestrator-kit handoff --restore` (the CLI briefing already reads memory.json and `handoff.md`), falling back to reading `handoff.md` directly if the CLI fails. At exit the parent itself writes `handoff.md`, runs `npx agent-orchestrator-kit handoff <name>` (upserts `.cursor/memory.json` with an absolute path), and pastes the CLI stdout prompt. The `session-handoff` subagent is spawned only when the CLI path fails; Memory MCP is an optional mirror. The prompt is self-contained — Amp often skips Memory MCP, so the next thread must be able to work from the pasted text alone. Never configure Memory with a relative `MEMORY_FILE_PATH`; use `scripts/memory-mcp-launcher.cjs` (`npx agent-orchestrator-kit memory-setup`). The next phase always starts in a new chat. The canonical Session Start / Exit protocol lives in one place — `.agents/rules/session-handoff.mdc` — and the `/opsx:*` commands reference it instead of duplicating it.
 
 ## Amp Code — Deep Integration Notes
 
@@ -736,9 +755,15 @@ npx agent-orchestrator-kit status
 npx agent-orchestrator-kit gate-check [change-name] [options]
   --src-glob <glob>  Source path filter used to detect code changes (default: src/)
   --base <ref>       Git ref to diff against (default: HEAD~1)
+  --tasks <name>     Lint task contracts (Files / Do / Done-when)
+  --review <name>    Deterministic Tier 1 review (optional --json)
   Exit non-zero when require_spec_review is true, src/ changed, and the
   active change has no review.md with Verdict: APPROVE. Graceful no-op
   otherwise (missing config, review not required, no relevant diff).
+
+npx agent-orchestrator-kit archive <name> [--sync | --no-sync --force]
+  Gate-check a completed change, optionally merge delta specs, move to
+  openspec/changes/archive/YYYY-MM-DD-<name>, validate, write final handoff
 ```
 
 ## Directory Reference
@@ -776,6 +801,15 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 0.3.0
+- **`archive` CLI** — deterministic archive with gates, `--sync` delta merge, and rollback on validate failure
+- **Task contract** — `gate-check --tasks` enforces `Files:` / `Do:` / `Done-when:` (`pipeline.task_contract: warn|strict|off`)
+- **Tiered review** — `gate-check --review` is machine Tier 1; `spec-reviewer` writes `apply-notes.md` on APPROVE
+- Lean apply (parent-driven) and parent-driven session handoff; `opsx-archive.md` is a thin CLI wrapper
+
+### 0.2.0
+- Thinned always-apply rules and `AGENTS.md` / `CLAUDE.md` (context budget); details stay in on-demand skills
+
 ### 0.1.14
 - **HARD STOP session handoff** — `session-handoff` subagent at start/exit; Amp isolated `subagent-session-handoff`
 - **`handoff` CLI** — writes `handoff.md`, upserts `.cursor/memory.json` with an absolute path, prints an expanded self-contained next-thread prompt

package/bin/agent-orchestrator.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import pc from 'picocolors';
-import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync, renameSync } from 'fs';
 import { join, dirname, basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -747,8 +747,8 @@ function parseReviewVerdict(changeDir) {
   const reviewPath = join(changeDir, 'review.md');
   if (!existsSync(reviewPath)) return null;
   const content = readFileSync(reviewPath, 'utf-8');
-  const match = content.match(/\*\*Verdict:\*\*\s*(.+)/);
-  return match ? match[1].trim() : 'unknown';
+  const match = content.match(/^(?:#{1,6}\s*)?\*{0,2}Verdict:\*{0,2}\s*(.+?)\s*$/m);
+  return match ? match[1].replace(/\*+\s*$/, '').trim() : 'unknown';
 }
 
 function parseDesignBrief(changeDir) {
@@ -769,13 +769,237 @@ function readPipelineConfig(projectDir) {
   const requireReviewMatch = content.match(/require_spec_review:\s*(true|false)/);
   const requireBriefMatch = content.match(/require_design_brief:\s*(true|false)/);
   const maxActiveMatch = content.match(/max_active_changes:\s*(\d+)/);
+  const taskContractMatch = content.match(/task_contract:\s*(warn|strict|off)/);
   return {
     requireSpecReview: requireReviewMatch ? requireReviewMatch[1] === 'true' : true,
     requireDesignBrief: requireBriefMatch ? requireBriefMatch[1] === 'true' : false,
     maxActiveChanges: maxActiveMatch ? parseInt(maxActiveMatch[1], 10) : null,
+    taskContract: taskContractMatch ? taskContractMatch[1] : 'warn',
   };
 }
 
+// --- Task-contract lint (gate-check --tasks) ---
+
+const VAGUE_DO_PATTERNS = [/\bas needed\b/i, /\bif necessary\b/i, /\bas appropriate\b/i, /де потрібно/i, /за потреби/i];
+
+function taskContractMode(projectDir) {
+  const config = readPipelineConfig(projectDir);
+  return config ? config.taskContract : 'warn';
+}
+
+function parseTaskContracts(content) {
+  const tasks = [];
+  let current = null;
+  for (const line of content.split('\n')) {
+    const taskMatch = line.match(/^\s*- \[[ xX]\]\s+(.*)$/);
+    if (taskMatch) {
+      current = { title: taskMatch[1].trim(), files: null, do: null, doneWhen: null };
+      tasks.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const fieldMatch = line.match(/^\s+(Files|Do|Done-when):\s*(.*)$/);
+    if (fieldMatch) {
+      const value = fieldMatch[2].trim();
+      if (fieldMatch[1] === 'Files') current.files = value;
+      else if (fieldMatch[1] === 'Do') current.do = value;
+      else current.doneWhen = value;
+    } else if (/^\S/.test(line)) {
+      current = null;
+    }
+  }
+  return tasks;
+}
+
+function lintTaskContracts(projectDir, tasksPath) {
+  const errors = [];
+  const tasks = parseTaskContracts(readFileSync(tasksPath, 'utf-8'));
+  for (const task of tasks) {
+    const label = `task "${task.title.slice(0, 60)}"`;
+    if (!task.files) errors.push(`${label}: missing Files:`);
+    if (!task.do) errors.push(`${label}: missing Do:`);
+    if (!task.doneWhen) errors.push(`${label}: missing Done-when:`);
+    if (task.do) {
+      for (const pattern of VAGUE_DO_PATTERNS) {
+        const match = task.do.match(pattern);
+        if (match) errors.push(`${label}: vague wording in Do: "${match[0]}"`);
+      }
+    }
+    if (task.files) {
+      for (const entry of task.files.split(',').map((s) => s.trim()).filter(Boolean)) {
+        if (/^new file:/i.test(entry)) continue;
+        if (!existsSync(join(projectDir, entry))) errors.push(`${label}: Files: path does not exist: ${entry} (prefix with "new file:" if intentional)`);
+      }
+    }
+  }
+  return errors;
+}
+
+function runTasksLint(projectDir, name, { quiet = false } = {}) {
+  const mode = taskContractMode(projectDir);
+  const report = { mode, errors: [], warnings: [] };
+  if (mode === 'off') return report;
+  const tasksPath = join(projectDir, 'openspec', 'changes', name, 'tasks.md');
+  if (!existsSync(tasksPath)) {
+    report.warnings.push(`tasks.md not found: ${tasksPath}`);
+    return report;
+  }
+  const findings = lintTaskContracts(projectDir, tasksPath);
+  if (mode === 'strict') report.errors = findings;
+  else report.warnings = [...report.warnings, ...findings];
+  if (!quiet) {
+    for (const e of report.errors) log.err(e);
+    for (const w of report.warnings) log.warn(w);
+  }
+  return report;
+}
+
+// --- Tier 1 review (gate-check --review) ---
+
+// Change names are interpolated into shell commands and paths; keep them slugs.
+function isSafeChangeName(name) {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
+}
+
+function runTier1Review(projectDir, name) {
+  const errors = [];
+  if (!isSafeChangeName(name)) {
+    return { pass: false, errors: [`invalid change name: ${name}`] };
+  }
+  const changeDir = join(projectDir, 'openspec', 'changes', name);
+  if (!existsSync(changeDir)) {
+    return { pass: false, errors: [`change not found: ${name}`] };
+  }
+
+  try {
+    execSync(`npx openspec validate ${name} --strict --type change`, {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+    });
+  } catch (e) {
+    const detail = `${e.stdout || ''}${e.stderr || ''}`.trim().split('\n')[0] || 'non-zero exit';
+    errors.push(`openspec validate --strict failed: ${detail}`);
+  }
+
+  const lint = runTasksLint(projectDir, name, { quiet: true });
+  errors.push(...lint.errors);
+
+  const proposalPath = join(changeDir, 'proposal.md');
+  if (!existsSync(proposalPath)) {
+    errors.push('proposal.md not found');
+  } else {
+    const proposal = readFileSync(proposalPath, 'utf-8');
+    if (!/^#{2,}\s*Non-goals\b/im.test(proposal)) errors.push('proposal.md: missing "Non-goals" section');
+    if (!/^#{2,}\s*Acceptance criteria\b/im.test(proposal)) errors.push('proposal.md: missing "Acceptance criteria" section');
+  }
+
+  for (const deltaPath of listDeltaSpecFiles(changeDir)) {
+    const rel = deltaPath.replace(`${projectDir}/`, '');
+    const sections = parseDeltaSpec(readFileSync(deltaPath, 'utf-8'));
+    const total = sections.ADDED.length + sections.MODIFIED.length + sections.REMOVED.length;
+    if (total === 0) errors.push(`${rel}: no non-empty ADDED/MODIFIED/REMOVED Requirements section`);
+  }
+
+  return { pass: errors.length === 0, errors, warnings: lint.warnings };
+}
+
+// --- Delta spec sync (archive --sync) ---
+
+function listDeltaSpecFiles(changeDir) {
+  const specsDir = join(changeDir, 'specs');
+  if (!existsSync(specsDir)) return [];
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full);
+      else if (entry.endsWith('.md')) files.push(full);
+    }
+  };
+  walk(specsDir);
+  return files.sort();
+}
+
+function splitRequirementBlocks(sectionBody) {
+  return String(sectionBody || '')
+    .split(/^### Requirement: /m)
+    .slice(1)
+    .map((part) => {
+      const nl = part.indexOf('\n');
+      const name = (nl === -1 ? part : part.slice(0, nl)).trim();
+      const body = nl === -1 ? '' : part.slice(nl + 1);
+      return { name, block: `### Requirement: ${name}\n${body}`.replace(/\s+$/, '') };
+    });
+}
+
+function parseDeltaSpec(content) {
+  const sections = { ADDED: [], MODIFIED: [], REMOVED: [] };
+  const parts = String(content || '').split(/^## /m);
+  for (const part of parts.slice(1)) {
+    const nl = part.indexOf('\n');
+    const title = (nl === -1 ? part : part.slice(0, nl)).trim();
+    const body = nl === -1 ? '' : part.slice(nl + 1);
+    const match = title.match(/^(ADDED|MODIFIED|REMOVED) Requirements$/);
+    if (match) sections[match[1]] = splitRequirementBlocks(body);
+  }
+  return sections;
+}
+
+function findRequirementSpan(content, name) {
+  const header = `### Requirement: ${name}`;
+  const idx = content.indexOf(header);
+  if (idx === -1) return null;
+  const rest = content.slice(idx + header.length);
+  const relEnd = rest.search(/\n### Requirement: |\n## /);
+  const end = relEnd === -1 ? content.length : idx + header.length + relEnd;
+  return [idx, end];
+}
+
+function planSpecSync(projectDir, deltaSpecPaths, changeName) {
+  const plan = [];
+  const conflicts = [];
+  for (const deltaPath of deltaSpecPaths) {
+    const capability = basename(dirname(deltaPath));
+    const mainPath = join(projectDir, 'openspec', 'specs', capability, 'spec.md');
+    const delta = parseDeltaSpec(readFileSync(deltaPath, 'utf-8'));
+    if (delta.ADDED.length + delta.MODIFIED.length + delta.REMOVED.length === 0) continue;
+    const existed = existsSync(mainPath);
+    const dirExisted = existsSync(dirname(mainPath));
+    const oldContent = existed ? readFileSync(mainPath, 'utf-8') : null;
+    let content = existed
+      ? oldContent
+      : `## Purpose\n\n${capability} — requirements merged from change ${changeName}.\n\n## Requirements\n`;
+
+    for (const req of delta.REMOVED) {
+      const span = findRequirementSpan(content, req.name);
+      if (!span) {
+        conflicts.push(`${capability}: REMOVED requirement not found in main spec: "${req.name}"`);
+        continue;
+      }
+      content = `${content.slice(0, span[0]).replace(/\n+$/, '\n\n')}${content.slice(span[1]).replace(/^\n+/, '')}`;
+    }
+    for (const req of delta.MODIFIED) {
+      const span = findRequirementSpan(content, req.name);
+      if (!span) {
+        conflicts.push(`${capability}: MODIFIED requirement not found in main spec: "${req.name}"`);
+        continue;
+      }
+      content = `${content.slice(0, span[0])}${req.block}\n\n${content.slice(span[1]).replace(/^\n+/, '')}`;
+    }
+    for (const req of delta.ADDED) {
+      if (findRequirementSpan(content, req.name)) {
+        conflicts.push(`${capability}: ADDED requirement already exists in main spec: "${req.name}"`);
+        continue;
+      }
+      content = `${content.replace(/\s+$/, '')}\n\n${req.block}\n`;
+    }
+    if (!content.endsWith('\n')) content += '\n';
+    plan.push({ mainPath, existed, dirExisted, oldContent, newContent: content });
+  }
+  return { plan, conflicts };
+}
+
 // Returns true/false when the diff is known, or null when it could not be
 // determined (no git repo, invalid base ref, shallow clone, etc.) — callers
 // must treat null as "skip gracefully", never as "block".
@@ -1354,8 +1578,46 @@ program
   .description('Deterministically check the review gate before apply/merge (exit non-zero if unmet)')
   .option('--src-glob <glob>', 'source path filter used to detect code changes', 'src/')
   .option('--base <ref>', 'git ref to diff against', 'HEAD~1')
+  .option('--tasks <name>', 'lint task contracts (Files/Do/Done-when) of a change')
+  .option('--review <name>', 'run deterministic Tier 1 review checks on a change')
+  .option('--json', 'with --review: print a {pass, errors[]} JSON report to stdout', false)
   .action((changeName, opts) => {
     const projectDir = process.cwd();
+
+    if (opts.tasks) {
+      log.title(`gate-check --tasks  ${opts.tasks}`);
+      const mode = taskContractMode(projectDir);
+      if (mode === 'off') {
+        log.info('task contract lint disabled (pipeline.task_contract: off)');
+        return;
+      }
+      const report = runTasksLint(projectDir, opts.tasks);
+      if (report.errors.length) {
+        console.error(`task contract gate failed — ${report.errors.length} error(s) (pipeline.task_contract: strict)`);
+        process.exitCode = 1;
+      } else if (report.warnings.length) {
+        log.warn(`task contract: ${report.warnings.length} issue(s) — warn mode, not blocking`);
+      } else {
+        log.ok('all tasks follow the contract (Files/Do/Done-when)');
+      }
+      return;
+    }
+
+    if (opts.review) {
+      const result = runTier1Review(projectDir, opts.review);
+      if (opts.json) {
+        console.log(JSON.stringify({ pass: result.pass, errors: result.errors }, null, 2));
+      } else {
+        log.title(`gate-check --review  ${opts.review}`);
+        for (const e of result.errors) log.err(e);
+        for (const w of result.warnings || []) log.warn(w);
+        if (result.pass) log.ok('Tier 1 review passed — proceed to spec-reviewer (Tier 2)');
+        else log.err(`Tier 1 review failed — ${result.errors.length} error(s)`);
+      }
+      if (!result.pass) process.exitCode = 1;
+      return;
+    }
+
     log.title('agent-orchestrator gate-check');
 
     const config = readPipelineConfig(projectDir);
@@ -1427,6 +1689,146 @@ program
     }
   });
 
+program
+  .command('archive <name>')
+  .description('Archive a completed change: check gates, optionally sync delta specs, move to a dated archive, validate, write final handoff')
+  .option('--sync', 'merge delta specs into openspec/specs/ before archiving')
+  .option('--no-sync', 'skip delta-spec merge (requires --force when delta specs exist)')
+  .option('--force', 'confirm archiving without merge when delta specs exist', false)
+  .action((name, opts) => {
+    const projectDir = process.cwd();
+    const fail = (msg) => {
+      console.error(msg);
+      process.exitCode = 1;
+    };
+    log.title(`agent-orchestrator archive  ${name}`);
+
+    if (!isSafeChangeName(name)) return fail(`invalid change name: ${name}`);
+
+    let status;
+    try {
+      const out = execSync(`npx openspec status --change ${name} --json`, {
+        cwd: projectDir,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+      });
+      status = JSON.parse(out);
+    } catch (e) {
+      const detail = `${(e.stderr || e.stdout || e.message || '')}`.trim().split('\n')[0];
+      return fail(`could not resolve change "${name}" via openspec status: ${detail}`);
+    }
+
+    const changeRoot = status.changeRoot || join(projectDir, 'openspec', 'changes', name);
+    const changesDir = (status.planningHome && status.planningHome.changesDir) || join(projectDir, 'openspec', 'changes');
+    if (!existsSync(changeRoot)) return fail(`change not found: ${changeRoot}`);
+
+    // Gate 1: review verdict (only when required by pipeline config)
+    const config = readPipelineConfig(projectDir);
+    const requireReview = config ? config.requireSpecReview : true;
+    if (requireReview) {
+      const verdict = parseReviewVerdict(changeRoot);
+      if (!(verdict && /^APPROVE/i.test(verdict))) {
+        return fail(`review gate failed — change "${name}" has ${verdict ? `verdict "${verdict}"` : 'no review.md'} (require_spec_review: true)`);
+      }
+    }
+
+    // Gate 2: all tasks checked (skipped when the schema has no tasks artifact)
+    const tasksPaths = (status.artifactPaths && status.artifactPaths.tasks && status.artifactPaths.tasks.existingOutputPaths) || [];
+    for (const tasksPath of tasksPaths) {
+      if (/^\s*- \[ \]/m.test(readFileSync(tasksPath, 'utf-8'))) {
+        return fail(`tasks gate failed — ${tasksPath.replace(`${projectDir}/`, '')} still has unchecked "- [ ]" items`);
+      }
+    }
+
+    // Gate 3: target archive must not exist
+    const dateStamp = new Date().toISOString().slice(0, 10);
+    const targetDir = join(changesDir, 'archive', `${dateStamp}-${name}`);
+    const targetRel = targetDir.replace(`${projectDir}/`, '');
+    if (existsSync(targetDir)) return fail(`archive gate failed — target already exists: ${targetRel}`);
+
+    // Sync decision for delta specs
+    const deltaSpecs = listDeltaSpecFiles(changeRoot);
+    let plan = [];
+    let syncStatus = 'no delta specs';
+    if (deltaSpecs.length) {
+      if (opts.sync === undefined) {
+        return fail(`change "${name}" has ${deltaSpecs.length} delta spec(s) — pass --sync to merge them into openspec/specs/, or --no-sync --force to archive without merging`);
+      }
+      if (opts.sync === false && !opts.force) {
+        return fail('refusing --no-sync without --force — delta specs would be archived without merging into openspec/specs/');
+      }
+      if (opts.sync) {
+        const result = planSpecSync(projectDir, deltaSpecs, name);
+        if (result.conflicts.length) {
+          for (const conflict of result.conflicts) console.error(`sync conflict: ${conflict}`);
+          return fail('delta-spec merge refused — resolve conflicts manually with the openspec-sync-specs skill, then re-run archive');
+        }
+        plan = result.plan;
+        // Snapshots of affected main specs are held in plan[].oldContent for rollback.
+        for (const entry of plan) {
+          mkdirSync(dirname(entry.mainPath), { recursive: true });
+          writeFileSync(entry.mainPath, entry.newContent);
+        }
+        syncStatus = `synced ${plan.length} main spec file(s)`;
+      } else {
+        syncStatus = 'skipped (--no-sync --force)';
+      }
+    }
+
+    // Move change into the dated archive
+    mkdirSync(dirname(targetDir), { recursive: true });
+    renameSync(changeRoot, targetDir);
+
+    // Strict validation with full rollback on failure
+    try {
+      execSync('npx openspec validate --all --strict', {
+        cwd: projectDir,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+      });
+    } catch (e) {
+      renameSync(targetDir, changeRoot);
+      for (const entry of plan) {
+        if (entry.existed) writeFileSync(entry.mainPath, entry.oldContent);
+        else if (entry.dirExisted) rmSync(entry.mainPath, { force: true });
+        else rmSync(dirname(entry.mainPath), { recursive: true, force: true });
+      }
+      const detail = `${e.stdout || ''}${e.stderr || ''}`.trim() || 'non-zero exit';
+      console.error(detail);
+      return fail('openspec validate --all --strict failed — rolled back: change restored, main specs reverted to pre-sync state');
+    }
+
+    // Final handoff: pipeline is complete, no next-session prompt
+    const progress = parseTasksProgress(targetDir);
+    const fields = {
+      changeName: name,
+      closedRole: 'Archiver',
+      change: `- name: ${name}\n- status: archived`,
+      done: `Change archived to ${targetRel}. Delta spec sync: ${syncStatus}. openspec validate --all --strict passed.`,
+      decisions: 'none',
+      blocked: 'none',
+      nextCommand: 'none',
+      nextRole: 'none',
+      attach: `- \`${targetRel}/\``,
+      spawn: 'none',
+      constraints: 'Pipeline complete — no next session.',
+      status: 'archived',
+      tasks: progress ? `${progress.done}/${progress.total}` : '',
+      review: parseReviewVerdict(targetDir) || '',
+      summary: `archived to ${targetRel}`,
+    };
+    writeFileSync(join(targetDir, 'handoff.md'), `${buildHandoffMarkdown(fields).trim()}\n`);
+    const memoryPath = persistMemoryFromHandoff(projectDir, fields);
+
+    console.log(`change:   ${name}`);
+    console.log(`schema:   ${status.schemaName || 'unknown'}`);
+    console.log(`archive:  ${targetRel}`);
+    console.log(`sync:     ${syncStatus}`);
+    console.log(`handoff:  ${join(targetRel, 'handoff.md')} (next_command: none)`);
+    console.log(`memory:   ${memoryPath.replace(`${projectDir}/`, '')}`);
+    log.ok(`archived ${name}`);
+  });
+
 program
   .command('figma-setup')
   .description('Create local Figma token env file (never prints the token)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, conductor subagents, durable session handoff CLI, and optional local Figma PAT setup",
   "keywords": [
     "ai-agent",

package/profiles/generic/orchestrator.yaml

@@ -10,6 +10,7 @@ pipeline:
   require_design_brief: false
   max_active_changes: 1
   archive_after_merge: true
+  task_contract: warn
 
 roles:
   explorer:
@@ -48,7 +49,7 @@ handoff:
   persist_on_exit: true
   emit_next_session_prompt: true
   prompt_self_contained: true
-  spawn_handoff_subagent: true
+  spawn_handoff_subagent: false
 
 memory:
   enabled: true

package/profiles/mvp/openspec-config.yaml.example

@@ -12,6 +12,8 @@ rules:
     - Acceptance criteria — 3–5 перевірних пунктів
   tasks:
     - 3–7 атомарних задач
+    - "Контракт таска: індентовані поля Files: (реальні шляхи; нові — з префіксом new file:), Do: (конкретна зміна, 1–3 рядки), Done-when: (перевірна умова або команда)"
+    - Таск самодостатній без design.md; без неконкретних формулювань («as needed», «if necessary», «за потреби»)
     - Останній пункт: build + lint
   specs:
     - Опційно для MVP — пропускай якщо change тривіальний