tvproductions/gzkit / .agents/skills/gz-adr-promote
gz-adr-promote
VerifiedUse to promote a pool ADR (ADR-pool.*) into an active, versioned ADR package.
gz adr promote
Overview
Turn one pool ADR into a versioned ADR package with one OBPI brief per checklist
item, and record the move in the ledger. uv run gz adr promote <POOL-ADR> --semver X.Y.Z --kind feature (adr_promote_cmd,
src/gzkit/commands/adr_promote.py; parsing helpers in adr_promote_utils.py):
- refuses before any I/O, exit 1 (
_validate_promotion_kind_semver): a missing--kind;--kind pool(pool is the source kind);--kind foundationwhere the kind is closed (data/foundation_grandfather.jsonexists, as in gzkit per ADR-0.34.0), or, where it is open, with a non-0.0.xsemver;--kind featurewith a0.0.xsemver; - refuses, exit 1, while planning: a source that is not a pool id, is
already renamed in the ledger, or already carries
promoted_to:; an invalid--semveror--slug; a target id already in the ledger or on disk; a pool ADR with an empty or missing## Target Scope, or with no items to derive; - derives the target id
ADR-<semver>-<slug>(slug from--slug, else from the pool id), the checklist from the pool (see Slug Source Contract), and renders the ADR template with statusProposed(--status draftfor Draft),kind:andpromoted_from:. It carries## Intent(or## Problem Statement) and## Decisioninto the new ADR and preserves## Target Scope,## Non-Goals,## Dependencies,## Promotion Criteria,## Inspired Byand## Notes. Lane is--lane, else the pool'slane:, else the projectmode; parent is--parent, else the pool's; --dry-runprints the target, the brief paths and the events it would append, and writes nothing. With--jsonit prints only the result payload;- otherwise writes
<paths.adrs>/pre-release/<id>/<id>.md(foundation/for an open foundation kind) andobpis/<OBPI-ID>.mdper checklist item, and rewrites the pool file tostatus: Supersededwithpromoted_to:and a promoted-on note. It appendsartifact_renamed(reasonpool_promotion, extraskindandsemver), oneobpi_createdper brief, and anobpi_unparkedfor every OBPI a prior demotion parked at this pool id (GHI #584); - then checks what it wrote, unless
--force: brief structure and path validity (GHI #419) and template scaffold, exit 1; then thegz adr evaluatescoring (evaluate_adr, no ledger event), exit 3 on any verdict but GO. On either failure the files, the Superseded pool file and the ledger events stay. Recover by authoring the package and re-checking withuv run gz obpi validate --adr <ID> --authoredanduv run gz adr evaluate <ID>. Do not re-promote: the recorded rename refuses it, with--forceas well.
It appends no adr_created. The promoted ADR inherits the pool id's
adr_created through the rename. A pool ADR that was never booked (gz plan create --kind pool books nothing) leaves the promoted ADR without one, and
gz adr report (_warn_orphaned_adrs) warns that it exists on disk but is not
registered in the ledger.
Slug Source Contract (GHI #241)
_promoted_checklist_from_pool resolves OBPI slugs from the pool ADR in this
order. Author the pool to hit the first path that fits:
-
## Proposed OBPI Decompositiontable (preferred). A markdown table withSlugandDescriptioncolumns (a leading#column is fine; extra columns likeLaneare ignored; a row whose slug is not kebab-case is dropped). TheSlugcolumn drives the OBPI name; theDescriptioncolumn becomes the Feature Checklist text.## Proposed OBPI Decomposition | # | Slug | Description | Lane | |---|------|-------------|------| | 01 | check-pipeline | Implement ordered check pipeline | Lite | | 02 | auto-repair-tier | Deterministic auto-repair executor | Lite | -
- **slug** — narrativebullets in## Target Scope. When every top-level bullet uses the bold-prefix convention (em dash, en dash or hyphen), the bold text becomes the OBPI slug and the narrative becomes the checklist text.## Target Scope - **check-pipeline** — Implement ordered check pipeline with Pydantic models - **auto-repair-tier** — Deterministic auto-repair executor -
Legacy narrative-only bullets (deprecated). Still accepted for backward compatibility but emits a deprecation warning on promote. The full bullet text becomes both slug source and checklist text, which produces long, narrative-leaking OBPI slugs. Migrate to path 1 or 2.
## Target Scope is required on every path, table or not: it must be non-empty
and is preserved verbatim as the promoted ADR's narrative scope. Bullets nested
under ### H3 subsections within it are ignored by paths 2 and 3; only
direct top-level bullets count as scope. A pool ADR can therefore decompose
under a clean table (path 1) while keeping rich prose in a
### Detailed specification subsection below.
Workflow
- Identify the pool ADR (e.g.
ADR-pool.ai-runtime-foundations) and read it through. Check it againstAGENTS.md§ Architectural Boundaries and the active campaign plan, which sets release prioritization. - Choose the target version and kind.
--kind featurein gzkit, with the semver the ascending feature-ADR order allows (the work-order ruling carried ingz-obpi-pipeline). In an adopter project wherefoundationis open, it takes a0.0.xsemver; resolve the boundary with the invariance test, "Foundation = without it, we wouldn't be doing the project" (the hexagonal-ports lens: ports point to invariance; adapters are features), perdocs/user/concepts/foundation-feature-invariance-test.md. - Decompose in the pool ADR, before promoting. Promotion creates one
checklist item and one brief per derived scope item, 1:1, and fits the
scorecard to that count (
_promotion_scorecard). The decomposition decision is therefore the pool's table or bullets. Size it withdocs/governance/GovZero/obpi-decomposition-matrix.md: the Rule of Three baseline (which the doc sets for heavy-lane ADRs), then the Matrix of Four overlay (Single-Narrative, Testability Ceiling, State Anchor, Surface Boundary). A unit that violates a principle is split further. - Preview:
uv run gz adr promote <POOL-ADR> --semver <X.Y.Z> --kind feature --dry-run. Check the target id, the brief slugs and any legacy-bullet warning. - Promote: the same command without
--dry-run. If the post-write checks exit 1 or 3, the promotion stands: author the retained package and run the two re-check commands the output names. - Book the ADR if the pool never was:
uv run gz register-adrs <NEW-ADR-ID>appendsadr_createdwhen the promoted id has none, and reports nothing to register when the rename carried one over. - Verify: the ADR under
pre-release/(orfoundation/), one brief per checklist item under itsobpis/, the pool filestatus: Supersededwithpromoted_to:, and in the ledger theartifact_renamed, theobpi_createdevents and anadr_createdthat resolves to the new id (uv run gz adr status <NEW-ADR-ID>).
Options
--semver(required): the target version,X.Y.Z.--kind(required, no default):feature;poolis always refused;foundationonly where the kind is open.--slug: target slug override (defaults to the slug derived from the pool id).--title: target title (defaults to the pool H1 title).--parent: parent override (defaults to the pool'sparent:).--lane:liteorheavy(defaults to the pool'slane:, then the projectmode).--status:proposed(default) ordraft.--dry-run,--json: preview; structured result payload.--force: skip the post-write structure, scaffold and evaluation checks. It does not bypass the kind/semver binding and works only on the first application.
Common Rationalizations
These thoughts mean STOP — you are about to violate the architectural boundary:
| Thought | Reality |
|---|---|
| "The pool ADR doesn't have actionable Target Scope bullets, but I know what it means" | Promotion is fail-closed without actionable scope. Your interpretation is not a substitute. Refine the pool ADR first. |
| "The Rule of Three feels like overengineering for this small ADR" | The decomposition protocol exists because ADRs that skip it produce briefs that drift during implementation. Small now, sprawling later. |
| "I'll add OBPIs after the promote runs" | Promotion fixes the checklist and briefs 1:1 from the pool's decomposition. Change the pool's table or bullets before promoting, not the promoted package after it. |
"The post-promote check failed — I'll promote again with --force" | The promotion is already applied and recorded; the rename refuses a second run. Author the retained briefs and re-check them. |
"I can skip --dry-run, I know the layout" | --dry-run costs nothing. A wrong-version promotion is undone only by gz adr demote, which deletes the package. |
| "The original pool ADR was written years ago — it doesn't need re-evaluation" | Pool ADRs are intent. If the intent is years old, the foundation it assumed may not exist. Re-read AGENTS.md § Architectural Boundaries before promoting. |
Red Flags
- Promoting a pool ADR that
AGENTS.md§ Architectural Boundaries rules out - A target semver ahead of the lowest feature ADR with unlanded OBPIs
- Resulting Feature Checklist count differs from generated OBPI brief count
- Pool file or ledger edited by hand to "finish" a promotion
- Re-running promotion after its post-write checks failed
- No
adr_createdresolving to the promoted id after step 6 - Decomposition Protocol skipped or applied superficially
Demote (inverse lifecycle)
uv run gz adr demote <ADR-ID> --ghi <N> (adr_demote_cmd,
src/gzkit/commands/adr_demote.py) reverses a promotion. It turns a feature or
foundation ADR into ADR-pool.<slug>, strips kind, semver, date and
promoted_from, deletes the source package directory (briefs and closeout
form), appends artifact_renamed (reason pool_demotion) and parks each child
OBPI (obpi_parked), which a later re-promotion unparks. It exits 3 when
another ADR names this one as parent or when @covers decorators under
tests/ name REQs from the deleted briefs (GHI #773); --force overrides both.
A promote/demote round trip always collides on the retained pool file, which
fails by default. Choose --on-collision take-demoted when the ADR was worked
after promotion, or keep-pool when it never diverged from its intake
(GHI #775).
uv run gz adr demote ADR-0.27.0-arb-receipt-system-absorption --ghi 520 --on-collision take-demoted --dry-run
uv run gz adr demote ADR-0.27.0-arb-receipt-system-absorption --ghi 520 --on-collision take-demoted
Example
uv run gz adr promote ADR-pool.harness-fitness-report --semver 0.60.0 --kind feature --dry-run
uv run gz adr promote ADR-pool.harness-fitness-report --semver 0.60.0 --kind feature
uv run gz register-adrs ADR-0.60.0-harness-fitness-report
uv run gz adr status ADR-0.60.0-harness-fitness-report
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |