workspace-metabolism v0.4.0 — AI governance: wm gate + decision_id

workspace-metabolism v0.4.0 — AI 治理即代码

本次变更（自 v0.3.1）

1. wm gate —— MCP 治理代理（核心新功能）

把任意 MCP stdio 服务器包进治理层：每个 tools/call 先过策略裁决，拒绝的调用
永远不会到达目标服务器，所有决策（allow/deny）带 decision_id 写入哈希链
journal。

wm gate --target "python -m my_mcp_server"

• 工具名 → AI 动作映射：ai_governance.tool_patterns（glob，如 "fs_*": "write"），
  未匹配默认 execute
• 调用参数带 "preview": true 可满足 requires_preview
• 路径类参数启发式提取（path/file/dir/uri 等）
• 定位声明：这是治理与审计层，不是沙箱——管自觉的 agent，管不了绕过
  代理直连的恶意 agent

2. decision_id 执行链（intent → decision → execution）

• wm govern 返回 decision_id 并写入 journal
• wm clean / wm rollback / wm slim 接受 --decision-id（CLI + MCP
  wm_clean 参数）
• journal 现在能完整回答："agent 声称做什么 → 策略裁决什么 → 实际执行了什么"，
  每个环节都带策略哈希、可验证、可回滚

3. 配套

• schema：ai_governance.tool_patterns 字段
• 示例 policy 更新（wm_*/fs_*/shell_* 映射示例）
• README：AI governance 章节重写（gate 用法、preview 工作流、decision_id 链、
  沙箱边界）
• 测试 115 个全过（gate 全流程：放行/拦截/preview/未知工具/journal 链 +
  decision_id 闭环）

用法速览

pip install --upgrade workspace-metabolism
wm init                          # 生成策略文件
# metabolism.json 里配 ai_governance.tool_patterns + actions
wm govern write --path src/main.py          # 先问策略（决策入 journal）
wm gate --target "python -m my_server"      # 或直接包在代理后面强制执行
wm clean --grades G4 --yes --decision-id govern-20260901-...   # 执行链闭环

发布

python -m build
twine upload dist/workspace_metabolism-0.4.0-*
git tag v0.4.0 && git push origin v0.4.0

workspace-metabolism v0.3.1 — policy matching fixes

workspace-metabolism v0.3.1 — 发布说明

本次变更（自 v0.3.0，三个修复）

1. slim 策略匹配精确化（1055e90）：路径段精确匹配 + 最长匹配优先——泛条目
   （如 data）不再遮蔽具体条目（如 data/app.db）的 db_slim 配置；同时修掉
   了 p in rel 任意子串误匹配的问题
2. registry 自动发现容错（dc5923c）：策略目录不可读时 verify/slim
   不再崩溃
3. 全策略引擎的最具体条目优先（56f420c）：wm explain 之前返回列表第一个
   匹配条目（泛条目遮蔽具体条目，实测复现 G2/never 遮蔽 G4/auto）；wm clean
   的规划阶段现在会拦截"泛 G4 目录候选包含更具体 never 子路径"的情况，避免把
   策略保护的文件扫进回收站。新增 2 个回归测试，共 106 个测试全过

影响

• CLI / MCP 行为：explain 的营养标签现在永远指向最具体的策略条目；clean 规划
  更保守（宁可拦截，不碰 protected 路径）
• Glama 同步后重评不受影响（修复不改变工具面）

发布

python -m build
twine upload dist/workspace_metabolism-0.3.1-*
git tag v0.3.1 && git push origin v0.3.1

workspace-metabolism v0.3.0 — slim + govern

workspace-metabolism v0.3.0

What's new: wm slim — in-place SQLite trimming

Databases rot too. wm slim is the DB-internal analogue of wm clean:

• Never deletes rows or files — only rewrites one JSON blob column,
  dropping policy-listed heavy keys (e.g. factor_observations that nothing
  reads after they are stored).
