@michaelxwb/code-flow 0.5.2 → 0.6.0

package/src/adapters/opencode/commands/cf-task/align.md

@@ -2,6 +2,7 @@
 description: 从需求出发通过结构化对话产出设计简报(.design.md)
 ---
 
+
 # cf-task:align
 
 从需求出发，通过结构化对话产出设计简报（`.design.md`），为 `cf-task:plan` 提供足够丰富的输入。支持三种输入：纯文本需求、`.prd.md` 产品需求文档、`.design.md` 草稿。
@@ -114,6 +115,18 @@ PRD 已覆盖的维度如无需调整，将直接使用。
 - Step 3 中已从 PRD 获得充分信息的维度**不重复提问**，除非用户主动修改
 - design 中 FEAT 的"来源"列必须引用 PRD 中对应的 US-XX
 
+### 2.7. 继承并刷新 Spec Context（硬门禁）
+
+进入技术讨论前先定位需求目录中的 `spec-context.yml`：
+
+1. PRD 派生/恢复模式必须执行 `python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <需求目录> --root "$PWD" --json`；missing/stale/conflict 必须先处理。
+2. 已有 binding 必须从 PRD Context 原样继承，**不得重新选择**、降级 enforcement 或清空 PRD 阶段 refs/decision/evidence。根据预计实现路径运行 `catalog --stage design`，只对新增 design-stage 候选做增量 bind，并记录 reason。
+3. 为每条 design-stage required Rule 预建 `Spec Compliance Matrix` 行：`Spec/Rule`、enforcement、设计影响、具体设计落点、验证场景/verifier、状态或 N/A 理由。
+4. required Rule 没有具体 heading/item 和验证方式时不得进入可评审状态；只写“遵循规范”无效。
+5. N/A/waiver 必须逐 Rule 请求用户确认并调用 `decision`；`batch` 必须为 false，Agent 不得代确认。无有效确认来源时 fail-closed。
+
+> 无 PRD 的新建模式也必须先 catalog/bind 并创建 Context，再写 Design；不能因为缺 PRD 跳过 Specs。
+
 ### 3. 交互式细化
 
 围绕选中的维度逐步推进，**每轮提 2-3 个问题**（不要一次性抛 10 个问题）：
@@ -194,7 +207,8 @@ CLI 场景：
 3. **只包含适用的章节**，模板中有但需求不涉及的章节跳过
 4. 用 `{}` 占位符替换为实际内容
 5. PRD 派生模式：功能清单的"来源"列填 PRD 中对应的 US-XX
-6. 展示生成的设计简报
+6. 生成 `Spec Compliance Matrix`，每条 required Rule 的验证场景必须引用 S-/E-/B- 或说明仅可人工验证的外部边界
+7. 展示生成的设计简报
 
 **章节映射**（Lite 模板，对应 `design-lite.md` 实际章节）：
 
@@ -271,6 +285,14 @@ CLI 场景：
    - **全栈需求**：前后端各写一份到同一需求目录
 4. 用 Write 写入最终路径
 
