release-audit
Detect-only pre-release validation sweep over the processkit content tree. Walks entity files, SKILL.md definitions, MCP server tools, and cross-references, then emits a single human-readable report with ERROR / WARN / INFO counts. Use when the user invokes `/pk-release-audit`, before tagging a release, or any time you need a comprehensive structural health check beyond what pk-doctor covers. Detect-only; never modifies any file under `context/`.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- release-audit
- metadata
- { "processkit": { "id": "SKILL-release-audit", "uses": [ { "skill": "pk-doctor", "purpose": "Complementary health check — pk-doctor covers schema/drift/migration checks; release-audit covers entity frontmatter, skill structure, MCP tool annotations, and cross-references." } ], "layer": 3, "created": 1777161600000, "version": "1.0.0", "category": "processkit", "commands": [ { "args": "[--repo-root=<path>] [--tree=context|src-context|both]", "name": "pk-release-audit", "description": "Run the pre-release validation sweep and print a single report." } ], "apiVersion": "processkit.projectious.work/v2" } }
- description
- Detect-only pre-release validation sweep over the processkit content tree. Walks entity files, SKILL.md definitions, MCP server tools, and cross-references, then emits a single human-readable report with ERROR / WARN / INFO counts. Use when the user invokes `/pk-release-audit`, before tagging a release, or any time you need a comprehensive structural health check beyond what pk-doctor covers. Detect-only; never modifies any file under `context/`.
02 资源文件 5
- 参考文档commands/pk-release-audit.md277 B
- 脚本mcp/server.py3.6 KB
- 脚本scripts/release_audit.py32.3 KB
- 脚本scripts/test_release_audit_json.py4.8 KB
- 脚本scripts/test_release_audit.py23.9 KB
03 SKILL.md 正文
release-audit
Intro
/pk-release-audit is the structural correctness sweep you run before
tagging a processkit release. It answers: "are all entity files, skill
definitions, MCP server tools, and cross-references internally consistent?"
without modifying any file.
The skill complements pk-doctor: doctor covers schema validation, drift
between context/ and src/context/, and pending migrations; release-audit
covers entity frontmatter correctness, SKILL.md structural requirements, MCP
tool annotation completeness, and uses: cross-reference resolution.
Exit code is 0 if there are no ERRORs (WARNs are permitted), 1 if any
ERROR is found. This makes it suitable as a blocking CI gate before git tag.
Overview
Invocation
/pk-release-audit # detect-only; all four checks; report to stdout
uv run --script context/skills/processkit/release-audit/scripts/release_audit.py
uv run --script .../release_audit.py --repo-root=/path/to/repo
uv run --script .../release_audit.py --tree=src-context
uv run --script .../release_audit.py --tree=both
Exit code 0 = clean (0 ERRORs). Exit code 1 = at least one ERROR found.
The default context tree is the live dogfood/project tree. src-context
audits the shipped release deliverable tree under src/context/ and does
not warn when dogfood-only entity directories such as workitems/ or
decisions/ are absent.
The four checks
-
entity_files— walks every selected tree's<dir>/*.mdfor the registered entity directories (workitems,decisions,logs,artifacts,actors,bindings,scopes,gates,roles,migrations,team,team-members,notes,discussions). For each file verifies:- YAML frontmatter is present and parseable (between
---markers). apiVersion: processkit.projectious.work/v2is present.kind:is present and is one of the 13 registered kinds.metadata.idis present and matches the filename stem.
- YAML frontmatter is present and parseable (between
-
skill_structure— walks every selected tree'sskills/**/SKILL.md. For each file verifies:- Frontmatter has
name,description,metadata.processkit.apiVersion,metadata.processkit.id,metadata.processkit.version,metadata.processkit.category, andmetadata.processkit.layerfor processkit-category skills. - Body contains the four required sections:
## Intro,## Overview,## Gotchas,## Full reference.
- Frontmatter has
-
mcp_annotations— walks every selected tree'sskills/**/mcp/server.py. For each file verifies that every@server.tool(...)decoration includes anannotations=ToolAnnotations(...)argument containing all four required hint keys:readOnlyHint,destructiveHint,idempotentHint,openWorldHint. -
cross_references— walks every selected tree'sskills/**/SKILL.mdand readsmetadata.processkit.uses[*].skill. For each named skill, checks that a correspondingSKILL.mdexists atcontext/skills/<category>/<name>/SKILL.md(searches all category directories, not justprocesskit/). ERROR per unresolvable reference.
What release-audit will NEVER do
- Modify any file under
context/orsrc/context/. - Validate YAML schemas against
src/context/schemas/— that is pk-doctor'sschema_filenamecheck. - Write to
context/logs/— this tool is a CLI script, not an MCP server. - Block on missing
context/templates/— the template mirror is not consulted.
Report shape
# pk-release-audit v1.0.0
repo_root: /path/to/repo
## entity_files — 0 ERROR / 0 WARN / 47 INFO
[i] BACK-20260409_1449-BoldVale-fts5-full-text-search (workitems) — OK
## skill_structure — 1 ERROR / 0 WARN / 36 INFO
[E] skill.missing-section — context/skills/foo/bar/SKILL.md missing section: ## Gotchas
## mcp_annotations — 0 ERROR / 0 WARN / 12 INFO
[i] skill-gate:acknowledge_contract — annotations present
## cross_references — 0 ERROR / 0 WARN / 14 INFO
[i] pk-doctor → event-log — resolved
## totals — 1 ERROR / 0 WARN / 109 INFO
Gotchas
Agent-specific failure modes — provider-neutral pause-and-self-check items:
- Running release-audit as a replacement for pk-doctor. The two tools complement each other. Release-audit does NOT check schema conformance, drift, or pending migrations. Always run both before tagging.
- Treating cross-reference ERRORs as false positives. The
uses:resolver searches allcontext/skills/<category>/<name>/SKILL.mdpaths. If a skill truly exists but is in an unexpected location, the fix is to correct theuses:entry, not to suppress the check. - Fixing ERRORs by editing files directly without understanding the cause.
A
metadata.idmismatch ERROR means either the file was renamed without updating the frontmatter, or the frontmatter was edited without renaming the file. The correct fix depends on which copy is canonical — check git history. - Running release-audit against a partial tree. The script walks the live
context/tree from the detected repo root. Running it in a worktree or checkout missing some files will produce false ERRORs for every absent entity directory. Use--tree=src-contextwhen auditing only the shipped release deliverable. - Ignoring WARNs before a release. WARNs indicate structural drift that does not prevent the release but will accumulate into ERRORs in future versions. Address all WARNs before a minor or major release.
Full reference
CLI contract
release_audit.py [--repo-root=PATH] [--tree=context|src-context|both]
| Flag | Meaning |
|---|---|
--repo-root |
Explicit repo root path. Defaults to git rev-parse --show-toplevel. |
--tree |
context audits the live tree, src-context audits the release deliverable tree, and both audits both. |
Registered entity kinds
| kind | directory |
|---|---|
WorkItem |
workitems/ |
DecisionRecord |
decisions/ |
LogEntry |
logs/ |
Artifact |
artifacts/ |
Actor |
actors/ |
Binding |
bindings/ |
Scope |
scopes/ |
Gate |
gates/ |
Role |
roles/ |
Migration |
migrations/ |
TeamMember |
team-members/ |
Note |
notes/ |
Discussion |
discussions/ |
Required SKILL.md frontmatter fields
name(string)description(string)metadata.processkit.apiVersion(string)metadata.processkit.id(string, must start withSKILL-)metadata.processkit.version(string)metadata.processkit.category(string)metadata.processkit.layer(integer or null)
Required SKILL.md body sections
## Intro## Overview## Gotchas## Full reference
Required MCP tool annotation keys
readOnlyHintdestructiveHintidempotentHintopenWorldHint
Adding a check in future versions
- Add a new check function in
release_audit.pyfollowing therun_<name>(repo_root) -> list[Finding]pattern. - Register it in
CHECKSat the bottom of the file. - Add a gotcha for that check in this SKILL.md.
- Mirror the updated script to
src/context/skills/processkit/release-audit/scripts/.
04 同仓库更多 Skills
standard-ui-design
暂无简介
standard-agent-use
Company standard for working with AI agents. Use when deciding what to delegate to agents, capturing open work, keeping agent memory or knowledge notes, improving an agent workflow, or introducing agent work in a team or for a client.
standard-agent-building
暂无简介
skill-management
Manage Skill package manifests as v1 ontology entities.
schema-management
Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.
proposition-management
Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.