• keep_recent — rows whose reference value is among the newest N distinct
  values (e.g. the newest N epochs) are left untouched.
• VACUUM — when the reclaim exceeds vacuum_min_gb, --yes also reclaims
  the freed pages.
• Journaled — every run lands in the hash-chained audit trail
  (action slim); dry-run by default, --yes to execute.
• Policy-driven — the policy entry for the database declares the recipe:

{
  "path": "data/app.db", "grade": "G2", "cleanup": "never",
  "db_slim": {
    "table": "work_units",
    "blob_column": "payload_json",
    "strip_keys": ["factor_observations"],
    "keep_recent": {"table": "epochs", "column": "created_at", "n": 3},
    "vacuum_min_gb": 1.0
  }
}

Run it (maintenance window, when the DB is not in use):

wm slim --db data/app.db            # dry-run: how many rows, how much reclaimable
wm slim --db data/app.db --yes      # execute + journal; VACUUM if reclaim >= 1 GB

CLI overrides exist for every policy field (--table, --blob-column,
--strip-keys, --keep-recent, --keep-table, --keep-column,
--vacuum-min-gb). Identifiers are validated against the database schema —
no free-form SQL.

Why this belongs in the metabolism tool

The audit trail answers "what happened to my workspace". Until v0.3.0 it was
file-only; databases were invisible and rotted silently (a 20.7 GB work
ledger caused minute-long queries in production). slim makes DB bloat a
first-class, policy-driven, audited lifecycle concern — the same
classify → audit → clean → rollback philosophy, applied inside the file.

workspace-metabolism v0.2.3

workspace-metabolism v0.2.3 — 发布说明

本次变更（自 v0.2.2）

• MCP 新增 wm_init 和 wm_rollback 工具（Glama Server Coherence 评审点名的两个缺口）：
  • wm_init：像 git init 一样为工作区生成 metabolism.json 策略文件（安全默认：源码/文档/密钥/dotfiles 永不清除）
  • wm_rollback：把之前 wm_clean 回收的条目按 SHA-256 校验后还原回原位（dry-run 默认）
  • 策略文件调用时自动发现：wm_init 之后同一 MCP 会话内 wm_audit 立即可用
• 两个新工具均按 TDQS 规范编写描述（Glama 实测：wm_rollback 4.9/5、wm_init 4.7/5）
• README 更新 Agents 章节

Glama 影响

• 服务器评分 17 → 67 → 92（Quality A），评估基于 GitHub 源码，已生效
• PyPI 0.2.2 → 0.2.3：让 pip 用户也拿到新工具

发布步骤

python -m build
twine upload dist/workspace_metabolism-0.2.3-*   # 需要 pypi-token.txt
git tag v0.2.3 && git push origin v0.2.3

workspace-metabolism v0.2.2

workspace-metabolism v0.2.2 — 发布说明草稿

上传 PyPI 需要 token。本机没有 pypi-token.txt，发布时按文末步骤操作。

本次变更（自 v0.2.1）

• MCP 工具定义全面重写（TDQS 规范）：5 个工具（wm_audit / wm_health /
  wm_explain / wm_verify / wm_clean）的描述现在完整说明"做什么、返回什么、
  何时用、何时不用"，所有参数都有说明——Glama 质量分 70% 取决于工具定义质量，
  评分已在审核队列中
• 新增 mcp.json：Claude Code / Cursor 等客户端可直接发现 stdio 服务器
• 新增 Dockerfile + .dockerignore：容器化构建与检查（Glama 评估用），
  也可用于自托管
• README 徽章：PyPI 版本 / Python 版本 / CI / License / 零依赖

发布步骤

