Back to Details

policy-algebra

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/policy-algebra

/policy-algebra

Generates frozen, drift-checkable governance rules from thin intent strings (deep interview) or rich plan inputs (shallow confirmation). Produces fenced Starlark blocks callers can inject into downstream work, and exposes 
--verify
for canonicalized drift detection.
可从简洁的意图字符串（深度访谈模式）或详尽的计划输入（浅层确认模式）生成可冻结、可漂移检查的治理规则。生成可被调用方注入到下游工作中的带围栏的Starlark代码块，并提供
--verify
参数用于规范化漂移检测。

Invocation

调用方式

/policy-algebra <target>                      # generate rules
/policy-algebra <target> --write <path>       # generate + persist raw block
/policy-algebra --verify <frozen> <candidate> # drift check
<target>
is a readable file path (SHALLOW mode) or an intent string (DEEP mode).
/policy-algebra <target>                      # 生成规则
/policy-algebra <target> --write <path>       # 生成并保存原始代码块
/policy-algebra --verify <frozen> <candidate> # 漂移检查
<target>
是可读文件路径（SHALLOW模式）或意图字符串（DEEP模式）。

Adaptive input detection

自适应输入检测

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

Deep flow

深度流程

  1. Construct framing prompt for 
    /grill-me
    :
    "Interview the user to extract rule invariants for: <target prompt>
    Focus questions on:
    • Scope: what artifacts/events/phases does this rule govern?
    • Invariants: what must always be true? what must never happen?
    • Variable holes: what changes between instances?
    • Combinators: are existing operators (+, diff, intersect, method calls) enough, or do we need new helpers?
    • Failure modes: what happens when a rule can't be satisfied?
    Return a structured list of predicates in natural language. /policy-algebra will draft Starlark from your output."
  2. Invoke 
    /grill-me
    via the 
    Skill
    tool with that prompt.
  3. Capture 
    /grill-me
    's output as the invariant list.
  4. Continue to drafting (step 5 of shallow flow).
  1. 为
    /grill-me
    构建框架提示语：
    "请与用户访谈，提取以下规则的不变量： <目标提示语>
    重点关注以下问题：
    • 范围：该规则管控哪些工件/事件/阶段？
    • 不变量：哪些情况必须始终成立？哪些情况绝对不能发生？
    • 变量缺口：不同实例之间哪些内容会变化？
    • 组合器：现有运算符（+、diff、intersect、方法调用）是否足够，还是需要新的辅助工具？
    • 故障模式：当规则无法被满足时会发生什么？
    返回结构化的自然语言谓词列表。 /policy-algebra将根据你的输出起草Starlark代码。"
  2. 通过
    Skill
    工具调用
    /grill-me
    并传入上述提示语。
  3. 捕获
    /grill-me
    的输出作为不变量列表。
  4. 继续进入起草环节（对应浅层流程的第5步）。

Shallow flow

浅层流程

  1. Read file contents.
  2. Scan for invariant declarations — headings like "Invariants", "Rules", "Constraints"; bullets with MUST / NEVER / ALWAYS; predicate-looking code blocks.
  3. Extract those as the invariant list.
  4. If extraction yields fewer than 2 invariants OR content is ambiguous: fall through to DEEP mode with the file contents as target.
  5. Draft Starlark from the invariant list per 
    notation.md
    conventions.
  6. Pass draft to 
    /review-loop
    (no panel hint — 
    /review-loop
    assembles).
  7. /review-loop
    converges → frozen, OR caps → inherit 
    /review-loop
    escalation.
  1. 读取文件内容。
  2. 扫描不变量声明——如"Invariants"、"Rules"、"Constraints"等标题；包含MUST/NEVER/ALWAYS的项目符号；类似谓词的代码块。
  3. 将这些内容提取为不变量列表。
  4. 如果提取的不变量少于2个，或内容存在歧义：切换为DEEP模式，将文件内容作为目标。
  5. 根据
    notation.md
    约定，基于不变量列表起草Starlark代码。
  6. 将草稿传入
    /review-loop
    （无需面板提示——
    /review-loop
    会自动组建评审组）。
  7. /review-loop
    达成一致→生成冻结代码块，或达到上限→继承
    /review-loop
    的升级流程。

Drafting conventions

起草约定

Group by subject (DEFAULTS, then named functions); keep each function body to 5 lines or fewer; one prose comment per function; no mutation. See 
notation.md
for the full ruleset.
按主题分组（先DEFAULTS，再命名函数）；每个函数体不超过5行；每个函数配一条注释；禁止使用突变操作。完整规则集请参考
notation.md
。

Freeze and return

冻结并返回

After 
/review-loop
APPROVE, capture the exact Starlark text as the FROZEN block. Do not canonicalize at freeze time — canonicalization is a compare-time operation only, keeping freeze/return simple.
Output format:
ALGEBRA:
```starlark
<raw frozen starlark block, as /review-loop approved>
REVIEW_ROUNDS: <n> PANEL: <comma-separated reviewers> STATUS: CONVERGED FILE: <path> (only when --write was used) NOTE: <non-obvious decision> (optional)

If `--write <path>` was supplied, write the raw Starlark block to that path and include `FILE: <path>` in the return block.
在
/review-loop
批准后，捕获精确的Starlark文本作为FROZEN代码块。冻结时不要进行规范化处理——规范化仅在对比阶段操作，以保持冻结/返回流程简洁。
输出格式：
ALGEBRA:
```starlark
<经/review-loop批准的原始冻结Starlark代码块>
REVIEW_ROUNDS: <n> PANEL: <逗号分隔的评审者列表> STATUS: CONVERGED FILE: <路径> (仅当使用--write时显示) NOTE: <非显而易见的决策> (可选)

如果使用了`--write <path>`参数，将原始Starlark代码块写入该路径，并在返回块中包含`FILE: <path>`。

--verify
flow

--verify
流程

  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