+写入后，对 Matrix 每一行调用 `bind --stage design` 的 `applications` 回填 design artifact、`section_id`、稳定 `item_id` 和脚本计算的 hash；随后执行：
+
+```bash
+python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage design --json
+```
+
+只有 Design Gate `decision=pass` 才能输出 Plan 下一步。缺 Matrix 行、artifact ref、验证方式、用户确认或发生 drift 时保留草稿并修复，不得推迟到 Coding/Done 才发现。
+
 ### 6. 输出摘要
 
 ```
@@ -282,6 +304,7 @@ CLI 场景：
   - <按实际包含的章节列出>
   - 验收标准: N 项
   - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；每个场景有测试层级和关键真实边界✓；RULE/高影响 RISK 有验证场景✓；Full 模板 §6 矩阵闭合
+  - Spec Compliance: required Rules N/N 已落点；Design Gate: pass
   - 性能自检: 标记性能敏感则方案须体现最优性能设计依据（§3.1/§3.5 或 lite §3.4），否则提示补全或显式声明"无性能敏感点"
 
 下一步:

package/src/adapters/opencode/commands/cf-task/archive.md

@@ -2,6 +2,7 @@
 description: 归档已完成的 task 文件
 ---
 
+
 # cf-task:archive
 
 归档已完成的整个 task 文件。归档前执行四维校验，归档后提示更新 specs。
@@ -36,6 +37,13 @@ description: 归档已完成的 task 文件
 
 ### 2. 归档前校验（Verify）
 
+**Spec Context / Code Gate（先于四维校验）**：
+
+- 需求目录必须存在 `spec-context.yml`；执行 `python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <需求目录> --root "$PWD" --json`
+- 执行 `python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage code --json`；required Rule 的 stale/pending/conflict/unverified 任一存在即 FAIL
+- 若 `.code-flow/.active-task.json` 仍指向本需求，必须先完成对应 TASK 的 Done Gate，并以 `{"gate_passed": true}` 调用 `active complete`；不得通过归档绕过 active 状态
+- Context 与 Evidence 随需求目录一并归档，`_session` 仅是可重建投影，不是事实源
+
 所有子任务 done 后，执行四维校验：
 
 **完整性**：

package/src/adapters/opencode/commands/cf-task/plan.md

@@ -2,6 +2,7 @@
 description: 从设计文档拆解需求，生成结构化任务文件
 ---
 
+
 # cf-task:plan
 
 从设计文档或设计简报拆解需求，生成结构化任务文件。
@@ -166,6 +167,13 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 5. Checklist 禁止使用泛化的“编写测试”。必须写成 `[场景ID][测试层级] + 真实边界 + 关键断言`，并为新功能/缺陷修复安排先写测试和 RED 记录。
 6. 如果场景缺测试层级、真实边界或 RULE/高影响 RISK 没有验证场景，先以 `#NOTES` 列为设计缺口；未解决前不得开始编码。
 
+**Spec 责任拆解（硬约束）**：
+
+1. 先执行 Context `refresh`，读取 Design `Spec Compliance Matrix` 与每个 design-stage/plan-stage Rule 的 `verifier_ref`，继承已有 applied refs，禁止重新选择或降级。
+2. 每条 plan-stage required Rule 必须有且仅有一个责任 TASK；该 TASK 的 `Spec-Refs` 写完整 `{spec-id}#{rule-ref}`，Checklist 写具体 verifier 命令/输入，Acceptance Contract 写测试层级、不得 Mock 的真实边界和关键断言。
+3. Rule 可被其他 TASK 引用为依赖，但 Acceptance Coverage 只能有一个最终负责人。E2E 层级**不得降级**；manual 仍仅限经用户确认的外部边界。
+4. 缺 `verifier_ref`、责任 TASK 为 0/多个、Checklist/Contract 不含 Rule-specific 验证责任时，任务文件只能保留为缺口草稿，不能启动。
+
 ### 4. 生成任务文件方案
 
 将拆解结果按以下格式组织，展示给用户确认：
@@ -213,6 +221,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 - **Priority**: P0
 - **Depends**:
 - **Source**: docs/xxx.md#§3.1 数据模型(L83-L110)
+- **Spec-Refs**: product-rules#RULE-product-001
 - **Acceptance-Refs**: S-01, E-01, RULE-01
 
 ### Description
@@ -288,6 +297,14 @@ TASK-002: <标题> [P1]
 3. 如果输入为 docs/ 设计文档（无需求目录）→ 按当前日期创建需求目录 `.code-flow/tasks/<YYYY-MM-DD>/<需求>/` 并写入其中
 4. 用 Write 写入
 
