policy-algebra

/policy-algebra

从简短的意图字符串（深度访谈）或丰富的计划输入（浅层确认）生成冻结且可检测漂移的治理规则。生成调用方可注入下游工作的围栏 Starlark 代码块，并提供 --verify 用于检测规范化后的漂移。

调用

/policy-algebra <target>                      # generate rules
/policy-algebra <target> --write <path>       # generate + persist raw block
/policy-algebra --verify <frozen> <candidate> # drift check

<target> 是可读取的文件路径（SHALLOW 模式）或意图字符串（DEEP 模式）。

自适应输入检测

if target is a readable file path:
    mode = SHALLOW
    input = read(target)
else:
    mode = DEEP
    input = target

深度流程

1. 为 /grill-me 构造引导提示词：

   "访谈用户，提取以下内容的规则不变量： <target prompt>

   问题重点：

   • 范围：此规则约束哪些制品／事件／阶段？
   • 不变量：哪些条件必须始终成立？哪些情况绝不能发生？
   • 可变项：不同实例之间有哪些变化？
   • 组合器：现有运算符（+、diff、intersect、方法调用）是否足够，还是需要新的辅助函数？
   • 失败模式：无法满足规则时会发生什么？

   以自然语言返回结构化的谓词列表。 /policy-algebra 将根据你的输出起草 Starlark。"

2. 通过 Skill 工具使用该提示词调用 /grill-me。

3. 将 /grill-me 的输出记录为不变量列表。

4. 继续起草（浅层流程的第 5 步）。

浅层流程

1. 读取文件内容。
2. 扫描不变量声明——例如“Invariants”“Rules”“Constraints”等标题；包含 MUST／NEVER／ALWAYS 的项目符号；类似谓词的代码块。
3. 将这些内容提取为不变量列表。
4. 如果提取到的不变量少于 2 个，或内容含糊：使用文件内容作为目标，转入 DEEP 模式。
5. 按照 notation.md 中的约定，根据不变量列表起草 Starlark。
6. 将草稿交给 /review（不提供评审组提示——由 /review 负责组建）。
7. /review 达成一致 → 冻结；否则达到上限 → 沿用 /review 的升级处理。

起草约定

按主题分组（先 DEFAULTS，再列出命名函数）；每个函数体不超过 5 行；每个函数写一条说明性注释；不得修改数据。完整规则集请参见 notation.md。

冻结并返回

/review 批准后，将确切的 Starlark 文本记录为 FROZEN 代码块。冻结时不要规范化——规范化仅在比较时进行，以简化冻结／返回流程。

输出格式：

ALGEBRA:
```starlark
<raw frozen starlark block, as /review approved>

REVIEW_ROUNDS: PANEL: STATUS: CONVERGED FILE: (only when --write was used) NOTE: (optional)

If `--write <path>` was supplied, write the raw Starlark block to that path and include `FILE: <path>` in the return block.

## `--verify` flow

1. Read both files.
2. Extract first ` ```starlark ` fenced block from each file.
3. Normalize both blocks (strip trailing whitespace, collapse blank lines, trim edges).
4. If equal → print `MATCH`, exit 0. Else → print `DRIFT` + unified diff, exit 1.

Use the following bash to verify drift — no external dependencies needed:

```bash
# policy-algebra verify — inline, no dependencies
# Usage: bash verify.sh <frozen_file> <candidate_file>
normalize() { sed 's/[[:space:]]*$//' | sed '/^$/d'; }
extract_starlark() { sed -n '/^```starlark/,/^```$/p' "$1" | sed '1d;$d'; }

FROZEN=$(extract_starlark "$1" | normalize)
CANDIDATE=$(extract_starlark "$2" | normalize)

if [ "$FROZEN" = "$CANDIDATE" ]; then
  echo "MATCH"
  exit 0
else
  echo "DRIFT"
  diff <(echo "$FROZEN") <(echo "$CANDIDATE")
  exit 1
fi

多代码块行为

当文件包含多个 ```starlark 代码块时，extractAlgebra 会静默使用第一个。这是有意设计的——请将规范规则放在任何文档的第一个围栏代码块中。