# 1. 把 pyproject.toml 的 version 改为 0.2.2
# 2. 构建
python -m pip install --upgrade build twine
python -m build
# 3. 上传（需要 PyPI token，即 .gitignore 里的 pypi-token.txt）
twine upload dist/*
# 4. 打 GitHub release
git tag v0.2.2
git push origin v0.2.2

验证

• pip install workspace-metabolism==0.2.2 可安装
• wm mcp 的 tools/list 返回新描述（本机已实测 80+88 测试全绿）

workspace-metabolism v0.2.1

workspace-metabolism v0.2.1

One policy file controls the whole lifecycle of files in your multi-agent
workspace: classify, audit, clean (recyclable), rollback, and purge — every
step leaves a hash-chained audit trail. Python 3.11+, zero dependencies,
Windows / Linux / macOS.

The one-liner: loops keep the agent running; metabolism keeps the workspace
alive.

What's new in v0.2.1

• Memory-backed awareness in wm audit: on systems where a workspace
  location sits on tmpfs/ramfs (e.g. /tmp on modern Linux), the audit now
  says so — residue there costs RAM, not just disk. The report gains a
  memory section (workspace mount, memory-resident candidates and their
  size), the summary gains memory_candidates / workspace_on_memory, the
  journal records the count, and both the report and CLI print a hint when
  it matters. Degrades to a no-op where no memory-backed mounts are visible
  (Windows, macOS).
• The demo now shows the difference: python examples/demo.py contrasts
  the usual blind-delete fix (a file gone in place, no record, no undo) with
  the wm way — clean moves expired items to the recycle area, rollback
  restores them after a per-file SHA-256 check, verify confirms the journal
  chain. Deterministic 5-item comparison, all inside throwaway temp dirs.
• Positioning page: new docs/positioning.md — "What
  workspace-metabolism is not": not a fix for vendor bugs, not a heuristic
  classifier, not a rival to agent self-cleanup, not a blind-delete script.
  It exists because a public review on
  anthropics/claude-code#8856
  tested the project's first outreach comment; the four objections are
  answered in order there. The README gained a matching "What this is not"
  section.
• One-liner refresh: the project now introduces itself as the policy
  layer for multi-agent workspaces — Claude Code, Codex, Aider and OpenClaw
  all leave byproducts in the one thing they share: your workspace. Launch
  drafts and announcement copy were updated to match.

What's unchanged

• Safety model: clean is dry-run by default; G3 needs --approve +
  --approver; rollback verifies per-file SHA-256 and refuses to overwrite;
  purge is the only real delete, retention-gated and recycle-area-only.
• Zero dependencies; CI on Ubuntu / Windows / macOS (Python 3.11 & 3.12).
• The policy schema is still versioned and may shift before v1.0.

Install: pip install workspace-metabolism

Docs: README ·
positioning ·
philosophy ·
narrative

workspace-metabolism v0.2.0

workspace-metabolism v0.2.0

One policy file controls the whole lifecycle of files in an AI-driven
workspace: classify, audit, clean (recyclable), rollback, and purge — every
step leaves a hash-chained audit trail. Python 3.11+, zero dependencies,
Windows / Linux / macOS.

The one-liner: loops keep the agent running; metabolism keeps the workspace
alive.

What's new in v0.2.0

• wm init: scaffold a metabolism.json policy file like git init.
  The tool scans your workspace and grades common directories (source/docs
  keep, logs/tmp/cache auto, archive/staging approve).
• Auto-discovery: metabolism.json / .wm.json in the workspace root are
  found automatically, so --registry is optional.
• Policy JSON Schema in schema/metabolism.schema.json; new optional
  governance fields: owner, intent, review_after.
• wm explain <path>: the nutrition label for any path — what grade,
  what retention, whether it is a candidate right now, and why.
• wm health: a 0-100 workspace health score (auditability 25,
  governance 25, rot burden 35, recycle readiness 15) with --json and
  --badge (shields.io) output.
• wm mcp: a zero-dependency MCP stdio server so agents can run
  micro-metabolism themselves. Clean stays dry-run unless the caller
  explicitly passes execute=true.
• Ritual and CI: examples/micro_metabolism.py (the end-of-loop
  question) and examples/ci-audit.yml (a weekly health gate that fails
  below a configurable score).
• Community: ROADMAP, CONTRIBUTING, issue templates, an English essay
  (docs/publish/agentic-metabolic-engineering-essay.md) and a stack diagram
  in the narrative.

What's unchanged

• Safety model: clean is dry-run by default; G3 needs --approve +
  --approver; rollback verifies per-file SHA-256 and refuses to overwrite;
  purge is the only real delete, retention-gated and recycle-area-only.
• Zero dependencies; CI on Ubuntu / Windows / macOS (Python 3.11 & 3.12).

Install: pip install workspace-metabolism

Docs: README ·
philosophy ·
narrative

workspace-metabolism v0.1.2

workspace-metabolism v0.1.2

One policy file controls the whole lifecycle of files in an AI-driven
workspace: classify, audit, clean (recyclable), rollback, and purge — every
step leaves a hash-chained audit trail. Python 3.11+, zero dependencies,
Windows / Linux / macOS.

The one-liner: loops keep the agent running; metabolism keeps the workspace
alive.

What's new in v0.1.2

• Complete narrative. "Agentic Metabolic Engineering" is now framed as
  the fifth layer of the agentic engineering stack, with a one-liner, a
  three-act story (can write → keeps writing → writes without rotting), and a
  named human role (policy author). See
  docs/narrative.md.
• Reproducible proof. examples/metabolism_benchmark.py simulates 30
  agent loops in two identical workspaces (governed vs ungoverned) and prints
  the numbers quoted in the narrative: after 30 loops, the governed workspace
  holds 2 active files and 0 expired candidates; the ungoverned one holds 242
  files and 240 expired candidates, and every governed byproduct is
  recoverable via wm rollback.
• Reliability fix. audit and clean run IDs now include microseconds.
  Previously, two runs started in the same second produced the same run ID;
  the second run could overwrite the first run's manifest, silently orphaning
  the first recycle batch. This matters exactly for the narrative's
  micro-metabolism scenario: an agent running clean at the end of every
  loop. Regression tests added.
• Copy in Chinese and English. Updated launch draft, Zhihu article, X
  post, and GitHub announcement with the one-liner and the three-act story.

What's unchanged

• Safety model: clean is dry-run by default; G3 needs --approve +
  --approver; rollback verifies per-file SHA-256 and refuses to overwrite;
  purge is the only real delete, retention-gated and recycle-area-only.
• Policy grades G1–G4 in one JSON file; nothing happens the policy doesn't
  allow.
• Zero dependencies; CI on Ubuntu / Windows / macOS (Python 3.11 & 3.12).

It's early days (v0.1.x), so the policy schema might have minor tweaks before
v1.0. Issues and PRs are welcome.

workspace-metabolism v0.1.1

workspace-metabolism v0.1.1

One policy file controls the whole lifecycle of files in an AI-driven workspace: classify, audit, clean (recyclable), rollback, and purge — every step leaves a hash-chained audit trail. Python 3.11+, zero dependencies, Windows / Linux / macOS.

What's in v0.1.1:

• wm audit --json summary block: growth, recycle ratio, journal chain, governance (the measurement ritual in docs/narrative.md)
• Policy grades G1–G4; clean is dry-run by default; G3 needs --approve + --approver
• Rollback with per-file SHA-256; purge is the only real delete, retention-gated, recycle area only
• Scheduling templates for cron and Windows Task Scheduler

Install: pip install workspace-metabolism
Docs: philosophy.md (framing) · narrative.md (story) · README

It's early days (v0.1), so the policy schema might have minor tweaks before v1.0. Issues and PRs are welcome.

workspace-metabolism v0.1.0

First public release of workspace-metabolism: policy-driven file lifecycle management with recyclable clean, rollback, hash-chained audit, and dual-OS scheduled runs. Install: pip install workspace-metabolism