+写入后用 `bind --stage plan` 的 `applications` 将每条 required Rule 指向任务文件内唯一 TASK item，并执行：
+
+```bash
+python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage plan --artifact <任务文件> --json
+```
+
+只有 Context Plan 状态与任务结构校验都 `decision=pass` 才输出 Start 下一步；缺唯一 owner、`verifier_ref`、测试层级或真实边界时必须回到拆解修复。
+
 ### 6. 输出摘要
 
 ```

package/src/adapters/opencode/commands/cf-task/prd.md

@@ -2,6 +2,7 @@
 description: 从一句话需求出发产生产品需求文档(PRD)
 ---
 
+
 # cf-task:prd
 
 从一句话需求出发，通过结构化对话产出产品需求文档（PRD），为 `cf-task:align` 提供足够丰富的输入。
@@ -38,6 +39,22 @@ description: 从一句话需求出发产生产品需求文档(PRD)
 
 目的：**让 PRD 基于实际业务背景**，而非泛泛的通用描述。本步只读不提问，所有提问统一放到 Step 3。
 
+### 2.1 先解析并绑定 Existing Specs（硬门禁）
+
+在开始写需求内容前，先确定 Step 5 的需求目录和预计涉及路径，再执行：
+
+```bash
+python3 .code-flow/scripts/cf_spec_context.py catalog --stage prd --root "$PWD" --paths <预计路径...> --json
+```
+
+1. 必须检查完整 `candidates`，不得按展示条数截断；只消费 resolver 返回的 `stages` 含 `prd` 的产品、安全、兼容、业务约束，`code-only` Spec 不得进入 PRD。
+2. 对每个适用候选记录 `selected_by` 和具体 `reason`，立即用 `bind --stage prd` 写入需求目录的 `spec-context.yml`（首次 `applications` 为空），然后再进入需求细化。
+3. required Rule 必须进入 PRD 的 `Existing Spec Constraints`，并明确影响哪个范围项、FEAT 验收或 NFR；只复制一句“遵循规范”不算承接。
+4. 不适用的 required Rule 必须逐 Rule 说明具体理由并请求用户确认，再调用 `decision` 保存 `not_applicable`；禁止批量 N/A，**Agent 不得代确认**。
+5. Catalog/Context 失败、同级 required 冲突或 required Rule 尚未决定时 fail-closed：保留草稿并修复，不得绕过后继续产出可批准 PRD。
+
+> 预计路径尚不明确时仍须以空 `--paths` 运行，确保 global/task-stage 规则先进入 Context；后续范围明确时重新 catalog，并补充绑定新增候选。
+
 ### 3. 交互式细化
 
 围绕 PRD 各要素逐步推进，**每轮提 2-3 个问题**：
@@ -98,6 +115,7 @@ description: 从一句话需求出发产生产品需求文档(PRD)
 | 5. 非功能需求 | Step 3 的"非功能需求"（按需，分配 NFR 编号） |
 | 6. 范围与边界 | Step 3 的"范围与边界" |
 | 7. 依赖与风险 | Step 3 的"依赖与风险"（按需） |
+| 8. Existing Spec Constraints | Step 2.1 的 prd-stage Rule；逐条关联范围/FEAT 验收/NFR |
 
 **编号与追溯（硬约束，`cf-task:align` 派生的基础）**：
 - 用户故事按出现顺序分配 `US-01`、`US-02`…，写入 §3.2 用户故事表
@@ -120,6 +138,12 @@ description: 从一句话需求出发产生产品需求文档(PRD)
 3. **重名检查**：需求目录已存在且非本次草稿时，目录名追加序号 `<name>-2`、`<name>-3`… 避免覆盖；恢复模式复用原目录、不改名
 4. 用 Write 写入 `.code-flow/tasks/<YYYY-MM-DD>/<name>/<name>.prd.md`
 
+写入后必须完成 Context 回填和 PRD Gate：
+
+1. 再次调用 `bind --stage prd`，`selections` 可为空，`applications` 为每条已承接 Rule 写入 `artifact`、`section_id`、`item_id`；artifact 必须指向本需求目录内 PRD，由脚本计算 `artifact_sha256`。
+2. 执行 `python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage prd --json`。
+3. 只有 `decision=pass` 才能把 PRD 标为可评审并输出下一步；pending/conflict/stale、缺少范围/验收落点或无有效用户确认的 N/A 均保持阻断。
+
 **文件位置说明**：PRD、设计简报（`<name>.frontend.design.md` / `<name>.backend.design.md`）、任务文件（`<name>.md`）同放**需求目录** `.code-flow/tasks/<日期>/<name>/`，`cf-task:archive` 按整个需求目录归档。
 
 ### 6. 输出摘要
@@ -132,6 +156,7 @@ description: 从一句话需求出发产生产品需求文档(PRD)
   - 用户故事: N 个
   - 功能: N 个（P0: X, P1: Y）
   - 追溯自检: FEAT↔US 全部关联 ✓ ｜ 有缺口则列出「未关联 FEAT-XX / 未覆盖 US-XX」
+  - Existing Specs: N 个 / required Rules: N 条 / PRD Gate: pass
 
 > 自检发现缺口（FEAT 无来源 US 或 US 无 FEAT 覆盖）时，在摘要显式标注并提示用户补 US 或降级，不要静默放过。
 

package/src/adapters/opencode/commands/cf-task/start.md

@@ -2,6 +2,7 @@
 description: 激活子任务并开始编码
 ---
 
+
 # cf-task:start
 
 激活子任务并开始编码。支持单任务模式和整文件模式。
@@ -62,12 +63,15 @@ description: 激活子任务并开始编码
 
 ### 3. 激活并准备验收测试
 
-1. 用 Edit 更新子任务 Status 为 `in-progress`
-2. 在 `### Log` 追加：`- [<当前日期>] started (in-progress)`
-3. 更新文件头 `Updated` 日期
-4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
-5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+在改状态或生产代码前，顺序固定且不得跳步：
+
+1. 调用 `cf_spec_context.py refresh --task-dir ...`，执行 Start Gate；stale/pending/conflict 或依赖未闭合均不得继续。
+2. 重新读取 refresh 后的 Context hash，再调用 `cf_spec_context.py active start`，传 task/context hash 和逐路径确认的 pre-existing ownership；已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
+3. 调用 `cf_spec_session.py`，只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `_session/task-<name>.md`。禁止重新 catalog 或猜测规则。
+4. 只有前三步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
+5. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
+6. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+7. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
 
 RED 证据写入 `Acceptance Evidence`：
 
