agent-orchestrator-kit 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
+- **`init --ci gitlab|github|none`** — CI provider flag (default: `github`)
+- **GitLab verify** — `.gitlab/agent-verify.yml` fragment with multi-PM detect (npm/yarn/pnpm)
+- **PM-aware prebuild hook** — `verify:openspec` + `prebuild` injection on `--ci gitlab` (zero DevOps config via `npm run build`)
+- **Starter example** — `templates/.gitlab-ci.starter.yml.example` for early push before DevOps owns root CI
+- **OpenSpec specs** — `gitlab-consumer-verify`, `kit-ci-verify` synced to `openspec/specs/`
+
+### Changed
+- **`update`** refreshes `.gitlab/agent-verify.yml` via `KIT_MANAGED_PATHS`
+- **README + AGENTS.md** — GitLab verifier path documented (prebuild hook, not GitHub Actions)
+- **`printNextSteps`** — GitLab hints for `--ci gitlab` users
+
 ## [0.1.4] - 2026-06-27
 
 ### Added
@@ -49,6 +75,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.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
 [0.1.2]: https://github.com/makshc2/agent-orchestrator-kit/compare/v0.1.1...v0.1.2

package/README.md

@@ -64,6 +64,24 @@ npx agent-orchestrator-kit init \
   --lang uk
 ```
 
+For GitLab-hosted projects (verify via `prebuild` hook — no GitHub Actions):
+
+```bash
+npx agent-orchestrator-kit init --ci gitlab
+```
+
+This installs `.gitlab/agent-verify.yml`, injects `verify:openspec` and PM-aware `prebuild` into `package.json`. When DevOps runs `npm run build` (or yarn/pnpm build), npm lifecycle runs `prebuild` first → `npx openspec validate --all --strict` executes automatically.
+
+Optional dev-controlled CI before DevOps setup: copy `templates/.gitlab-ci.starter.yml.example` from the kit to `.gitlab-ci.yml` and adjust stages as needed.
+
+Skip CI files entirely:
+
+```bash
+npx agent-orchestrator-kit init --ci none
+```
+
+Default remains GitHub Actions (`--ci github`).
+
 ### Sync to local IDEs
 
 After init (and after every update):
@@ -80,7 +98,9 @@ This copies `.agents/` to your local IDE directories (not committed to git).
 your-project/
 ├── AGENTS.md
 ├── CLAUDE.md
-├── .github/workflows/agent-verify.yml   # CI: openspec validate + lint + build
+├── .github/workflows/agent-verify.yml   # CI (default --ci github)
+├── .gitlab/agent-verify.yml             # CI fragment (--ci gitlab)
+├── .gitlab/spec-verify.yml              # AI Spec Verifier (--spec-verify, opt-in)
 ├── .agents/
 │   ├── orchestrator.yaml
 │   ├── mcp.json.example                 # Cursor MCP template
@@ -96,7 +116,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   # (--spec-verify, opt-in)
 ```
 
 ### Included in kit
@@ -106,7 +127,8 @@ 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` (openspec validate, lint, build, test) |
+| CI | `agent-verify.yml` — GitHub (default) or GitLab fragment + `prebuild` hook |
+| AI Spec Verifier | `spec-verify.yml` + verifier scripts — GitLab opt-in (`--spec-verify`) |
 | MCP templates | Memory MCP for Cursor and Amp |
 
 ### Not included (install separately)
@@ -285,7 +307,7 @@ npm run lint    # must pass
 
 ### Role 5: Verifier — CI (automatic)
 
-Installed at `.github/workflows/agent-verify.yml`:
+**GitHub (default `--ci github`):** installed at `.github/workflows/agent-verify.yml`:
 
 ```yaml
 - run: npx openspec validate --all --strict
