agent-orchestrator-kit 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.7] - 2026-07-07
+
+### Added
+- **`agent-orchestrator status`** — dashboard for active OpenSpec changes: task progress (`N/M`), review verdict, `ready to archive` flag
+- **`agent-orchestrator gate-check`** — deterministic review-gate check; exits non-zero when `src/` changed without an approved `review.md` (`require_spec_review: true`); warns (non-blocking) when active changes exceed `max_active_changes`; graceful no-op without `.agents/orchestrator.yaml`, when review isn't required, or when the diff can't be computed
+- **GitHub AI Spec Verifier** — `init --ci github --spec-verify` installs `.github/workflows/spec-verify.yml` + `scripts/post-pr-verdict-github.sh` (via `gh pr comment`), reusing the existing stack-agnostic `scripts/verify-specs.sh`
+- **OpenSpec specs** — `orchestrator-cli-controls`, `github-spec-verify`
+
+### Changed
+- **`sync`** (CLI) now removes stale skills/rules no longer present in `.agents/skills|rules` — matches `sync-local-agent-skills.sh` (`rsync --delete`); does not touch `memory.json`, `.mcp.json`, `CLAUDE.md`, `settings.json`
+- **`agent-verify.yml`** (both GitHub and GitLab fragments) now run `gate-check` as part of verify
+- **`--spec-verify`** — no longer GitLab-only; valid with `--ci gitlab` or `--ci github`
+- **README / AGENTS.md / agent-orchestration skill** — document `status`, `gate-check`, and GitHub Spec Verifier parity
+
+## [0.1.6] - 2026-07-02
+
+### Added
+- **`init --spec-verify`** — opt-in AI Spec Verifier for GitLab consumers: on MRs changing `src/`, an Amp agent verifies code against `openspec/specs/`, posts PASS/BLOCKED to the MR, and fails the pipeline on BLOCKED
+- **Templates** — `.gitlab/spec-verify.yml` (blocking job, commented Phase 1 `allow_failure` fallback), `scripts/verify-specs.sh` (stack-agnostic prompt with project context from `openspec/config.yaml`, graceful skips, secret-safe), `scripts/post-mr-verdict.sh` (GitLab MR comment)
+- **Orchestrator gate** — `spec-verify-blocking` auto-added to `roles.verifier.gates` (idempotent)
+- **OpenSpec spec** — `spec-verify-consumer`
+
+### Changed
+- **`update`** refreshes spec-verify files via `KIT_OPTIN_PATHS` — only in projects that already installed them
+- **README / AGENTS.md template** — AI Spec Verifier documented (install, CI variables, verdict schema, Phase 1 rollout)
+
 ## [0.1.5] - 2026-06-27
 
 ### Added
@@ -63,6 +89,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Initial release: 5-role orchestration pipeline, `/opsx:*` commands, IDE sync
 