@@ -91,15 +95,15 @@ RED 证据写入 `Acceptance Evidence`：
 4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
 5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
 
-### 3.5 会话级临时约束（FEAT-08）
+### 3.5 TASK-bound Spec Session
 
 激活后，若任务文件头 Source 指向的 design 文档含验收条件章节（如 §2.5 验收条件 / 验收标准）：
 
-1. 只提取当前任务 `Acceptance-Refs` 对应的场景、测试层级、关键真实边界与 RULE/RISK，生成 `.code-flow/specs/_session/task-<name>.md`：
+1. 只提取当前任务 `Spec-Refs` 与 `Acceptance-Refs` 对应的 Rule hash、verifier、artifact refs、场景、测试层级和真实边界，生成 `.code-flow/specs/_session/task-<name>.md`：
    - frontmatter：`description: 当前任务 <name> 的验收约束（cf-task:start 生成，archive 清理）`
    - 正文：验收场景与约束的精简列表（≤300 token）；必须保留全部引用 ID、层级、边界和预期结果，不能为压缩而删除场景
-2. Spec Catalog 目录扫描自动纳入该文件，无需配置；编辑代码时的自动注入同样生效
-3. design 无验收章节时静默跳过；同名文件已存在则覆盖（同任务重复 start）
+2. 任务模式直接读取这个投影，禁止经 Spec Catalog 二次选择；同名文件已存在则原子覆盖。
+3. 50 Rule 等超预算任务按 required/当前阶段优先输出受控摘要，完整 Context 保留不丢失，并明确提示拆 TASK；不得用截断隐藏 required 缺口。
 
 > `_session/` 不入库（.gitignore 模板已覆盖）、不参与规范审计与预算。
 

package/src/adapters/opencode/plugins/code-flow/index.js

