From 646160b85fb28df2c4063405f7d0233081b19388 Mon Sep 17 00:00:00 2001 From: David Abram Date: Fri, 4 Sep 2026 02:29:40 +0200 Subject: [PATCH] skills: Add SCE context audit workflow Add a repository-bound workflow for reconciling durable current-state context with implementation evidence. Define bounded repair, protected-path, and post-write verification rules alongside stable terminal output layouts. --- .pi/skills/sce-audit/SKILL.md | 266 ++++++++++++++++++++++ .pi/skills/sce-audit/references/output.md | 82 +++++++ 2 files changed, 348 insertions(+) create mode 100644 .pi/skills/sce-audit/SKILL.md create mode 100644 .pi/skills/sce-audit/references/output.md diff --git a/.pi/skills/sce-audit/SKILL.md b/.pi/skills/sce-audit/SKILL.md new file mode 100644 index 000000000..c7c0c02e9 --- /dev/null +++ b/.pi/skills/sce-audit/SKILL.md @@ -0,0 +1,266 @@ +--- +name: sce-audit +description: > + Audit an SCE repository's durable current-state context against the repository's + current implementation, classify context drift, repair only evidence-backed + current-state drift, and verify the result. Use when the user asks to run an SCE + context audit, reconcile context/ with code, find stale or missing SCE context, + or check whether the repository's SCE context correctly describes the system as + implemented. Do not use for brownfield reconstruction, decisions, plans, + handovers, task execution, plan validation, or ordinary code review. +--- + +# SCE Audit + +## Purpose + +Own this workflow from repository binding through its terminal user-visible +response. Execute the steps below directly and in order. Intermediate findings are +internal state, not inter-SCE workflow handoffs. Do not invoke another SCE skill, +sibling SCE package, or SCE workflow command. + +This workflow performs an explicit whole-repository reconciliation of existing +current-state `context/` against the system as implemented now. It complements +`sce-brownfield`: brownfield reconstructs missing context, while audit checks and +repairs existing context. It also complements task context synchronization: task +sync maintains context incrementally, while audit is an explicit whole-context +check. + +Relevant non-SCE skills may be used as helper capabilities during the active step. +A helper must return control to this workflow and must not alter the workflow's +scope, protected paths, write boundaries, verification, or terminal output. + +## User-visible output + +Read `references/output.md` before emitting any gate or terminal response. Use only +an applicable layout from that file. Do not expose the internal evidence ledger or +raw chain-of-thought. Summarize findings and evidence in the fields the layout +provides. + +## Input + +Bind to exactly one repository. + +- Prefer the repository explicitly named, linked, attached, or opened by the user. +- When exactly one repository is already unambiguously in scope, use it. +- When repository access can resolve the target without asking, inspect available + repository metadata first. +- When more than one repository remains plausible, ask which repository to audit + and stop. + +The repository identifier is environment binding, not audit scoping. A successful +run always audits the complete current-state context surface. Do not accept a path, +domain, file, or glob as a way to narrow the audit. If the user explicitly requests +a partial audit, render the **Unsupported scoped audit** layout and stop. + +## Workflow + +### 1. Confirm the context root + +Confirm that `context/` exists before gathering implementation evidence. + +When it does not exist, render the **Missing context bootstrap gate** layout with +`sce setup --bootstrap-context` as the required action and stop. Do not create the +context root from this workflow. + +### 2. Establish the current-state context surface + +Audit every file under `context/` whose purpose is to describe the system as it +exists now. + +Always include these root files when present: + +- `context/overview.md` +- `context/architecture.md` +- `context/patterns.md` +- `context/glossary.md` +- `context/context-map.md` + +Include current-state domain files and operational or contract documents linked +from the context map or otherwise clearly part of the repository's current-state +context. + +The following areas are protected lifecycle or historical state, not current-state +audit targets: + +- `context/decisions/` +- `context/plans/` +- `context/handovers/` +- `context/tmp/` + +Never create, edit, move, rename, or delete anything in a protected area. Do not +use a protected file as authority for what the system does now. If a current-state +file links to protected history, the link may be checked for integrity, but the +historical content does not outrank implementation evidence. + +Record the audit surface before classifying findings. + +### 3. Gather implementation evidence + +Use current implementation evidence as authority. Read enough of the repository to +establish the behavior, boundaries, contracts, and ownership that current-state +context is expected to describe. + +Use this evidence priority when sources disagree: + +1. Current source code and generated executable behavior. +2. Tests, schemas, migrations, build manifests, dependency manifests, executable + configuration, deployment configuration, and runtime configuration. +3. Repository documentation that describes current behavior. +4. Existing current-state `context/`, which is the subject being audited rather + than an authority over implementation. + +Inspect repository structure broadly enough to cover: + +- Entry points, executables, packages, modules, services, and published interfaces. +- Dependency direction and important architectural boundaries. +- Data models, persistence, schemas, migrations, and external integrations. +- Configuration surfaces and deployment/runtime behavior. +- Error handling, important invariants, and behavior protected by tests. +- User-visible or operator-visible capabilities that belong in durable context. + +Do not use Git history, commit messages, plans, decisions, handovers, or external +web documentation as current-state authority. Repository access through a connected +Git provider is allowed for reading the repository itself; unrelated network +research is not evidence for this audit. + +### 4. Build the bidirectional audit ledger + +Audit in both directions before writing anything. + +#### 4.1 Context -> implementation + +For every material current-state claim in the audit surface, compare the claim with +implementation evidence and classify it as exactly one of: + +- **verified** — current implementation evidence supports the claim. +- **drifted** — the same concern exists, but the current implementation differs + materially from what context says. +- **orphaned** — context describes a capability, boundary, component, integration, + or contract that implementation evidence proves no longer exists. +- **unverifiable** — available current implementation evidence is insufficient or + contradictory, so changing the claim would require guessing. + +#### 4.2 Implementation -> context + +For every material implemented capability, boundary, contract, ownership rule, or +operational fact that belongs in durable current-state context, check whether +context represents it and classify it as: + +- **verified** — context already represents it accurately. +- **missing** — implementation evidence proves the fact, but current-state context + omits it materially. +- **unverifiable** — it is unclear whether the fact belongs in durable context or + current evidence is insufficient to state it safely. + +A wording difference is not drift. Classify only differences that would cause a +reader or coding agent to form a materially wrong model of the implemented system. + +Keep the ledger internal. For every non-verified finding, retain the context path or +implementation location, concise evidence, classification, and intended action. + +### 5. Decide which findings are repairable + +Repair only proven current-state drift backed by implementation evidence. + +- **verified** -> make no change. +- **drifted** -> update the existing current-state statement when the correct state + is directly supported by implementation evidence. +- **missing** -> add the missing current-state fact to the most appropriate existing + context file, or create a focused current-state domain file when no existing file + owns the topic. +- **orphaned** -> remove or replace the obsolete current-state statement only when + current implementation evidence proves it false. When removal would require + guessing about intended ownership or replacement, reclassify it as + **unverifiable**. +- **unverifiable** -> never edit the affected claim from this finding. Preserve it + and report what evidence is missing. + +Before writing, detect whether a target context file has uncommitted user changes +when the environment exposes that information. Never overwrite a dirty target file. +Move that repair to **unverifiable/blocked** and preserve the user's work. + +If the environment cannot modify repository files without staging, committing, +pushing, or otherwise crossing the Git boundaries in this skill, do not perform the +write. Preserve the repository and render the **Blocked** layout with the proposed +repair targets and retry condition. + +### 6. Apply bounded context repairs + +Write only current-state context required by repairable findings. + +Every write must obey all of these rules: + +- Describe the system as it exists now, not the audit process and not a change + narrative. +- Preserve the repository's established context structure and terminology. +- Prefer editing the file that already owns the topic over creating a parallel file. +- Keep one topic per file and keep files concise; when the repository follows the + SCE 250-line hygiene rule, do not exceed it. +- Use relative Markdown links between context files. +- Update `context/context-map.md` when a new current-state file is created or an + existing discoverability entry must change because of a proven repair. +- Add glossary entries only for domain language the implementation currently uses + and the glossary does not define. +- Never write confidence scores, audit classifications, commit hashes, timestamps, + or audit dates into durable current-state context. + +Never modify application code, tests, schemas, migrations, build files, runtime +configuration, deployment configuration, or any other implementation artifact. +Never modify `context/decisions/`, `context/plans/`, `context/handovers/`, or +`context/tmp/`. + +### 7. Verify after writing + +After all bounded repairs, perform a fresh verification pass. Do not assume a write +is correct because it matched the intended patch. + +Verify all of the following: + +- Every changed current-state claim is supported by current implementation evidence. +- Every repaired **drifted**, **missing**, or **orphaned** finding now classifies as + **verified**. +- No **unverifiable** finding was silently changed. +- No protected path changed. +- No implementation file changed. +- Dirty context files, when detectable, were preserved. +- New current-state files are discoverable through `context/context-map.md`. +- Relative links introduced or changed by the audit resolve. +- No audit metadata, confidence score, commit hash, timestamp, or audit date was + written into durable context. + +When the environment exposes a repository diff, inspect it as part of this step and +confirm that every changed path and hunk belongs to a ledger repair. Never stage or +commit the diff. + +When a verification failure can be repaired without inventing a fact, repair the +context and rerun the failed check. Otherwise render the **Blocked** layout and stop. + +### 8. Report + +Render the **Completed audit** layout from `references/output.md`. + +Report counts for `verified`, `drifted`, `missing`, `orphaned`, and `unverifiable` +from the pre-repair audit, list context files changed, summarize unresolved findings, +and state whether post-write verification passed. + +Stop. Do not start another SCE workflow. + +## Rules + +- Audit at most one repository per invocation. +- Audit the full current-state context surface; never silently narrow scope. +- Use implementation and executable configuration as current-state authority. +- Never treat decisions, plans, handovers, temporary context, or Git history as + current-state authority. +- Never modify `context/decisions/`, `context/plans/`, `context/handovers/`, or + `context/tmp/`. +- Never modify implementation code, tests, configuration, schemas, or migrations. +- Never repair an **unverifiable** finding by guessing. +- Never create a decision or invoke `sce-decision`. +- Never create or update a plan, execute a task, synchronize plan state, or invoke + `sce-next-task`, `sce-change-to-plan`, or `sce-validate`. +- Never stage files, create a Git commit, push, switch branches, rebase, reset, or + rewrite repository history. +- Never create the `context/` root. +- Never infer success when post-write verification fails. diff --git a/.pi/skills/sce-audit/references/output.md b/.pi/skills/sce-audit/references/output.md new file mode 100644 index 000000000..5b78e7292 --- /dev/null +++ b/.pi/skills/sce-audit/references/output.md @@ -0,0 +1,82 @@ +# Audit output layouts + +Use only the applicable layout. Values come from workflow state. Omit empty detail +lists, but keep all status and count fields. + +## Missing context bootstrap gate + +```markdown +------------------------------------- + +# SCE context audit blocked. + +`context/` does not exist in {repository}. + +Required action: `sce setup --bootstrap-context` + +No repository files were changed. +``` + +## Unsupported scoped audit + +```markdown +------------------------------------- + +# SCE context audit not started. + +`sce-audit` audits the complete current-state `context/` surface. +Path-, file-, domain-, and glob-scoped audits are not supported. + +Repository: {repository} +No repository files were changed. +``` + +## Blocked + +```markdown +------------------------------------- + +# SCE context audit blocked. + +Repository: {repository} +Reason: {reason} + +Preserved files: +- {preserved-path}: {why-preserved} + +Pending repairs: +- {target-path}: {repair-summary} + +Retry condition: {retry-condition} + +No Git commit was created. +``` + +## Completed audit + +```markdown +------------------------------------- + +# SCE context audit complete. + +Repository: {repository} +Status: {clean|repaired} + +Findings before repair: +- verified: {verified-count} +- drifted: {drifted-count} +- missing: {missing-count} +- orphaned: {orphaned-count} +- unverifiable: {unverifiable-count} + +Context changes: +- {context-path}: {repair-summary} + +Unresolved: +- {classification}: {summary} — {evidence-gap} + +Protected areas: unchanged +Implementation files: unchanged +Post-write verification: passed +No Git commit was created. +```