@@ -294,8 +316,54 @@ Installed at `.github/workflows/agent-verify.yml`:
 - run: npm test --if-present
 ```
 
+**GitLab (`--ci gitlab`):** verify runs through the package manager build lifecycle — no GitHub Actions:
+
+```json
+"verify:openspec": "npx openspec validate --all --strict",
+"prebuild": "npm run verify:openspec"
+```
+
+When CI or a developer runs `npm run build`, npm executes `prebuild` first. DevOps pipelines that already call `npm run build` get OpenSpec validate with zero config changes.
+
+Optional: include `.gitlab/agent-verify.yml` in `.gitlab-ci.yml` for full lint/build/test verify before DevOps owns the root CI file. See kit `templates/.gitlab-ci.starter.yml.example`.
+
 Blocks merge if any gate fails.
 
+#### AI Spec Verifier (GitLab, opt-in)
+
+```bash
+npx agent-orchestrator-kit init --ci gitlab --spec-verify
+```
+
+Installs an AI verification layer on top of the deterministic gates: on every merge 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, and **fails the pipeline on BLOCKED** — specs become an enforceable merge contract, not just documentation.
+
+Installed files:
+
+| 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 |
+
+The flag also adds `spec-verify-blocking` to `roles.verifier.gates` in `.agents/orchestrator.yaml`.
+
+Setup after install:
+
+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).
+
+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` in `.gitlab/spec-verify.yml` to keep the pipeline green while the team builds trust in verdicts, then remove it to enforce blocking (Phase 2).
+
+`update` refreshes the three spec-verify files only in projects that already installed them — the feature stays opt-in.
+
 ---
 
 ### Archive — `/opsx:archive`
@@ -429,6 +497,8 @@ npx agent-orchestrator-kit init [options]
   --profile <name>   Stack profile: generic | vue3 | node | mvp
   --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 only)
   --force            Overwrite existing files
 
 npx agent-orchestrator-kit update
@@ -470,6 +540,22 @@ openspec/                # Committed — spec-driven workflow
 
 ## Changelog
 
+### 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
+- `.gitlab/agent-verify.yml` template + starter example
+- `update` refreshes GitLab fragment; docs for GitLab verifier path
+
+### 0.1.4
+- Kit repo CI — `.github/workflows/agent-verify.yml`
+- OpenSpec devDependency for local and CI validation
+
 ### 0.1.3
 - Fix gitignore dedup (exact line match, not substring)
 - Add `.claude` to gitignore on init

package/bin/agent-orchestrator.js

@@ -28,9 +28,20 @@ const KIT_MANAGED_PATHS = [
   '.agents/rules',
   ...KIT_SKILL_DIRS.map((s) => `.agents/skills/${s}`),
   '.github/workflows/agent-verify.yml',
+  '.gitlab/agent-verify.yml',
   'scripts/sync-local-agent-skills.sh',
 ];
 
+// Opt-in files: refreshed by `update` only when already present in the project
+const KIT_OPTIN_PATHS = [
+  '.gitlab/spec-verify.yml',
+  'scripts/verify-specs.sh',
+  'scripts/post-mr-verdict.sh',
+];
+
+const VALID_CI_PROVIDERS = ['gitlab', 'github', 'none'];
+const VERIFY_OPENSPEC_SCRIPT = 'npx openspec validate --all --strict';
+
 const GITIGNORE_LINES = ['.cursor', '.cursor/memory.json', '.amp/settings.json', '.claude'];
 
 const log = {
@@ -146,6 +157,114 @@ function installOpenspecConfigExample(projectDir, profile, vars, force) {
   }
 }
 
+function resolveCiProvider(ci) {
+  if (VALID_CI_PROVIDERS.includes(ci)) return ci;
+  log.warn(`Unknown --ci value "${ci}". Valid: ${VALID_CI_PROVIDERS.join(', ')}. Using github.`);
+  return 'github';
+}
+
+function injectVerifyScripts(projectDir, { pm }) {
+  const pkgPath = join(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    log.warn('skip script injection: no package.json');
+    return;
+  }
+
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+  if (!pkg.scripts) pkg.scripts = {};
+
+  if (pkg.scripts['verify:openspec']) {
+    log.warn('skip (exists): verify:openspec script');
+  } else {
+    pkg.scripts['verify:openspec'] = VERIFY_OPENSPEC_SCRIPT;
+    log.ok('verify:openspec script added');
+  }
+
+  const runCmd = `${pm} run verify:openspec`;
+  const existingPrebuild = pkg.scripts.prebuild;
+
+  if (existingPrebuild && existingPrebuild.includes('verify:openspec')) {
+    log.warn('skip (exists): prebuild already chains verify:openspec');
+  } else if (existingPrebuild) {
+    pkg.scripts.prebuild = `${runCmd} && ${existingPrebuild}`;
+    log.ok('prebuild script chained');
+  } else {
+    pkg.scripts.prebuild = runCmd;
+    log.ok('prebuild script added');
+  }
+
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+}
+
+function installCi(projectDir, templateDir, ci, force) {
+  if (ci === 'none') {
+    log.info('CI install skipped (--ci none)');
+    return;
+  }
+
+  if (ci === 'github') {
+    const githubWorkflow = join(templateDir, '.github', 'workflows', 'agent-verify.yml');
+    const githubDest = join(projectDir, '.github', 'workflows', 'agent-verify.yml');
+    if (!existsSync(githubWorkflow)) return;
+    if (!force && existsSync(githubDest)) {
+      log.warn('skip (exists): .github/workflows/agent-verify.yml');
+      return;
+    }
+    mkdirSync(dirname(githubDest), { recursive: true });
+    copyFileSync(githubWorkflow, githubDest);
+    log.ok('.github/workflows/agent-verify.yml');
+    return;
+  }
+
+  if (ci === 'gitlab') {
+    const gitlabFragment = join(templateDir, '.gitlab', 'agent-verify.yml');
+    const gitlabDest = join(projectDir, '.gitlab', 'agent-verify.yml');
+    if (!existsSync(gitlabFragment)) return;
+    if (!force && existsSync(gitlabDest)) {
+      log.warn('skip (exists): .gitlab/agent-verify.yml');
+      return;
+    }
+    mkdirSync(dirname(gitlabDest), { recursive: true });
+    copyFileSync(gitlabFragment, gitlabDest);
+    log.ok('.gitlab/agent-verify.yml');
+  }
+}
+
+function installSpecVerify(projectDir, templateDir, force) {
+  for (const rel of KIT_OPTIN_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);
+  }
+  try {
+    execSync(`chmod +x ${join(projectDir, 'scripts', 'verify-specs.sh')} ${join(projectDir, 'scripts', 'post-mr-verdict.sh')}`);
+  } 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;
@@ -168,7 +287,7 @@ function patchOrchestratorVerifier(projectDir, pm) {
   writeFileSync(orchPath, content);
 }
 