失败模式

失败	行为
未提供目标	错误："target required"
SHALLOW：文件不可读	使用路径字符串作为意图，转入 DEEP 模式
SHALLOW：可提取的不变量少于 2 个	使用文件内容作为意图，转入 DEEP 模式
DEEP：/grill-me 不可用	错误："deep interview requires /grill-me skill"
DEEP：用户中止访谈	沿用 /grill-me 的退出行为
起草结果为空 Starlark	错误："no invariants found to codify"；返回不变量列表
/review 达到上限但未达成一致	沿用 /review 的升级处理——不做自定义处理
--write <path> 路径不可写	报错并提供路径；仍返回内联结果
任一 --verify 路径不可读	报错并提供路径，退出码为 2
不存在 ```starlark 代码块	返回带路径的 NoAlgebraBlockError，退出码为 2
canonicalize 抛出异常	返回包含堆栈信息的错误，退出码为 3

退出码

代码	含义
0	MATCH（verify）／SUCCESS（常规）
1	DRIFT（仅 verify）
2	输入错误（文件缺失、参数错误、NoAlgebraBlockError）
3	内部错误

跨工具说明

• Claude Code：通过 Skill 工具调用 /grill-me（深度访谈）和 /review （评审团收敛）。这两项都作为项目本地技能存放在 .claude/skills/ 下。
• Codex / Cursor：Skill 工具仅适用于 Claude Code。请直接读取相关技能文件：
  • .claude/skills/grill-me/SKILL.md——访谈流程
  • .claude/skills/review/SKILL.md——评审团收敛 请直接按其流程操作，而不要将其作为命令调用。 本 SKILL.md 中的起草、冻结和 --verify 逻辑与工具无关，在 Claude Code、Codex 和 Cursor 中的工作方式完全相同。
• **CLI（--verify 路径）**与运行时无关：使用上文 --verify 部分中的内联 bash 代码片段——无需 Node 或 pnpm。

治理

此技能可自托管：其自身规则编码在一个冻结的 Starlark 治理块中。偏离这些不变量即为错误。请使用 /policy-algebra --verify 进行验证。

# policy-algebra governance — self-hosted
# FROZEN — do not edit; regenerate via /policy-algebra

DEFAULTS = {
    "min_invariants": 2,
    "exit_codes": {"match": 0, "drift": 1, "input_error": 2, "internal_error": 3},
    "required_output_fields": ["ALGEBRA", "REVIEW_ROUNDS", "PANEL", "STATUS"],
    "converged_status": "CONVERGED",
}

# SELECT_MODE: file path → SHALLOW; intent string → DEEP.
def SELECT_MODE(target):
    if is_readable_file(target):
        return "SHALLOW"
    return "DEEP"

# SHALLOW_OR_DEEP: fall through to DEEP when extraction yields < min_invariants or is ambiguous.
def SHALLOW_OR_DEEP(invariants, ambiguous):
    if len(invariants) < DEFAULTS["min_invariants"] or ambiguous:
        return "DEEP"
    return "SHALLOW"

# EXTRACT_BLOCK: use first starlark fence only; multiple blocks → first wins.
def EXTRACT_BLOCK(fences):
    if len(fences) == 0:
        return None
    return fences[0]

# OUTPUT_VALID: output must carry all required fields; STATUS=CONVERGED only after review.
def OUTPUT_VALID(output, review_loop_passed):
    fields_present = all([f in output for f in DEFAULTS["required_output_fields"]])
    converged_ok = output.get("STATUS") != DEFAULTS["converged_status"] or review_loop_passed
    return fields_present and converged_ok

# VERIFY: canonicalize both blocks and compare; never modify source files.
def VERIFY(frozen_canon, candidate_canon):
    if frozen_canon == candidate_canon:
        return DEFAULTS["exit_codes"]["match"]
    return DEFAULTS["exit_codes"]["drift"]

# EXIT_CODE: map outcome strings to numeric codes.
def EXIT_CODE(outcome):
    return DEFAULTS["exit_codes"].get(outcome, DEFAULTS["exit_codes"]["internal_error"])