undefined
  1. 读取两个文件。
  2. 从每个文件中提取第一个
    ```starlark
    围栏代码块。
  3. 规范化两个代码块（去除尾随空格、合并空行、修剪边缘）。
  4. 如果内容一致→输出
    MATCH
    ，退出码0。否则→输出
    DRIFT
    及统一差异对比，退出码1。
使用以下bash脚本进行漂移检查——无需外部依赖：
bash
undefined

policy-algebra verify — inline, no dependencies

policy-algebra verify — 内联式，无依赖

Usage: bash verify.sh <frozen_file> <candidate_file>

使用方法: 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
undefined
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
undefined

Multiple-block behavior

多代码块处理逻辑

When a file contains multiple 
```starlark
blocks, 
extractAlgebra
silently uses the first. This is intentional — wrap your canonical rules in the first fenced block of any document.
当文件包含多个
```starlark
代码块时，
extractAlgebra
会默认使用第一个。这是有意设计的——请将你的规范规则放在任意文档的第一个围栏代码块中。

Failure modes

故障模式

FailureBehavior
Target omittedError: "target required"
SHALLOW: file unreadableFall through to DEEP with path string as intent
SHALLOW: < 2 extractable invariantsFall through to DEEP with file contents as intent
DEEP: 
/grill-me
unavailable		Error: "deep interview requires /grill-me skill"
DEEP: user abandons interviewInherit 
/grill-me
's exit behavior
Drafting produces empty StarlarkError: "no invariants found to codify"; return invariant list
/review-loop
caps without convergence		Inherit 
/review-loop
escalation — no custom handling
--write <path>
unwritable		Error with path; return inline result anyway
Either 
--verify
path unreadable		Error with path, exit 2
No 
```starlark
block
NoAlgebraBlockError
with path, exit 2
canonicalize
throws		Error with stack, exit 3
故障情况处理行为
未指定目标错误提示："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-loop
达到上限仍未达成一致		继承
/review-loop
的升级流程——无自定义处理
--write <path>
路径不可写		输出路径错误提示；仍返回内联结果
--verify
的任一路径不可读		输出路径错误提示，退出码2
无
```starlark
代码块		抛出
NoAlgebraBlockError
并附带路径，退出码2
canonicalize
执行出错		输出错误堆栈，退出码3

Exit codes

退出码

CodeMeaning
0MATCH (verify) / SUCCESS (normal)
1DRIFT (verify only)
2Input error (missing file, bad args, 
NoAlgebraBlockError
)
3Internal error
代码含义
0匹配成功（验证模式）/ 执行成功（普通模式）
1漂移（仅验证模式）
2输入错误（文件缺失、参数错误、
NoAlgebraBlockError
）
3内部错误

Cross-tool notes

跨工具说明

  • Claude Code: invokes 
    /grill-me
    (DEEP interview) and 
    /review-loop
    (panel convergence) via the 
    Skill
    tool. Both exist as project-local skills under 
    .claude/skills/
    .
  • Codex / Cursor: the 
    Skill
    tool is Claude-Code-only. Read the relevant skill files directly: 
    • .claude/skills/grill-me/SKILL.md
      — for the interview procedure
    • .claude/skills/review-loop/SKILL.md
      — for panel convergence Apply their procedures inline rather than invoking them as commands. The drafting, freeze, and 
      --verify
      logic in this SKILL.md is tool-agnostic and works identically for Claude Code, Codex, and Cursor.
  • CLI (
    --verify
    path)     is runtime-agnostic: use the inline bash snippet in the 
    --verify
    section above — no Node or pnpm required.
  • Claude Code：通过
    Skill
    工具调用
    /grill-me
    （深度访谈）和
    /review-loop
    （评审组共识）。这两个工具均作为项目本地Skill存在于
    .claude/skills/
    目录下。
  • Codex / Cursor：
    Skill
    工具仅支持Claude-Code。请直接阅读相关Skill文件： 
    • .claude/skills/grill-me/SKILL.md
      — 访谈流程说明
    • .claude/skills/review-loop/SKILL.md
      — 评审组共识流程说明 需手动执行其流程，而非通过命令调用。本SKILL.md中的起草、冻结和
      --verify
      逻辑是工具无关的，在Claude Code、Codex和Cursor中均可正常使用。
  • CLI（
    --verify
    路径）    ：与运行时无关：使用上述
    --verify
    部分的内联bash脚本即可——无需Node或pnpm依赖。

Governance

治理机制

This skill is self-hosted: its own rules are encoded as a frozen Starlark governance block. Drift from these invariants is a bug. Verify with 
/policy-algebra --verify
.
starlark
undefined
本Skill采用自托管模式：其自身规则被编码为冻结的Starlark治理规则块。偏离这些不变量属于Bug，可通过
/policy-algebra --verify
进行验证。
starlark
undefined

policy-algebra governance — self-hosted

policy-algebra governance — self-hosted

FROZEN — do not edit; regenerate via /policy-algebra

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", }
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.

SELECT_MODE: file path → SHALLOW; intent string → DEEP.

def SELECT_MODE(target): if is_readable_file(target): return "SHALLOW" return "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.

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

EXTRACT_BLOCK: use first starlark fence only; multiple blocks → first wins.

def EXTRACT_BLOCK(fences): if len(fences) == 0: return None return fences[0]
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-loop.

OUTPUT_VALID: output must carry all required fields; STATUS=CONVERGED only after review-loop.

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
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.

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"]
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.

EXIT_CODE: map outcome strings to numeric codes.

def EXIT_CODE(outcome): return DEFAULTS["exit_codes"].get(outcome, DEFAULTS["exit_codes"]["internal_error"])
undefined
def EXIT_CODE(outcome): return DEFAULTS["exit_codes"].get(outcome, DEFAULTS["exit_codes"]["internal_error"])
undefined