-function printNextSteps(profile, projectDir) {
+function printNextSteps(profile, projectDir, ci = 'github', specVerify = false) {
   const pm = detectPackageManager(projectDir);
   const openspecReady = hasOpenSpec(projectDir);
   const lines = [`${pc.bold('Next steps:')}`];
@@ -206,6 +325,18 @@ function printNextSteps(profile, projectDir) {
     lines.push(`  ${pc.dim(`Detected package manager: ${pm} (verifier commands updated in orchestrator.yaml)`)}`);
   }
 
+  if (ci === 'gitlab') {
+    lines.push(`  ${pc.dim(`GitLab verify: ${pm} run build triggers prebuild → verify:openspec automatically`)}`);
+    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:')}`);
+    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)`);
+  }
+
   console.log('\n' + lines.join('\n') + '\n');
 }
 
@@ -236,17 +367,21 @@ program
   .option('--lang <lang>', 'Agent response language (en | uk | ...)', 'en')
   .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 only)', false)
   .action((opts) => {
     const projectDir = process.cwd();
     const projectName = opts.name || basename(projectDir);
     const profile = resolveProfile(opts.profile);
     const pm = detectPackageManager(projectDir);
+    const ci = resolveCiProvider(opts.ci);
 
     log.title(`agent-orchestrator init  v${KIT_VERSION}`);
     log.info(`Project: ${projectName}`);
     log.info(`Profile: ${profile}`);
     log.info(`Language: ${opts.lang}`);
     log.info(`Package manager: ${pm}`);
+    log.info(`CI provider: ${ci}`);
 
     const templateDir = join(KIT_ROOT, 'templates');
     const profileDir = join(KIT_ROOT, 'profiles', profile);
@@ -259,22 +394,27 @@ 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 {}
 
     log.title('Installing CI workflow');
-    const githubWorkflow = join(templateDir, '.github', 'workflows', 'agent-verify.yml');
-    const githubDest = join(projectDir, '.github', 'workflows', 'agent-verify.yml');
-    if (existsSync(githubWorkflow)) {
-      if (!opts.force && existsSync(githubDest)) {
-        log.warn('skip (exists): .github/workflows/agent-verify.yml');
-      } else {
-        mkdirSync(dirname(githubDest), { recursive: true });
-        copyFileSync(githubWorkflow, githubDest);
-        log.ok('.github/workflows/agent-verify.yml');
-      }
+    installCi(projectDir, templateDir, ci, opts.force);
+    if (ci === 'gitlab') {
+      injectVerifyScripts(projectDir, { pm });
+    }
+
+    const specVerify = Boolean(opts.specVerify) && ci === 'gitlab';
+    if (opts.specVerify && ci !== 'gitlab') {
+      log.warn('--spec-verify requires --ci gitlab — skipping AI Spec Verifier install');
+    }
+    if (specVerify) {
+      log.title('Installing AI Spec Verifier (opt-in)');
+      installSpecVerify(projectDir, templateDir, opts.force);
     }
 
     log.title('Installing root files');
@@ -302,6 +442,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);
@@ -311,7 +454,7 @@ program
 
     log.title('Done');
     log.ok(`agent-orchestrator-kit v${KIT_VERSION} installed`);
-    printNextSteps(profile, projectDir);
+    printNextSteps(profile, projectDir, ci, specVerify);
   });
 
 program
@@ -336,6 +479,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');
   });

package/package.json

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

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

@@ -0,0 +1,36 @@
+.agent-verify-base:
+  image: node:20
+  before_script:
+    - |
+      if [ -f pnpm-lock.yaml ]; then
+        export PM=pnpm
+        corepack enable
+        pnpm install --frozen-lockfile
+      elif [ -f yarn.lock ]; then
+        export PM=yarn
+        yarn install --frozen-lockfile
+      else
+        export PM=npm
+        npm ci
+      fi
+  script:
+    - npx openspec validate --all --strict
+    - |
+      run_pm_script() {
+        local name=$1
+        if [ "$PM" = "npm" ]; then
+          npm run "$name" --if-present
+        elif node -e "process.exit(require('./package.json').scripts?.['${name}'] ? 0 : 1)"; then
+          $PM run "$name"
+        fi
+      }
+      run_pm_script lint
+      run_pm_script build
+      run_pm_script test
+
+agent-verify:
+  extends: .agent-verify-base
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_COMMIT_BRANCH == "develop"

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

@@ -0,0 +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

@@ -24,6 +24,10 @@ Never mix phases in one chat — this is the single most important rule.
 | Implementer | `/opsx:apply <name>` | writes `src/` | strong |
 | Verifier | CI (automatic) | scripts only | — |
 
+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`, an **AI Spec Verifier** also runs on MRs 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`).
+
 ## Hard Rules
 
 - **One active change per developer** at a time.

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/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"