@@ -60,7 +60,6 @@ export const CodeFlow = async (ctx) => {
         const sid = input.event?.properties?.info?.id || "";
         debugLog(projectRoot, `session.created sid=${sid}`);
         if (sid) sessionContext.delete(sid);
-        callHook(projectRoot, "cf_session_hook.py", { session_id: sid });
       }
       if (input.event?.type === "session.idle") {
         const sid =

package/src/cli.js

@@ -7,9 +7,11 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 
 const pkg = require('../package.json');
+const specWorkflowMigration = require('./migrate/spec-workflow');
 
 const usage = [
   'Usage: code-flow init [--force] [--platform=<claude|codex|costrict|opencode>]',
+  '       code-flow migrate --spec-workflow <--dry-run|--prepare|--apply --plan <path>|--rollback <id>>',
   '       code-flow -v | --version',
   '       code-flow -h | --help'
 ].join('\n');
@@ -469,15 +471,19 @@ function parsePlatform(args) {
 // --- Main init ---
 
 function runInit(force, platform) {
+  const cwd = process.cwd();
+  const installedVersion = readInstalledVersion(cwd);
+  if (installedVersion && compareVersions(installedVersion, '0.4.2') >= 0 && compareVersions(installedVersion, '0.6.0') < 0) {
+    process.stdout.write(`${JSON.stringify({ status: 'migration_required', version: installedVersion, command: 'code-flow migrate --spec-workflow --dry-run' })}\n`);
+    process.exit(3);
+  }
   ensurePython3();
 
-  const cwd = process.cwd();
   const baseDir = __dirname;
   const coreDir = path.join(baseDir, 'core');
   const adaptersDir = path.join(baseDir, 'adapters');
 
   // Determine mode
-  const installedVersion = readInstalledVersion(cwd);
   let mode;
   if (force) {
     mode = 'force';
@@ -778,6 +784,45 @@ function runInit(force, platform) {
 
 const args = process.argv.slice(2);
 
+function argumentValue(values, name) {
+  const index = values.indexOf(name);
+  return index >= 0 ? values[index + 1] || '' : '';
+}
+
+function migrationExitCode(result) {
+  if (result.status === 'rolled_back') return 4;
+  if (result.status === 'recovery_required') return 5;
+  if (result.status === 'prepared_blocked') return 3;
+  return 0;
+}
+
+function runMigrate(values) {
+  if (!values.includes('--spec-workflow')) fail('Error: migrate requires --spec-workflow.');
+  const actions = ['--dry-run', '--prepare', '--apply', '--rollback'].filter(action => values.includes(action));
+  if (actions.length !== 1) fail('Error: choose exactly one migrate action.');
+  let result;
+  try {
+    if (actions[0] === '--dry-run') result = specWorkflowMigration.preview(process.cwd());
+    if (actions[0] === '--prepare') result = specWorkflowMigration.prepare(process.cwd());
+    if (actions[0] === '--apply') {
+      const plan = argumentValue(values, '--plan');
+      if (!plan) fail('Error: --apply requires --plan <path>.');
+      result = specWorkflowMigration.apply(path.resolve(plan));
+    }
+    if (actions[0] === '--rollback') {
+      const id = argumentValue(values, '--rollback');
+      if (!id) fail('Error: --rollback requires a migration id.');
+      const plan = path.join(process.cwd(), '.code-flow', 'migrations', id, 'migration-plan.json');
+      result = specWorkflowMigration.rollback(plan);
+    }
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exit(migrationExitCode(result));
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ status: 'unresolved', error: String(error.message || error) })}\n`);
+    process.exit(3);
+  }
+}
+
 if (args.includes('-v') || args.includes('--version')) {
   process.stdout.write(`${pkg.version}\n`);
   process.exit(0);
@@ -799,6 +844,10 @@ if (args[0] === 'init') {
   runInit(force, platform);
 }
 
+if (args[0] === 'migrate') {
+  runMigrate(args.slice(1));
+}
+
 if (args.length === 0) {
   fail('Error: missing command.');
 }

package/src/core/code-flow/config.yml

@@ -1,5 +1,14 @@
 version: 1
 
+spec_workflow:
+    schema_version: 1
+    enforcement: required
+    drift_check: true
+    scope_expansion_check: true
+    metrics: true
+    catalog:
+        dedup_window: 5
+
 budget:
     total: 2500
     l0_max: 800
@@ -8,17 +17,6 @@ budget:
     # catalog 模式下 spec 目录的 token 上限（超出按 Tier1 优先截断并告警）
     catalog_max: 200
 
-inject:
-    auto: true
-    # 注入模式：
-    #   catalog — UserPromptSubmit 仅注入极小 spec 目录（每 spec 一行适用场景），
-    #             由模型按语义自行 Read 相关 spec 全文；prompt 含明确文件路径且
-    #             命中 domain 时仍直接注入完整约束。PreToolUse 不受影响（编辑时
-    #             始终强制注入完整约束兜底）。
-    #   full    — 旧行为：UserPromptSubmit 按 tag 词表匹配注入完整 spec。
-    # 仅 literal "catalog" 启用目录模式；缺失/其他值一律 full（升级用户行为不变）。
-    mode: catalog
-
 # 质量闭环（v0.5）：合规反馈 + 学习采集。
 # enabled 仅 literal true 启用（缺失即关闭，升级用户行为不变）；
 # 子开关缺省跟随 enabled，仅 literal false 单独关闭。
@@ -31,11 +29,6 @@ quality_loop:
     # 注入时对 spec 内容做保守无损压缩（去行尾空白、折叠多空行、剥 HTML 注释、去重 bullet）
     # 缺省视为 true；仅显式 false 关闭
     compress: true
-    # UserPromptSubmit 去重窗口：同一 spec 在最近 N 个 prompt 内不重复注入。
-    # 0 或负数 关闭去重（每次都注入，等同旧行为）；缺省 5。
-    # 窗口"限速"而非"永久跳过"，超过 N 个 prompt 后会再次注入，保证 auto-compaction
-    # 丢掉早期上下文后仍能恢复 spec。
-    dedup_window: 5
     code_extensions:
         - ".py"
         - ".ts"
@@ -73,7 +66,9 @@ quality_loop:
         - "*.config.*"
         - ".code-flow/**"
         - ".claude/**"
+        - ".codex/**"
         - ".costrict/**"
+        - ".opencode/**"
         - "node_modules/**"
         - "dist/**"
         - "build/**"
@@ -112,6 +107,8 @@ path_mapping:
             - "src/components/**"
             - "src/pages/**"
             - "src/hooks/**"
+            - "src/composables/**"
+            - "src/services/**"
             - "src/styles/**"
             - "**/*.tsx"
             - "**/*.jsx"

package/src/core/code-flow/scripts/cf_checks.py

@@ -16,6 +16,7 @@ import fnmatch
 import os
 import re
 import sys
+from typing import Mapping
 from concurrent.futures import ThreadPoolExecutor
 from concurrent.futures import TimeoutError as FutureTimeout
 
@@ -304,3 +305,32 @@ def run_checks(
                     "severity": check["severity"],
                 })
     return violations, skipped
+
+
+def run_regex_verifier(
+    pattern: str,
+    files: str,
+    contents: Mapping[str, str],
+    timeout: float = CHECK_TIMEOUT_SECONDS,
+) -> tuple[list[dict[str, object]], list[dict[str, object]]]:
+    """Execute one verifier regex over explicit file contents."""
+    try:
+        compiled = re.compile(pattern)
+    except re.error as exc:
+        return [], [{"check_id": "verifier", "reason": f"invalid_regex:{exc}"}]
+    check = {
+        "id": "verifier",
+        "type": "regex",
+        "pattern": pattern,
+        "regex": compiled,
+        "files": files,
+        "message": "Rule verifier matched forbidden content",
+        "severity": "warn",
+    }
+    violations: list[dict[str, object]] = []
+    skipped: list[dict[str, object]] = []
+    for relative, content in contents.items():
+        file_violations, file_skipped = run_checks([check], relative, content, timeout=timeout)
+        violations.extend(file_violations)
+        skipped.extend(file_skipped)
+    return violations, skipped