+[0.1.7]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.6...v0.1.7
 [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

@@ -99,7 +99,9 @@ your-project/
 ├── AGENTS.md
 ├── CLAUDE.md
 ├── .github/workflows/agent-verify.yml   # CI (default --ci github)
+├── .github/workflows/spec-verify.yml    # AI Spec Verifier (--ci github --spec-verify, opt-in)
 ├── .gitlab/agent-verify.yml             # CI fragment (--ci gitlab)
+├── .gitlab/spec-verify.yml              # AI Spec Verifier (--ci gitlab --spec-verify, opt-in)
 ├── .agents/
 │   ├── orchestrator.yaml
 │   ├── mcp.json.example                 # Cursor MCP template
@@ -115,7 +117,8 @@ your-project/
 │       ├── openspec-archive-change/
 │       ├── openspec-sync-specs/
 │       └── spec-workflow-openspec/
-└── scripts/sync-local-agent-skills.sh
+├── scripts/sync-local-agent-skills.sh
+└── scripts/verify-specs.sh + post-mr-verdict.sh / post-pr-verdict-github.sh   # (--spec-verify, opt-in)
 ```
 
 ### Included in kit
@@ -124,8 +127,10 @@ your-project/
 |----------|----------|
 | Orchestration | 5-role pipeline, `AGENTS.md`, `orchestrator.yaml`, review command |
 | OpenSpec skills | All 7 skills for `/opsx:*` workflow |
-| IDE sync | Cursor + Claude Code sync script |
-| CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook |
+| IDE sync | Cursor + Claude Code sync script (`--delete` semantics — removes stale skills) |
+| CLI gates | `agent-orchestrator status` / `gate-check` — deterministic review-gate checks |
+| 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 |
 
 ### Not included (install separately)
@@ -326,6 +331,72 @@ Optional: include `.gitlab/agent-verify.yml` in `.gitlab-ci.yml` for full lint/b
 
 Blocks merge if any gate fails.
 
+Every CI fragment (`agent-verify.yml`, GitHub and GitLab) also runs `npx agent-orchestrator-kit gate-check` — see [Deterministic gates](#deterministic-gates-status--gate-check) below. It never fails the pipeline for projects without `.agents/orchestrator.yaml`.
+
+#### AI Spec Verifier (GitLab or GitHub, opt-in)
+
+```bash
+npx agent-orchestrator-kit init --ci gitlab --spec-verify
+npx agent-orchestrator-kit init --ci github --spec-verify
+```
+
+Installs an AI verification layer on top of the deterministic gates: on every merge/pull request that changes `src/`, an Amp agent reads `openspec/specs/`, checks the changed code against every relevant requirement, posts a **PASS / BLOCKED** comment to the MR/PR, and **fails the pipeline on BLOCKED** — specs become an enforceable merge contract, not just documentation.
+
+Installed files (GitLab):
+
+| File | Purpose |
+|------|---------|
+| `.gitlab/spec-verify.yml` | CI fragment — hidden `.spec-verify-base` + blocking `spec-verify` job (MR + `src/**/*` only) |
+| `scripts/verify-specs.sh` | Collects changed files + specs, builds prompt (project context from `openspec/config.yaml`), calls `amp -x`, writes `artifacts/verdict.json` |
+| `scripts/post-mr-verdict.sh` | Posts the verdict as an MR comment via GitLab API |
+
+Installed files (GitHub):
+
+| File | Purpose |
+|------|---------|
+| `.github/workflows/spec-verify.yml` | Workflow triggered on `pull_request` for `src/**` — same verdict evaluation, `permissions: pull-requests: write` |
+| `scripts/verify-specs.sh` | Same script as GitLab — stack-agnostic, reused as-is |
+| `scripts/post-pr-verdict-github.sh` | Posts the verdict as a PR comment via `gh pr comment` |
+
+The flag also adds `spec-verify-blocking` to `roles.verifier.gates` in `.agents/orchestrator.yaml`.
+
+Setup after install (GitLab):
+
+1. Include the fragment from `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - local: '.gitlab/spec-verify.yml'
+```
+
+2. Add CI/CD variables (Settings → CI/CD → Variables, masked): `AMP_API_KEY`, `GITLAB_VERIFIER_TOKEN` (project access token with `api` scope).
+
+Setup after install (GitHub): the workflow runs automatically on `pull_request` — just add the repo secret `AMP_API_KEY` (Settings → Secrets and variables → Actions). `GITHUB_TOKEN` is provided by Actions automatically.
+
+Verdict schema (`artifacts/verdict.json`): `pass`, `score` (0–100), `summary`, `findings[]` with `severity` (`error` fails the job), `spec`, `requirement`, `message`, `file`. The script degrades gracefully — no `src/` changes, no specs, missing `amp` CLI, or missing `AMP_API_KEY` produce a skipped passing verdict and never block the pipeline. Secrets are never logged; `.env`/key/token files are excluded from prompts.
+
+**Warning-only rollout (Phase 1):** uncomment `allow_failure: true` (GitLab) or `continue-on-error: true` (GitHub) to keep the pipeline green while the team builds trust in verdicts, then remove it to enforce blocking (Phase 2).
+
+`update` refreshes the spec-verify files only in projects that already installed them — the feature stays opt-in.
+
+---
+
+### Deterministic gates: `status` / `gate-check`
+
+Orchestration hard rules (review approval, one active change) used to rely entirely on the agent remembering to check them in chat. Two CLI commands make them checkable and CI-enforceable:
+
+```bash
+npx agent-orchestrator-kit status
+```
+
+Prints every active OpenSpec change with task progress (`N/M tasks`), review verdict (`APPROVE` / `REQUEST CHANGES` / `none`), and a `ready to archive` flag once all tasks are `[x]` — no more running `openspec status` per change by hand.
+
+```bash
+npx agent-orchestrator-kit gate-check [change-name] [--src-glob src/] [--base HEAD~1]
+```
+
+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`. It degrades gracefully to exit 0 (with a message, not silently) when: `.agents/orchestrator.yaml` is missing, review isn't 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.
+
 ---
 
 ### Archive — `/opsx:archive`
@@ -460,14 +531,26 @@ npx agent-orchestrator-kit init [options]
   --lang <code>      Agent language: en | uk | ...
   --name <name>      Project name (default: directory name)
   --ci <provider>    CI provider: gitlab | github | none (default: github)
+  --spec-verify      Install AI Spec Verifier blocking gate (GitLab or GitHub)
   --force            Overwrite existing files
 
 npx agent-orchestrator-kit update
   Updates kit-managed files, preserves project overlay
 
 npx agent-orchestrator-kit sync [options]
-  --target <ide>     cursor | claude | all (default: all)
-  Copies .agents/ to local IDE directories
+  --target <ide>     cursor | claude | amp | all (default: all)
+  Copies .agents/ to local IDE directories, removing skills/rules no longer
+  present in .agents/ (does not touch memory.json, .mcp.json, CLAUDE.md, etc.)
+
+npx agent-orchestrator-kit status
+  Show progress, review verdict, and archive-readiness for active changes
+
+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)
+  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).
 ```
 
 ## Directory Reference
@@ -501,6 +584,18 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 0.1.7
+- `agent-orchestrator status` — dashboard for active OpenSpec changes: task progress, review verdict, archive readiness
+- `agent-orchestrator gate-check` — deterministic review-gate check (exit non-zero without an approved `review.md`); wired into both `agent-verify.yml` CI fragments
+- `init --ci github --spec-verify` — GitHub parity for the AI Spec Verifier (`.github/workflows/spec-verify.yml`, `scripts/post-pr-verdict-github.sh`), reusing the existing stack-agnostic `verify-specs.sh`
+- `sync` (CLI) now removes skills/rules that no longer exist in `.agents/` — matches `sync-local-agent-skills.sh` (`rsync --delete`) behavior; leaves `memory.json`, `.mcp.json`, `CLAUDE.md`, `settings.json` untouched
+
+### 0.1.6
+- `init --ci gitlab --spec-verify` — opt-in AI Spec Verifier: blocking MR gate via Amp CLI
+- Templates: `.gitlab/spec-verify.yml`, `scripts/verify-specs.sh`, `scripts/post-mr-verdict.sh`
+- `spec-verify-blocking` gate auto-added to `roles.verifier.gates`
+- `update` refreshes spec-verify files only where already installed
+
 ### 0.1.5
 - `init --ci gitlab|github|none` — GitLab verify via prebuild hook + CI fragment
 - PM-aware `verify:openspec` / `prebuild` injection for GitLab projects

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 } from 'fs';
+import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync, writeFileSync, rmSync } from 'fs';
 import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -32,6 +32,26 @@ const KIT_MANAGED_PATHS = [
   'scripts/sync-local-agent-skills.sh',
 ];
 
+// Opt-in AI Spec Verifier files, per CI provider. `scripts/verify-specs.sh` is
+// shared — it is stack- and CI-agnostic already.
+const GITLAB_SPEC_VERIFY_PATHS = [
+  '.gitlab/spec-verify.yml',
+  'scripts/verify-specs.sh',
+  'scripts/post-mr-verdict.sh',
+];
+const GITHUB_SPEC_VERIFY_PATHS = [
+  '.github/workflows/spec-verify.yml',
+  'scripts/verify-specs.sh',
+  'scripts/post-pr-verdict-github.sh',
+];
+
+// Opt-in files: refreshed by `update` only when already present in the project
+const KIT_OPTIN_PATHS = [...new Set([...GITLAB_SPEC_VERIFY_PATHS, ...GITHUB_SPEC_VERIFY_PATHS])];
+
+function specVerifyPathsFor(ci) {
+  return ci === 'github' ? GITHUB_SPEC_VERIFY_PATHS : GITLAB_SPEC_VERIFY_PATHS;
+}
+
 const VALID_CI_PROVIDERS = ['gitlab', 'github', 'none'];
 const VERIFY_OPENSPEC_SCRIPT = 'npx openspec validate --all --strict';
 
@@ -46,10 +66,11 @@ const log = {
 };
 
 function copyDir(src, dest, opts = {}) {
-  const { overwrite = true, skip = [] } = opts;
+  const { overwrite = true, skip = [], delete: deleteStale = false } = opts;
   if (!existsSync(src)) return;
   mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
+  const srcEntries = readdirSync(src);
+  for (const entry of srcEntries) {
     if (skip.includes(entry)) continue;
     const srcPath = join(src, entry);
     const destPath = join(dest, entry);
@@ -64,6 +85,17 @@ function copyDir(src, dest, opts = {}) {
       log.ok(destPath.replace(process.cwd() + '/', ''));
     }
   }
+
+  // Remove entries that exist in dest but no longer exist in src (e.g. skills
+  // removed by a kit `update`), keeping .cursor/.claude in sync with .agents/.
+  if (deleteStale && existsSync(dest)) {
+    for (const entry of readdirSync(dest)) {
+      if (skip.includes(entry) || srcEntries.includes(entry)) continue;
+      const destPath = join(dest, entry);
+      rmSync(destPath, { recursive: true, force: true });
+      log.warn(`removed stale: ${destPath.replace(process.cwd() + '/', '')}`);
+    }
+  }
 }
 
 function gitignoreLines(content) {
@@ -121,6 +153,59 @@ function hasOpenSpec(projectDir) {
   return existsSync(join(projectDir, 'openspec', 'config.yaml'));
 }
 
+function listActiveChanges(projectDir) {
+  const changesDir = join(projectDir, 'openspec', 'changes');
+  if (!existsSync(changesDir)) return [];
+  return readdirSync(changesDir)
+    .filter((name) => name !== 'archive' && statSync(join(changesDir, name)).isDirectory())
+    .sort();
+}
+
+function parseTasksProgress(changeDir) {
+  const tasksPath = join(changeDir, 'tasks.md');
+  if (!existsSync(tasksPath)) return null;
+  const content = readFileSync(tasksPath, 'utf-8');
+  const total = (content.match(/^\s*- \[[ xX]\]/gm) || []).length;
+  const done = (content.match(/^\s*- \[[xX]\]/gm) || []).length;
+  return { total, done };
+}
+
+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';
+}
+
+function readPipelineConfig(projectDir) {
+  const orchPath = join(projectDir, '.agents', 'orchestrator.yaml');
+  if (!existsSync(orchPath)) return null;
+  const content = readFileSync(orchPath, 'utf-8');
+  const requireReviewMatch = content.match(/require_spec_review:\s*(true|false)/);
+  const maxActiveMatch = content.match(/max_active_changes:\s*(\d+)/);
+  return {
+    requireSpecReview: requireReviewMatch ? requireReviewMatch[1] === 'true' : true,
+    maxActiveChanges: maxActiveMatch ? parseInt(maxActiveMatch[1], 10) : null,
+  };
+}
+
+// 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".
+function gitDiffTouchesGlob(projectDir, base, srcGlob) {
+  try {
+    const out = execSync(`git diff --name-only ${base}...HEAD -- "${srcGlob}"`, {
+      cwd: projectDir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf-8',
+    });
+    return out.trim().length > 0;
+  } catch {
+    return null;
+  }
+}
+
 function installOpenspecConfigExample(projectDir, profile, vars, force) {
   const src = resolveTemplate('openspec-config.yaml.example', profile);
   if (!existsSync(src)) return;
@@ -223,6 +308,43 @@ function installCi(projectDir, templateDir, ci, force) {
   }
 }
 
+function installSpecVerify(projectDir, templateDir, force, ci) {
+  const paths = specVerifyPathsFor(ci);
+  for (const rel of paths) {
+    const src = join(templateDir, rel);
+    const dest = join(projectDir, rel);
+    if (!existsSync(src)) continue;
+    if (!force && existsSync(dest)) {
+      log.warn(`skip (exists): ${rel}`);
+      continue;
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+    log.ok(rel);
+  }
+  const scripts = paths.filter((rel) => rel.startsWith('scripts/')).map((rel) => join(projectDir, rel));
+  try {
+    execSync(`chmod +x ${scripts.join(' ')}`);
+  } catch {}
+}
+
+function patchOrchestratorSpecVerify(projectDir) {
+  const orchPath = join(projectDir, '.agents', 'orchestrator.yaml');
+  if (!existsSync(orchPath)) return;
+
+  let content = readFileSync(orchPath, 'utf-8');
+  if (content.includes('spec-verify-blocking')) return;
+
+  const anchor = /^(\s*)- openspec-validate-strict\s*$/m;
+  if (!anchor.test(content)) {
+    log.warn('could not add spec-verify-blocking gate: openspec-validate-strict anchor not found in orchestrator.yaml');
+    return;
+  }
+  content = content.replace(anchor, '$1- openspec-validate-strict\n$1- spec-verify-blocking');
+  writeFileSync(orchPath, content);
+  log.ok('spec-verify-blocking gate added to orchestrator.yaml');
+}
+
 function patchOrchestratorVerifier(projectDir, pm) {
   const orchPath = join(projectDir, '.agents', 'orchestrator.yaml');
   if (!existsSync(orchPath)) return;
@@ -245,7 +367,7 @@ function patchOrchestratorVerifier(projectDir, pm) {
   writeFileSync(orchPath, content);
 }
 
-function printNextSteps(profile, projectDir, ci = 'github') {
+function printNextSteps(profile, projectDir, ci = 'github', specVerify = false) {
   const pm = detectPackageManager(projectDir);
   const openspecReady = hasOpenSpec(projectDir);
   const lines = [`${pc.bold('Next steps:')}`];
@@ -288,6 +410,19 @@ function printNextSteps(profile, projectDir, ci = 'github') {
     lines.push(`  ${pc.dim('Optional dev CI: include local .gitlab/agent-verify.yml (see kit templates/.gitlab-ci.starter.yml.example)')}`);
   }
 
+  if (specVerify) {
+    lines.push(`  ${pc.bold('AI Spec Verifier:')}`);
+    if (ci === 'gitlab') {
+      lines.push(`    - include ${pc.cyan(".gitlab/spec-verify.yml")} from your .gitlab-ci.yml`);
+      lines.push(`    - add CI/CD variables: ${pc.cyan('AMP_API_KEY')}, ${pc.cyan('GITLAB_VERIFIER_TOKEN')} (masked)`);
+      lines.push(`    - BLOCKED verdict fails the MR pipeline (uncomment allow_failure for warning-only rollout)`);
+    } else if (ci === 'github') {
+      lines.push(`    - workflow ${pc.cyan('.github/workflows/spec-verify.yml')} runs automatically on pull_request`);
+      lines.push(`    - add repo secret: ${pc.cyan('AMP_API_KEY')} (Settings → Secrets and variables → Actions)`);
+      lines.push(`    - BLOCKED verdict fails the PR pipeline (remove continue-on-error for warning-only rollout)`);
+    }
+  }
+
   console.log('\n' + lines.join('\n') + '\n');
 }
 
@@ -319,6 +454,7 @@ program
   .option('--name <name>', 'Project name (defaults to directory name)')
   .option('--force', 'Overwrite existing files', false)
   .option('--ci <provider>', 'CI provider: gitlab | github | none', 'github')
+  .option('--spec-verify', 'Install AI Spec Verifier blocking gate (GitLab or GitHub)', false)
   .action((opts) => {
     const projectDir = process.cwd();
     const projectName = opts.name || basename(projectDir);
@@ -344,7 +480,10 @@ program
     }
 
     log.title('Installing scripts/');
-    copyDir(join(templateDir, 'scripts'), join(projectDir, 'scripts'), { overwrite: opts.force });
+    copyDir(join(templateDir, 'scripts'), join(projectDir, 'scripts'), {
+      overwrite: opts.force,
+      skip: ['verify-specs.sh', 'post-mr-verdict.sh'],
+    });
     try {
       execSync(`chmod +x ${join(projectDir, 'scripts', 'sync-local-agent-skills.sh')}`);
     } catch {}
@@ -355,6 +494,15 @@ program
       injectVerifyScripts(projectDir, { pm });
     }
 
+    const specVerify = Boolean(opts.specVerify) && (ci === 'gitlab' || ci === 'github');
+    if (opts.specVerify && !specVerify) {
+      log.warn('--spec-verify requires --ci gitlab or --ci github — skipping AI Spec Verifier install');
+    }
+    if (specVerify) {
+      log.title('Installing AI Spec Verifier (opt-in)');
+      installSpecVerify(projectDir, templateDir, opts.force, ci);
+    }
+
     log.title('Installing root files');
     for (const f of ['AGENTS.md', 'CLAUDE.md']) {
       const src = resolveTemplate(f, profile);
@@ -380,6 +528,9 @@ program
       patchOrchestratorVerifier(projectDir, pm);
       log.ok('.agents/orchestrator.yaml');
     }
+    if (specVerify) {
+      patchOrchestratorSpecVerify(projectDir);
+    }
 
     log.title('OpenSpec config template');
     installOpenspecConfigExample(projectDir, profile, vars, opts.force);
@@ -389,7 +540,7 @@ program
 
     log.title('Done');
     log.ok(`agent-orchestrator-kit v${KIT_VERSION} installed`);
-    printNextSteps(profile, projectDir, ci);
+    printNextSteps(profile, projectDir, ci, specVerify);
   });
 
 program
@@ -414,6 +565,14 @@ program
       }
     }
 
+    for (const rel of KIT_OPTIN_PATHS) {
+      const src = join(templateDir, rel);
+      const dest = join(projectDir, rel);
+      if (!existsSync(src) || !existsSync(dest)) continue;
+      copyFileSync(src, dest);
+      log.ok(`${rel} (opt-in)`);
+    }
+
     log.ok(`Updated to v${KIT_VERSION}`);
     log.info('Run ./scripts/sync-local-agent-skills.sh to sync to local IDE');
   });
@@ -433,8 +592,8 @@ program
 
     if (syncCursor) {
       log.info('Syncing .agents/ → .cursor/');
-      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true });
-      copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true });
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.cursor', 'skills'), { overwrite: true, delete: true });
+      copyDir(join(projectDir, '.agents', 'rules'), join(projectDir, '.cursor', 'rules'), { overwrite: true, delete: true });
 
       const mcpExample = join(projectDir, '.agents', 'mcp.json.example');
       const mcpDest = join(projectDir, '.mcp.json');
@@ -446,7 +605,7 @@ program
 
     if (syncClaude) {
       log.info('Syncing .agents/ → .claude/');
-      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true });
+      copyDir(join(projectDir, '.agents', 'skills'), join(projectDir, '.claude', 'skills'), { overwrite: true, delete: true });
 
       const claudeMd = join(projectDir, 'CLAUDE.md');
       const claudeDir = join(projectDir, '.claude');
@@ -467,4 +626,98 @@ program
     log.warn('.cursor/, .claude/, .amp/ are local only — not committed to git');
   });
 
+program
+  .command('status')
+  .description('Show status of active OpenSpec changes (tasks progress, review verdict, archive readiness)')
+  .action(() => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator status');
+
+    const changes = listActiveChanges(projectDir);
+    if (changes.length === 0) {
+      log.info('No active changes');
+      return;
+    }
+
+    for (const name of changes) {
+      const changeDir = join(projectDir, 'openspec', 'changes', name);
+      const progress = parseTasksProgress(changeDir);
+      const verdict = parseReviewVerdict(changeDir);
+      const progressStr = progress ? `${progress.done}/${progress.total} tasks` : 'no tasks.md';
+      const verdictStr = verdict || 'none';
+      const readyToArchive = Boolean(progress && progress.total > 0 && progress.done === progress.total);
+
+      console.log(`\n${pc.bold(name)}`);
+      console.log(`  tasks:  ${progressStr}`);
+      console.log(`  review: ${verdictStr}`);
+      if (readyToArchive) log.ok('ready to archive');
+    }
+    console.log('');
+  });
+
+program
+  .command('gate-check [change-name]')
+  .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')
+  .action((changeName, opts) => {
+    const projectDir = process.cwd();
+    log.title('agent-orchestrator gate-check');
+
+    const config = readPipelineConfig(projectDir);
+    if (!config) {
+      log.info('.agents/orchestrator.yaml not found — nothing to gate');
+      return;
+    }
+
+    if (!config.requireSpecReview) {
+      log.ok('review not required (pipeline.require_spec_review: false)');
+      return;
+    }
+
+    const touchesSrc = gitDiffTouchesGlob(projectDir, opts.base, opts.srcGlob);
+    if (touchesSrc === false) {
+      log.ok(`no changes under ${opts.srcGlob} — nothing to gate`);
+      return;
+    }
+    if (touchesSrc === null) {
+      log.warn('could not compute git diff — skipping gate-check');
+      return;
+    }
+
+    const changes = listActiveChanges(projectDir);
+    if (config.maxActiveChanges && changes.length > config.maxActiveChanges) {
+      log.warn(`${changes.length} active changes exceed pipeline.max_active_changes (${config.maxActiveChanges})`);
+    }
+
+    let target = changeName;
+    if (!target) {
+      if (changes.length === 0) {
+        log.warn(`${opts.srcGlob} changed but no active OpenSpec change found — cannot verify review gate`);
+        return;
+      }
+      target = changes
+        .map((name) => ({ name, mtime: statSync(join(projectDir, 'openspec', 'changes', name)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime)[0].name;
+      log.info(`auto-selected change: ${target} (override: gate-check <name>)`);
+    }
+
+    const changeDir = join(projectDir, 'openspec', 'changes', target);
+    if (!existsSync(changeDir)) {
+      log.err(`change not found: ${target}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    const verdict = parseReviewVerdict(changeDir);
+    if (verdict && /^APPROVE/i.test(verdict)) {
+      log.ok(`review gate passed — ${target}: APPROVE`);
+      return;
+    }
+
+    log.err(`review gate failed — change "${target}" has ${verdict ? `verdict "${verdict}"` : 'no review.md'}`);
+    log.err(`Run /opsx:review ${target} and get an explicit APPROVE before apply/merge.`);
+    process.exitCode = 1;
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven pipeline with OpenSpec integration",
   "keywords": [
     "ai-agent",

package/templates/.agents/skills/agent-orchestration/SKILL.md

@@ -74,6 +74,8 @@ Before apply, check `.agents/orchestrator.yaml`:
 
 If Request Changes — fix artifacts, re-run `/opsx:review`.
 
+This is no longer only a chat convention: `agent-orchestrator-kit gate-check` runs in CI (both `agent-verify.yml` fragments) and fails the pipeline if `src/` changed without an approved `review.md` — a forgotten or skipped review is caught at merge time, not just at apply time.
+
 ### apply → verify
 Exit Implementer when:
 - All `tasks.md` boxes `[x]`
@@ -91,7 +93,7 @@ After PR merged + CI green:
 
 **Start of each session:**
 1. Announce role: "Starting Spec Reviewer session for change: <name>"
-2. Check `openspec list` — confirm active change limit (`max_active_changes` in orchestrator.yaml)
+2. Run `agent-orchestrator-kit status` (or `openspec list`) — confirm active change limit (`max_active_changes` in orchestrator.yaml) and see task/review progress for every active change at a glance
 3. Read `orchestrator.yaml` for project config and review gate
 
 **During session:**
@@ -135,7 +137,8 @@ At start of new session: read relevant entities to restore context without re-ex
 - [ ] explicit **Approve** received before apply (when `require_spec_review: true`)
 - [ ] `review.md` with `Verdict: APPROVE` exists (when review required)
 - [ ] all tasks `[x]` + build OK before PR
-- [ ] `/opsx:archive` run after merge
+- [ ] `agent-orchestrator-kit gate-check` passes locally before pushing (mirrors the CI gate)
+- [ ] `/opsx:archive` run after merge — `agent-orchestrator-kit status` shows "ready to archive"
 
 ## Anti-patterns
 

package/templates/.github/workflows/agent-verify.yml

@@ -10,6 +10,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-node@v4
         with:
@@ -45,6 +47,9 @@ jobs:
       - name: OpenSpec validate
         run: npx openspec validate --all --strict
 
+      - name: Gate check (review gate)
+        run: npx agent-orchestrator-kit gate-check --base "${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || 'HEAD~1' }}"
+
       - name: Lint (npm)
         if: steps.pm.outputs.manager == 'npm'
         run: npm run lint --if-present

package/templates/.github/workflows/spec-verify.yml

@@ -0,0 +1,82 @@
+name: spec-verify
+
+# ──────────────────────────────────────────────────────────────
+# AI Spec Verifier — blocking gate on pull requests.
+# Verifies that changed src/ code complies with openspec/specs/
+# via Amp CLI, posts a PASS / BLOCKED comment to the PR, and
+# fails the pipeline on a BLOCKED verdict.
+#
+# Installed by agent-orchestrator-kit (init --ci github --spec-verify).
+#
+# Required repo secret (Settings → Secrets and variables → Actions):
+#   AMP_API_KEY — Amp API key
+# GITHUB_TOKEN is provided automatically by Actions.
+#
+# Phase 1 (warning-only rollout): uncomment `continue-on-error: true` on the
+# "Evaluate verdict" step below, then remove it once the team trusts the
+# verdicts (Phase 2, blocking by default).
+# ──────────────────────────────────────────────────────────────
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  spec-verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install Amp CLI
+        run: npm install -g @sourcegraph/amp@latest
+
+      - name: Make scripts executable
+        run: chmod +x scripts/verify-specs.sh scripts/post-pr-verdict-github.sh
+
+      - name: Run spec verifier
+        env:
+          AMP_API_KEY: ${{ secrets.AMP_API_KEY }}
+          # verify-specs.sh is shared with the GitLab variant and reads this
+          # variable name as the diff base — reused as-is, not GitHub-specific.
+          CI_MERGE_REQUEST_DIFF_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: bash scripts/verify-specs.sh
+
+      - name: Post PR comment
+        if: always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: bash scripts/post-pr-verdict-github.sh
+
+      - name: Upload verifier artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: spec-verify-artifacts
+          path: |
+            artifacts/verdict.json
+            artifacts/verifier-prompt.md
+          retention-days: 7
+          if-no-files-found: ignore
+
+      - name: Evaluate verdict
+        # Phase 1 (warning-only rollout): uncomment the next line to let the
+        # pipeline stay green while the team builds trust in verdicts.
+        # continue-on-error: true
+        run: |
+          PASS=$(python3 -c "import json; v=json.load(open('artifacts/verdict.json')); print(str(v.get('pass', True)).lower())")
+          if [ "$PASS" != "true" ]; then
+            echo "Spec verifier found errors. See PR comment for details."
+            exit 1
+          fi
+          echo "Spec verification passed."

package/templates/.gitlab/agent-verify.yml

@@ -1,5 +1,7 @@
 .agent-verify-base:
   image: node:20
+  variables:
+    GIT_DEPTH: 0
   before_script:
     - |
       if [ -f pnpm-lock.yaml ]; then
@@ -15,6 +17,7 @@
       fi
   script:
     - npx openspec validate --all --strict
+    - npx agent-orchestrator-kit gate-check --base "${CI_MERGE_REQUEST_DIFF_BASE_SHA:-HEAD~1}"
     - |
       run_pm_script() {
         local name=$1

package/templates/.gitlab/spec-verify.yml

@@ -0,0 +1,47 @@
+# ──────────────────────────────────────────────────────────────
+# AI Spec Verifier — blocking gate on merge requests.
+# Verifies that changed src/ code complies with openspec/specs/
+# via Amp CLI, posts a PASS / BLOCKED comment to the MR, and
+# fails the pipeline on a BLOCKED verdict.
+#
+# Installed by agent-orchestrator-kit (init --ci gitlab --spec-verify).
+# Include from .gitlab-ci.yml:
+#   include:
+#     - local: '.gitlab/spec-verify.yml'
+#
+# Required CI/CD variables (Settings → CI/CD → Variables):
+#   AMP_API_KEY           — Amp API key (masked, protected)
+#   GITLAB_VERIFIER_TOKEN — Project token with api scope (masked)
+# ──────────────────────────────────────────────────────────────
+.spec-verify-base:
+  image: node:20
+  script:
+    - apt-get update -qq && apt-get install -y -qq python3 curl git > /dev/null
+    - npm install -g @sourcegraph/amp@latest
+    - chmod +x scripts/verify-specs.sh scripts/post-mr-verdict.sh
+    - bash scripts/verify-specs.sh
+    - bash scripts/post-mr-verdict.sh
+    # Evaluate verdict — exit 1 if verifier says fail
+    - |
+      PASS=$(python3 -c "import json; v=json.load(open('artifacts/verdict.json')); print(str(v.get('pass',True)).lower())")
+      if [ "$PASS" != "true" ]; then
+        echo "Spec verifier found errors. See MR comment for details."
+        exit 1
+      fi
+      echo "Spec verification passed."
+  artifacts:
+    paths:
+      - artifacts/verdict.json
+      - artifacts/verifier-prompt.md
+    expire_in: 7 days
+    when: always
+
+spec-verify:
+  extends: .spec-verify-base
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        - "src/**/*"
+  # Phase 1 (warning-only rollout): uncomment the next line to let
+  # the pipeline stay green while the team builds trust in verdicts.
+  # allow_failure: true

package/templates/.gitlab-ci.starter.yml.example

@@ -1,5 +1,7 @@
 include:
   - local: '.gitlab/agent-verify.yml'
+  # AI Spec Verifier (opt-in — installed via init --ci gitlab --spec-verify):
+  # - local: '.gitlab/spec-verify.yml'
 
 agent-verify:
   extends: .agent-verify-base

package/templates/AGENTS.md

@@ -26,6 +26,10 @@ Never mix phases in one chat — this is the single most important rule.
 
 Verifier runs on **GitHub Actions** (default) or **GitLab** via `prebuild` → `verify:openspec` when using `init --ci gitlab`. GitLab projects do not use `.github/workflows/`.
 
+With `init --ci gitlab --spec-verify` or `init --ci github --spec-verify`, an **AI Spec Verifier** also runs on MRs/PRs changing `src/`: an Amp agent checks the changed code against `openspec/specs/` and a **BLOCKED verdict fails the pipeline** (gate `spec-verify-blocking` in `.agents/orchestrator.yaml`).
+
+Both CI fragments also run `agent-orchestrator-kit gate-check` — a deterministic check that fails the pipeline when `src/` changed but the active change has no `review.md` with `Verdict: APPROVE` (when `require_spec_review: true`). Run `agent-orchestrator-kit status` at the start of any session to see task progress, review verdict, and archive readiness for every active change without querying `openspec` per change.
+
 ## Hard Rules
 
 - **One active change per developer** at a time.
@@ -40,9 +44,9 @@ Verifier runs on **GitHub Actions** (default) or **GitLab** via `prebuild` → `
 |------------|------|
 | explore → propose | Decision brief written; change name chosen |
 | propose → review | `openspec validate --strict` passes ✓ |
-| review → apply | Reviewer writes explicit **Approve** |
+| review → apply | Reviewer writes explicit **Approve** — enforced in CI by `gate-check` |
 | apply → verify | All `tasks.md` checkboxes `[x]`; local build OK |
-| verify → archive | CI green; PR merged |
+| verify → archive | CI green; PR merged — check `agent-orchestrator status` for "ready to archive" |
 
 ## Context to Pin per Role
 

package/templates/scripts/post-mr-verdict.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────
+# Posts spec verifier verdict as a GitLab MR comment.
+#
+# Installed by agent-orchestrator-kit (init --ci gitlab --spec-verify).
+#
+# Usage:  ./scripts/post-mr-verdict.sh
+# Env:    CI_API_V4_URL, CI_PROJECT_ID, CI_MERGE_REQUEST_IID,
+#         GITLAB_VERIFIER_TOKEN (CI/CD variable, masked)
+#
+# Security: GITLAB_VERIFIER_TOKEN is a project access token with
+# api scope. It is NEVER logged or echoed.
+# ──────────────────────────────────────────────────────────────
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VERDICT_FILE="$ROOT/artifacts/verdict.json"
+
+if [ ! -f "$VERDICT_FILE" ]; then
+  echo "No verdict file found — skipping MR comment."
+  exit 0
+fi
+
+if [ -z "${CI_API_V4_URL:-}" ] || [ -z "${CI_PROJECT_ID:-}" ] || [ -z "${CI_MERGE_REQUEST_IID:-}" ]; then
+  echo "Not running in MR context — skipping MR comment."
+  exit 0
+fi
+
+if [ -z "${GITLAB_VERIFIER_TOKEN:-}" ]; then
+  echo "GITLAB_VERIFIER_TOKEN not set — skipping MR comment."
+  exit 0
+fi
+
+# Parse verdict
+PASS=$(python3 -c "import json,sys; v=json.load(open('$VERDICT_FILE')); print(str(v.get('pass',True)).lower())")
+SCORE=$(python3 -c "import json,sys; v=json.load(open('$VERDICT_FILE')); print(v.get('score',0))")
+SUMMARY=$(python3 -c "import json,sys; v=json.load(open('$VERDICT_FILE')); print(v.get('summary',''))")
+SKIPPED=$(python3 -c "import json,sys; v=json.load(open('$VERDICT_FILE')); print(str(v.get('skipped',False)).lower())")
+
+if [ "$SKIPPED" = "true" ]; then
+  ICON="⏭️"
+  STATUS="SKIPPED"
+elif [ "$PASS" = "true" ]; then
+  ICON="✅"
+  STATUS="PASS"
+else
+  ICON="❌"
+  STATUS="BLOCKED"
+fi
+
+# Build findings table
+FINDINGS_TABLE=$(python3 <<'PYEOF'
+import json, sys
+
+with open("artifacts/verdict.json") as f:
+    v = json.load(f)
+
+findings = v.get("findings", [])
+if not findings:
+    print("_No findings._")
+    sys.exit(0)
+
+severity_icons = {"error": "🔴", "warning": "🟡", "info": "🔵"}
+
+print("| | Severity | Spec | Requirement | Message | File |")
+print("|---|----------|------|-------------|---------|------|")
+for f in findings:
+    icon = severity_icons.get(f.get("severity", "info"), "⚪")
+    sev = f.get("severity", "—")
+    spec = f.get("spec", "—")
+    req = f.get("requirement", "—")
+    msg = f.get("message", "—")
+    file = f.get("file", "—")
+    line = f.get("line")
+    if line:
+        file = f"{file}:{line}"
+    print(f"| {icon} | {sev} | {spec} | {req} | {msg} | {file} |")
+PYEOF
+)
+
+# Build comment body
+COMMENT_BODY="## ${ICON} Spec Verifier — ${STATUS}
+
+**Score:** ${SCORE}/100
+**Verdict:** ${STATUS}
+
+### Summary
+${SUMMARY}
+
+### Findings
+${FINDINGS_TABLE}
+
+---
+_AI Spec Verifier • agent-orchestrator-kit • Pipeline: ${CI_PIPELINE_ID:-local}_"
+
+# Escape for JSON
+COMMENT_JSON=$(python3 -c "
+import json, sys
+body = sys.stdin.read()
+print(json.dumps({'body': body}))
+" <<< "$COMMENT_BODY")
+
+# Post to GitLab API
+# Security: token is passed via header, never logged
+HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+  --request POST \
+  --header "PRIVATE-TOKEN: ${GITLAB_VERIFIER_TOKEN}" \
+  --header "Content-Type: application/json" \
+  --data "$COMMENT_JSON" \
+  "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/merge_requests/${CI_MERGE_REQUEST_IID}/notes")
+
+if [ "$HTTP_STATUS" -ge 200 ] && [ "$HTTP_STATUS" -lt 300 ]; then
+  echo "MR comment posted successfully (HTTP $HTTP_STATUS)"
+else
+  echo "Failed to post MR comment (HTTP $HTTP_STATUS)"
+fi

package/templates/scripts/post-pr-verdict-github.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────
+# Posts spec verifier verdict as a GitHub PR comment via gh CLI.
+#
+# Installed by agent-orchestrator-kit (init --ci github --spec-verify).
+#
+# Usage:  ./scripts/post-pr-verdict-github.sh
+# Env:    GH_TOKEN / GITHUB_TOKEN — provided by GitHub Actions
+#         GITHUB_EVENT_PATH, GITHUB_REPOSITORY, GITHUB_RUN_ID — Actions runtime
+#         PR_NUMBER — optional override, auto-detected from the pull_request event otherwise
+#
+# Security: GH_TOKEN/GITHUB_TOKEN is never logged or echoed.
+# ──────────────────────────────────────────────────────────────
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VERDICT_FILE="$ROOT/artifacts/verdict.json"
+
+if [ ! -f "$VERDICT_FILE" ]; then
+  echo "No verdict file found — skipping PR comment."
+  exit 0
+fi
+
+TOKEN="${GH_TOKEN:-${GITHUB_TOKEN:-}}"
+if [ -z "$TOKEN" ]; then
+  echo "GH_TOKEN/GITHUB_TOKEN not set — skipping PR comment."
+  exit 0
+fi
+
+if ! command -v gh &>/dev/null; then
+  echo "gh CLI not found — skipping PR comment."
+  exit 0
+fi
+
+PR_NUMBER="${PR_NUMBER:-}"
+if [ -z "$PR_NUMBER" ] && [ -n "${GITHUB_EVENT_PATH:-}" ] && [ -f "$GITHUB_EVENT_PATH" ]; then
+  PR_NUMBER=$(python3 -c "
+import json
+try:
+    data = json.load(open('$GITHUB_EVENT_PATH'))
+    print(data.get('pull_request', {}).get('number', ''))
+except Exception:
+    print('')
+" 2>/dev/null || true)
+fi
+
+if [ -z "$PR_NUMBER" ]; then
+  echo "Not running in a pull_request context — skipping PR comment."
+  exit 0
+fi
+
+export GH_TOKEN="$TOKEN"
+
+PASS=$(python3 -c "import json; v=json.load(open('$VERDICT_FILE')); print(str(v.get('pass',True)).lower())")
+SCORE=$(python3 -c "import json; v=json.load(open('$VERDICT_FILE')); print(v.get('score',0))")
+SUMMARY=$(python3 -c "import json; v=json.load(open('$VERDICT_FILE')); print(v.get('summary',''))")
+SKIPPED=$(python3 -c "import json; v=json.load(open('$VERDICT_FILE')); print(str(v.get('skipped',False)).lower())")
+
+if [ "$SKIPPED" = "true" ]; then
+  ICON="⏭️"
+  STATUS="SKIPPED"
+elif [ "$PASS" = "true" ]; then
+  ICON="✅"
+  STATUS="PASS"
+else
+  ICON="❌"
+  STATUS="BLOCKED"
+fi
+
+# Build findings table
+FINDINGS_TABLE=$(python3 <<'PYEOF'
+import json, sys
+
+with open("artifacts/verdict.json") as f:
+    v = json.load(f)
+
+findings = v.get("findings", [])
+if not findings:
+    print("_No findings._")
+    sys.exit(0)
+
+severity_icons = {"error": "🔴", "warning": "🟡", "info": "🔵"}
+
+print("| | Severity | Spec | Requirement | Message | File |")
+print("|---|----------|------|-------------|---------|------|")
+for f in findings:
+    icon = severity_icons.get(f.get("severity", "info"), "⚪")
+    sev = f.get("severity", "—")
+    spec = f.get("spec", "—")
+    req = f.get("requirement", "—")
+    msg = f.get("message", "—")
+    file = f.get("file", "—")
+    line = f.get("line")
+    if line:
+        file = f"{file}:{line}"
+    print(f"| {icon} | {sev} | {spec} | {req} | {msg} | {file} |")
+PYEOF
+)
+
+# Build comment body
+COMMENT_BODY="## ${ICON} Spec Verifier — ${STATUS}
+
+**Score:** ${SCORE}/100
+**Verdict:** ${STATUS}
+
+### Summary
+${SUMMARY}
+
+### Findings
+${FINDINGS_TABLE}
+
+---
+_AI Spec Verifier • agent-orchestrator-kit • Run: ${GITHUB_RUN_ID:-local}_"
+
+TMP_BODY_FILE=$(mktemp)
+trap 'rm -f "$TMP_BODY_FILE"' EXIT
+echo "$COMMENT_BODY" > "$TMP_BODY_FILE"
+
+GH_REPO_FLAG=()
+if [ -n "${GITHUB_REPOSITORY:-}" ]; then
+  GH_REPO_FLAG=(--repo "$GITHUB_REPOSITORY")
+fi
+
+# Security: token is passed via GH_TOKEN env var, never logged
+if gh pr comment "$PR_NUMBER" "${GH_REPO_FLAG[@]}" --body-file "$TMP_BODY_FILE" >/dev/null 2>&1; then
+  echo "PR comment posted successfully"
+else
+  echo "Failed to post PR comment"
+fi

package/templates/scripts/verify-specs.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────
+# AI Spec Verifier — collects changed src/ files, concatenates
+# openspec/specs/, builds a prompt, calls Amp CLI, and produces
+# artifacts/verdict.json.
+#
+# Installed by agent-orchestrator-kit (init --ci gitlab --spec-verify).
+#
+# Usage:  ./scripts/verify-specs.sh
+# Env:    CI_MERGE_REQUEST_DIFF_BASE_SHA (GitLab CI provides it)
+#         AMP_API_KEY — Amp API key (CI/CD variable, masked)
+#         SRC_GLOB    — source path filter (default: src/)
+#
+# Security: this script NEVER logs tokens, keys, or .env content.
+# ──────────────────────────────────────────────────────────────
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ARTIFACTS_DIR="$ROOT/artifacts"
+SPECS_DIR="$ROOT/openspec/specs"
+PROJECT_CONFIG="$ROOT/openspec/config.yaml"
+VERDICT_FILE="$ARTIFACTS_DIR/verdict.json"
+PROMPT_FILE="$ARTIFACTS_DIR/verifier-prompt.md"
+SRC_GLOB="${SRC_GLOB:-src/}"
+
+mkdir -p "$ARTIFACTS_DIR"
+
+write_skipped_verdict() {
+  local summary="$1"
+  cat > "$VERDICT_FILE" <<EOF
+{
+  "pass": true,
+  "score": 100,
+  "skipped": true,
+  "summary": "${summary}",
+  "findings": []
+}
+EOF
+}
+
+# ── 1. Collect changed source files ──────────────────────────
+BASE_SHA="${CI_MERGE_REQUEST_DIFF_BASE_SHA:-HEAD~1}"
+
+CHANGED_FILES=$(git diff --name-only "$BASE_SHA"...HEAD -- "$SRC_GLOB" || true)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "No ${SRC_GLOB} files changed — skipping spec verification."
+  write_skipped_verdict "No ${SRC_GLOB} files changed — verification skipped."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES"
+
+# ── 2. Collect all spec files ────────────────────────────────
+SPEC_FILES=$(find "$SPECS_DIR" -name '*.md' -type f 2>/dev/null || true)
+
+if [ -z "$SPEC_FILES" ]; then
+  echo "No spec files found in $SPECS_DIR — skipping."
+  write_skipped_verdict "No spec files found — verification skipped."
+  exit 0
+fi
+
+# ── 3. Build spec content block ──────────────────────────────
+SPECS_CONTENT=""
+for spec_file in $SPEC_FILES; do
+  rel_path="${spec_file#$ROOT/}"
+  SPECS_CONTENT+="
+--- FILE: $rel_path ---
+$(cat "$spec_file")
+"
+done
+
+# ── 4. Build changed file content block ──────────────────────
+# Security: skip .env, secrets, tokens, keys from content
+CHANGED_CONTENT=""
+for file in $CHANGED_FILES; do
+  full_path="$ROOT/$file"
+  if [ -f "$full_path" ]; then
+    case "$file" in
+      *.env*|*secret*|*token*|*key*|*.pem|*.p12) continue ;;
+    esac
+    CHANGED_CONTENT+="
+--- FILE: $file ---
+$(cat "$full_path")
+"
+  fi
+done
+
+# ── 5. Project context from openspec/config.yaml ─────────────
+PROJECT_CONTEXT=""
+if [ -f "$PROJECT_CONFIG" ]; then
+  PROJECT_CONTEXT="
+## Project Context (openspec/config.yaml)
+
+$(cat "$PROJECT_CONFIG")
+"
+fi
+
+# ── 6. Build verifier prompt ─────────────────────────────────
+cat > "$PROMPT_FILE" <<PROMPT
+You are a SPEC VERIFIER.
+Your job: verify that changed source code complies with project specifications.
+${PROJECT_CONTEXT}
+## Instructions
+1. Read ALL specs below carefully.
+2. Read ALL changed source files below.
+3. For each changed file, check if it relates to any spec requirement.
+4. Verify that every relevant requirement/scenario from specs is satisfied.
+5. Respect project conventions from the project context above, if provided.
+
+## Output
+Return ONLY valid JSON (no markdown fences, no extra text) with this structure:
+{
+  "pass": true|false,
+  "score": 0-100,
+  "summary": "Brief summary",
+  "findings": [
+    {
+      "severity": "error"|"warning"|"info",
+      "spec": "spec file path",
+      "requirement": "requirement name from spec",
+      "message": "what is wrong or missing",
+      "file": "affected source file",
+      "line": null
+    }
+  ]
+}
+
+Rules for verdict:
+- "pass": false if ANY finding has severity "error"
+- "pass": true if only "warning" or "info" findings, or no findings
+- "score": 100 minus 10 per error, 3 per warning (minimum 0)
+- If a changed file has no related spec, add an "info" finding noting it
+
+## SPECIFICATIONS
+
+${SPECS_CONTENT}
+
+## CHANGED SOURCE FILES
+
+${CHANGED_CONTENT}
+PROMPT
+
+echo "Verifier prompt built ($(wc -c < "$PROMPT_FILE") bytes)"
+
+# ── 7. Call Amp CLI ──────────────────────────────────────────
+if ! command -v amp &>/dev/null; then
+  echo "amp CLI not found — writing fallback verdict."
+  write_skipped_verdict "amp CLI not installed — verification skipped."
+  exit 0
+fi
+
+if [ -z "${AMP_API_KEY:-}" ]; then
+  echo "AMP_API_KEY not set — skipping Amp call."
+  write_skipped_verdict "AMP_API_KEY not set in CI — Amp verification skipped."
+  exit 0
+fi
+
+echo "Running Amp verifier agent..."
+export AMP_API_KEY
+AMP_RESPONSE=$(amp -x < "$PROMPT_FILE" 2>/dev/null || true)
+
+# ── 8. Extract JSON from response ────────────────────────────
+# The response might contain markdown fences — strip them
+CLEAN_JSON=$(echo "$AMP_RESPONSE" | sed -n '/^{/,/^}/p' | head -200)
+
+if echo "$CLEAN_JSON" | python3 -m json.tool > /dev/null 2>&1; then
+  echo "$CLEAN_JSON" > "$VERDICT_FILE"
+else
+  echo "Failed to parse verifier response as JSON."
+  echo "Raw response (first 500 chars):"
+  echo "$AMP_RESPONSE" | head -c 500
+  # Write a cautious pass — don't block on verifier infrastructure failure
+  cat > "$VERDICT_FILE" <<'EOF'
+{
+  "pass": true,
+  "score": 50,
+  "skipped": false,
+  "summary": "Verifier did not return valid JSON — result inconclusive.",
+  "findings": [
+    {
+      "severity": "warning",
+      "spec": "N/A",
+      "requirement": "N/A",
+      "message": "Verifier agent response was not valid JSON. Manual review recommended.",
+      "file": "N/A",
+      "line": null
+    }
+  ]
+}
+EOF
+fi
+
+echo "Verdict written to $VERDICT_FILE"
+cat "$VERDICT_FILE" | python3 -m json.tool 2>/dev/null || cat "$VERDICT_FILE"