spec-merge-cleanup
Skill4 starsChanged 4 months agoApache-2.0View on GitHub
Complete one reviewed Spec by validating the exact v2 review state, merging or directly closing the Spec, cleaning branch/review state idempotently, reconciling governing Wayfinders, and rebuilding Project projection from durable lifecycle authority.
In this repository51 other files it gives its agents.
- AGENTS.mdAGENTS.md
- architecture-remediationSkill
- attentionSkill
- classify-docSkill
- codebase-designSkill
- codebase-memory-mcpSkill
- codegraphSkill
- coding-standardsSkill
- contract-ledgerSkill
- conventional-commitsSkill
- database-migrationsSkill
- deduplicate-codeSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- format-codeSkill
- github-issue-dependenciesSkill
- graphifySkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implement-ticketSkill
- improve-codebase-architectureSkill
- project-delivery-managementSkill
- project-trackingSkill
- prototypeSkill
- repowiseSkill
- researchSkill
- resolving-merge-conflictsSkill
- review-architectureSkill
- review-specSkill
- setup-matt-pocock-skillsSkill
- spec-contractSkill
- tddSkill
- teachSkill
- to-adr-docSkill
- to-docSkill
- to-specsSkill
- to-ticketsSkill
- triageSkill
- verify-architectureSkill
- verify-codeSkill
- verify-spec-closureSkill
- verify-specSkill
- verify-ticket-closureSkill
- verify-ticket-decompositionSkill
- wayfinderSkill
- wiki-lintSkill
- wiki-syncSkill
- wiki-synthesizeSkill
- writing-great-skillsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 6 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
every current governing Wayfinder from Spec-local provenance and canonical Wayfinder handoffs.
- Distinctive: line 32
If any required identity is missing, duplicated, contradictory, or stale, fail closed and return the owning lifecycle rather than …
- Distinctive: line 79
Do not require, parse, synthesize, or accept historical remediation compatibility fields or legacy finding-ledger markers as current …
- Very specific: line 91
When proven, call the newer tip AUTHORIZED_DELIVERY_TIP.
- Very specific: line 96
Use canonical GitHub issue/PR/branch state, not Project state.
- Very specific: line 117
Run this section only for pre-completion.
- Very specific: line 131
When neither local nor remote spec-<n> exists and no branch-backed completion is present, revalidate Review Exit Authorization, close the …
- Very specific: line 147
Do not delete the branch as part of the merge operation.
- Distinctive: line 162
After authoritative Spec completion is proven, close the conventional Spec Review if it is still open.
- Very specific: line 182
After all unambiguous map transitions, invoke $project-delivery-management reconcile.
- Distinctive: line 189
After Spec completion, Review cleanup, Wayfinder reconciliation, dependent actionability, and project-delivery reconciliation are durable, …
- Very specific: line 202
Do not use historical remediation compatibility state or current Project rows to derive lifecycle truth.
- Very specific: line 209
If projection fails after lifecycle completion, report PROJECT TRACKING: DRIFT.
- Distinctive: line 214
After authoritative Spec completion is proven and the remaining Review, Wayfinder, project-delivery, and Project projection work above has …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Spec Merge & Cleanup
$spec-merge-cleanup is the authoritative completion boundary after $review-spec PASS.
It consumes the current structured review ledger directly. Historical remediation
compatibility fields/markers are not completion authority.
1. Recover durable completion inputs
Assume no prior chat/session state.
Recover:
- parent Spec issue and current state;
- exact current Spec body, branch/baseline metadata, and latest passing Spec Verification Receipt;
- exactly one conventional
Spec Review: ...issue for the Spec; - exactly one current
review-spec-finding-ledger:v2comment on that Spec Review; - latest Spec Review Exit Receipt on that Spec Review;
- current branch/PR state when the Spec is branch-backed;
- current native Spec blockers/dependents;
- every current governing Wayfinder from Spec-local provenance and canonical Wayfinder handoffs;
- current project-delivery state.
Project fields and prior conversation are never lifecycle authority.
If any required identity is missing, duplicated, contradictory, or stale, fail closed and return the owning lifecycle rather than reconstructing intent from prose.
2. Validate current review authorization
Build the deterministic current Spec contract and validate the current v2 finding ledger:
python -m scripts.ccl_spec check <spec-body-file> contracts/ccl/transactions
python -m scripts.spec_contract build <spec-issue-json> <spec-contract.json>
python -m scripts.review_remediation validate-ledger <spec-contract.json> <review-findings.json>Require SPEC CONTRACT: VALID and REVIEW FINDING LEDGER: VALID.
Hash the exact managed finding-ledger comment body as persisted by $review-spec; do not
normalize whitespace or otherwise change bytes.
The Exit Receipt must be current and contain:
## Spec Review Exit Receipt
**Status:** passed
**Spec Review:** #<review issue>
**Reviewed HEAD:** <full SHA>
**Reviewed Baseline:** <full Spec baseline SHA>
**Branch:** spec-<spec> | None
**Spec Body Hash:** <hash>
**Spec Contract Hash:** <hash>
**Finding Ledger Hash:** <sha256 of exact managed ledger body>
**Blocking findings:** 0
**Open blocking findings:** 0
**Unaccounted prior findings:** 0
**Unresolved continuity cells:** 0
**Unresolved decomposition defects:** 0
**Review coverage:** complete
**Unchecked coverage cells:** 0Require exact agreement with the current Spec baseline, current deterministic contract, current finding-ledger hash, and latest passing Spec Verification Receipt for the same semantic candidate.
Also validate from the v2 ledger that open Blocking findings, cell-routing defects, contract-authority gaps, and planning-cell gaps are all zero.
Do not require, parse, synthesize, or accept historical remediation compatibility fields or legacy finding-ledger markers as current completion state.
Semantic anchor vs authorized delivery tip
The Exit Receipt's Reviewed HEAD is the semantic anchor. Normally it equals the branch tip.
A newer tip is admissible only under the repository-wide Non-Semantic Workflow-Policy
Synchronization rule in AGENTS.md: Reviewed HEAD is an ancestor of the tip, the complete
delta is limited to permitted workflow/process surfaces, no product/test/migration/
configuration/architecture/Spec/CCL/coverage/finding semantic state changed, and current
deterministic validation reproduces the receipt-bound contract identity.
When proven, call the newer tip AUTHORIZED_DELIVERY_TIP. Otherwise review authorization is
stale and $review-spec must run again.
3. Detect lifecycle phase before mutation
Use canonical GitHub issue/PR/branch state, not Project state. Classify exactly one:
pre-completion
Spec is open; authoritative completion has not occurred
post-merge recovery
Spec is closed by exactly one merged spec-<n> PR whose recorded head is the
AUTHORIZED_DELIVERY_TIP; merge commit is reachable from current main; any remaining
local/remote Spec branch still points to that exact tip
post-direct-close recovery
branchless Spec is closed and carries this workflow's durable direct-close completion
evidence; no Spec branch/merge PR existsA closed Spec that cannot prove one recovery mode is ambiguous. Fail closed; never reopen or infer how it completed.
4. Project-delivery actionability for a new completion transition
Run this section only for pre-completion. Independent Specs remain independent.
For every Wayfinder-managed Spec, require the Spec open and native Spec blockers closed,
recover every current governor, invoke $project-delivery-management reconcile, invoke
guard <Wayfinder> for each governor, and require at least one exact
PROJECT DELIVERY GUARD: ALLOWED result.
This workflow never establishes, switches, or broadens project focus. Do not re-run the pre-completion focus gate merely to finish a proven post-completion recovery.
5. Complete the Spec
Branchless Spec
When neither local nor remote spec-<n> exists and no branch-backed completion is present,
revalidate Review Exit Authorization, close the Spec exactly once with the canonical
direct-close completion comment, re-read and require CLOSED, then continue to Review
cleanup, Wayfinder reconciliation, project-delivery reconciliation, and Project
reconstruction.
A rerun after that transition uses post-direct-close recovery; never close again.
Branch-backed Spec
For pre-completion, require the branch tip equals AUTHORIZED_DELIVERY_TIP, push without
force, reuse the one open PR from spec-<n> to main or create it idempotently with
Closes #<spec>, require the PR head SHA equals the authorized tip, merge with a regular
merge commit rather than squash, and require PR state MERGED, Spec state closed, and the
merge commit reachable from main.
Do not delete the branch as part of the merge operation. Any failure after the merge
transition is cleanup drift; the next invocation must prove post-merge recovery and resume.
6. Branch cleanup is idempotent and fail-closed
For branch-backed completion or post-merge recovery, sync main with fast-forward-only
semantics, require the matching merge commit reachable from main, require Reviewed HEAD
to be an ancestor of main, and delete local/remote Spec branches only when their current
tips equal AUTHORIZED_DELIVERY_TIP. Never force-delete a drifted branch.
A branch tip that moved after the reviewed merge is a Hard Blocker for cleanup only. It does not roll back the already completed Spec.
7. Close the conventional Spec Review
After authoritative Spec completion is proven, close the conventional Spec Review if it is still open. If already closed, treat it as an idempotent no-op.
The v2 finding ledger and Exit Receipt remain historical completion evidence on the closed review issue. Do not rewrite them during cleanup.
8. Reconcile every governing Wayfinder
Spec closure is the native dependency-completion boundary; do not write a second synthetic satisfaction marker.
For every current governing Wayfinder build one working completion record with the complete
governed Spec set, open Wayfinder decisions, unresolved in-scope fog, governance ambiguity,
and a disposition of complete | remain-open | ambiguous.
complete requires all currently governed Derived/Remediation Specs closed, zero open
Wayfinder decisions, zero unresolved in-scope fog, and no governance ambiguity. Persist one
idempotent completion comment and close the Wayfinder if still open. remain-open leaves it
open. ambiguous leaves it untouched and reports reconciliation drift.
After all unambiguous map transitions, invoke $project-delivery-management reconcile. A
completed/ineligible map must leave focus; reconciliation never auto-selects a replacement.
9. Reconstruct Project projection once
Project is an eventually consistent projection, not lifecycle authority.
After Spec completion, Review cleanup, Wayfinder reconciliation, dependent actionability, and project-delivery reconciliation are durable, reconstruct one complete Project manifest from authoritative tracker/repository state containing the completed parent Spec, all native Implementation Ticket children, the conventional Spec Review, all native Review Remediation Ticket children, all current governing Wayfinders, required Wayfinder Decision children needed for complete lineage, direct dependent Specs whose actionability changed, and any additional formal artifact required for internal consistency.
For each artifact derive current lifecycle projection from owning durable authority: issue hierarchy/dependencies, deterministic contract/coverage state, ticket closure receipts, Spec Verification/Review receipts, Wayfinder state, project-delivery state, and explicit supersession/retirement authority.
Do not use historical remediation compatibility state or current Project rows to derive
lifecycle truth. Recover terminal completion dates from lifecycle-authoritative completion
evidence, not merely issue closed_at.
Invoke $project-tracking exactly once with the complete reconstructed projection set and
preserve Area/Priority unless separately authorized.
If projection fails after lifecycle completion, report PROJECT TRACKING: DRIFT. Do not
reopen lifecycle artifacts or restore branches.
Final best-effort Workflow Invocation Journal GC
After authoritative Spec completion is proven and the remaining Review, Wayfinder,
project-delivery, and Project projection work above has been attempted, perform final
best-effort cleanup of disposable Workflow Invocation Journals whose exact immutable
lifecycle_scope is this Spec. The canonical WIJ contract is
.agents/skills/WORKFLOW_INVOCATION_JOURNAL.md.
Run:
python -m scripts.workflow_journal gc \
--lifecycle-scope-url <canonical Spec issue URL>WORKFLOW JOURNAL GC: COMPLETE is the ordinary result. WORKFLOW JOURNAL GC: DEGRADED, a
missing helper, unreadable journal storage, or any other WIJ cleanup failure is report-only
cleanup degradation. Do not roll back authoritative Spec completion, reopen lifecycle
artifacts, restore a deleted Spec branch, or repeat Project projection solely because WIJ GC
failed.
GC may remove terminal or nonterminal journals for the completed Spec. It matches exact
lifecycle_scope identity, never branch-name inference. Independent clones outside the
repository's Git common directory remain outside this cleanup boundary and disappear with
their clone.
This final placement also ensures a future resumable $spec-merge-cleanup invocation does
not delete its own active journal before its remaining completion work is attempted.
10. Completion criteria
Success requires the current v2 finding ledger to validate against the current deterministic Spec contract; the Exit Receipt to bind the current semantic candidate and ledger hash; zero open Blocking findings/routing defects/contract-planning gaps; exactly one authoritative Spec completion transition or an exact post-completion recovery; closed conventional Spec Review; safe branch cleanup for branch-backed work; an explicit completion disposition for every unambiguously recovered governor; project-delivery reconciliation after completion transitions; and one complete Project reconstruction/projection attempt.
WIJ garbage collection is best-effort housekeeping and is deliberately not a success criterion. A cleanup failure after authoritative Spec completion never invalidates the completion transition. Resume from durable state and perform only remaining idempotent work.
Non-goals
$spec-merge-cleanup does not interpret review prose into findings, parse historical
remediation compatibility receipt fields, consume legacy finding-ledger markers as current
state, reopen a completed Spec because cleanup/project projection failed, guess Wayfinder
governance, use Project projection as lifecycle authority, force-delete a drifted branch,
create semantic requirements, or make WIJ cleanup a prerequisite for completion.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

