Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions .claude/skills/gov/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,12 +199,20 @@ govctl check --has-active

For RFC-governed work, verify the RFC state:

- `draft/spec`: ask permission, then finalize and advance to `impl`
- `normative/spec`: ask permission, then advance to `impl`
- `normative/impl+`: proceed
- `deprecated`: stop
- `draft/spec`: do not bump; ask permission, then finalize and advance to `impl`
- `normative/spec`: continue authoring the current version without another bump; ask permission before advancing to `impl`, which seals its RFC and Clause content
- `normative/impl+`: proceed against the sealed current-version baseline
- `deprecated`: stop; do not edit or version-bump

If implementation reveals a spec bug, do not silently deviate. Amend the RFC per [[ADR-0016]] or stop and ask.
If implementation reveals a spec bug, do not silently deviate:

- A code-only implementation defect does not require an RFC edit or bump.
- Editing RFC or Clause content after entry to `impl` creates an unversioned amendment. Do not advance to `test` while it exists.
- Release that amendment on the normative RFC with an appropriate patch, minor, or major `govctl rfc bump`; the new version starts in `spec`.
- Continue authoring that new version in `spec` without another bump, then advance to `impl` to seal the corrected baseline.
- A current-version changelog correction uses `govctl rfc edit <RFC-ID> changelog.*` and does not affect the sealed content baseline.

Ask before the lifecycle-owned bump unless the user already granted full authority.

Implementation rules:

Expand Down
29 changes: 29 additions & 0 deletions .claude/skills/rfc-writer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,35 @@ Only include representation details when they are themselves the external contra
| Specification | normative | MUST/SHOULD/MAY requirements |
| Rationale | informative | Extended explanation |

## Phase-Aware Authoring

These rules summarize [[RFC-0000:C-STATUS-LIFECYCLE]],
[[RFC-0000:C-PHASE-LIFECYCLE]], and [[RFC-0002:C-LIFECYCLE-VERBS]].

Before editing an RFC, inspect its status and phase:

- A draft RFC is published initially through finalization; do not version-bump it.
- In `spec`, RFC and Clause edits refine the current version candidate and do not require another version bump.
- In `impl`, `test`, or `stable`, edits that change RFC or Clause content create an unversioned amendment. Lifecycle-owned metadata updates performed by dedicated verbs and current-version changelog-only corrections are exempt. The `/spec` or `/gov` workflow must release qualifying amendments with a version bump before further phase progression.
- Entry from `spec` to `impl` seals the final RFC and Clause content as that version's implementation baseline.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
- A deprecated RFC cannot start another version lifecycle.

This helper writes specification content but does not perform lifecycle verbs.
Use `/spec` or `/gov` for bump and advance decisions.

## Clause Version Assignment

Clause version assignment follows [[RFC-0000:C-CLAUSE-DEF]] and
[[RFC-0002:C-LIFECYCLE-VERBS]].

Clause `since` is lifecycle-owned; do not write it into clause text or try to set
it through the generic edit surface:

- A Clause created in a draft RFC remains pending until RFC finalization assigns the current version.
- A Clause created in a normative RFC already in `spec` receives the current RFC version immediately.
- A Clause created in `impl`, `test`, or `stable` remains pending until a content-changing RFC bump assigns the next version.
- A deprecated RFC does not accept new Clauses.

## Rendering Rules

The renderer auto-generates structural elements. **Do NOT include these in clause `text`:**
Expand Down
27 changes: 20 additions & 7 deletions .claude/skills/spec/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Use this workflow for spec-only governance work: refine or accept ADRs, clarify
7. Validate with `govctl check`, and run `govctl render` when rendered docs should change.
8. Use `/commit` for raw VCS operations. This workflow defines what to record, not how to invoke VCS directly.
9. Do not let RFCs absorb implementation structure or let ADRs absorb work-item execution details. Preserve artifact roles while editing.
10. Do not bump an RFC again merely because its current version is already in `spec`; edits there belong to that version candidate.

## Quick Reference

Expand All @@ -47,6 +48,8 @@ govctl adr accept <ADR-ID>

govctl clause edit <RFC-ID>:C-<NAME> text --stdin <<'EOF' ... EOF
govctl rfc bump <RFC-ID> --patch -m "Clarify clause wording"
govctl rfc get <RFC-ID> changelog
govctl rfc edit <RFC-ID> changelog.summary --set "Clarify current version"
govctl rfc finalize <RFC-ID> normative

govctl check
Expand Down Expand Up @@ -81,6 +84,10 @@ govctl rfc show <RFC-ID>
govctl adr show <ADR-ID>
```

Before editing a normative RFC, inspect its current phase. The phase determines
whether the edit remains in the current version candidate or must be released as
a new version.

For artifact editing conventions, follow the appropriate writer skill:

- RFC changes -> **rfc-writer**
Expand All @@ -98,16 +105,21 @@ For ADR work:
For RFC work:

- Edit clauses with `govctl clause edit`
- If the RFC is draft and ready to become normative, ask permission before `govctl rfc finalize <RFC-ID> normative`
- If amending an existing normative RFC, ask permission before `govctl rfc bump`
- If the RFC is draft, do not bump it; when ready, ask permission before `govctl rfc finalize <RFC-ID> normative`
- If a normative RFC is in `spec`, edit the current version candidate directly; do not bump it again for those edits
- If a normative RFC is in `impl`, `test`, or `stable`, an RFC or Clause edit creates an unversioned amendment; after review, ask permission before using `govctl rfc bump` to release it as the next version in `spec`
- If the RFC is deprecated, do not edit or version-bump it
- Use `govctl rfc edit <RFC-ID> changelog.*` for current-version changelog corrections; these do not change version, phase, or the sealed content signature

Semver guidance for RFC amendments:

- `--patch`: clarification or wording fix with no behavioral change
- `--minor`: additive requirement or newly specified behavior
- `--major`: breaking or incompatible requirement change

Every RFC bump must include a changelog summary via `-m`.
Every version-changing RFC bump must include a changelog summary via `-m`.
`--change` without a bump level is changelog-only and cannot release an RFC or
Clause content amendment.

### 4. Review and validate

Expand Down Expand Up @@ -157,10 +169,11 @@ If the task grows into implementation work, stop here and hand off to `/gov`.

### Clarify an RFC without changing behavior

1. Edit the clause text with `govctl clause edit`
2. Run **rfc-reviewer**
3. Ask permission, then run `govctl rfc bump <RFC-ID> --patch -m "Clarify wording"`
4. Run `govctl check` and `govctl render`
1. Inspect the RFC phase with `govctl rfc show <RFC-ID>`
2. Edit the clause text with `govctl clause edit`
3. Run **rfc-reviewer**
4. For a draft RFC, keep the version and finalize when ready; for a normative RFC already in `spec`, keep the current version; for a normative RFC in `impl`, `test`, or `stable`, ask permission, then run `govctl rfc bump <RFC-ID> --patch -m "Clarify wording"`
5. Run `govctl check` and `govctl render`

### Prepare a deprecation plan without implementation

Expand Down
29 changes: 23 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,8 @@ The `gov/` directory is authoritative for governance artifacts. Rendered project
RFCs are constitutional law. Code that conflicts with a normative RFC is a bug.

- No silent deviation: fix the code or propose an RFC amendment
- Normative RFCs MAY be amended: version bump + changelog per [[ADR-0016]]
- Normative RFC content MAY continue changing without another bump while its current version remains in `spec`
- Content changed after entry to `impl` is an unversioned amendment and MUST be released by a version bump before further phase progression
- Cite RFC clauses when implementing invariants

### Law 2: Phase Discipline
Expand Down Expand Up @@ -82,23 +83,37 @@ If behavior is unspecified or ambiguous, escalate. Do not invent.
draft → normative → deprecated
```

- **draft**: Under discussion. Implementation MUST NOT depend on draft RFCs.
- **normative**: Binding. Implementation MUST conform to current version. Spec MAY evolve via version bumps with changelog entries per [[ADR-0016]].
- **deprecated**: Superseded. No new work permitted.
Status and phase rules derive from [[RFC-0000:C-STATUS-LIFECYCLE]],
[[RFC-0000:C-PHASE-LIFECYCLE]], and [[RFC-0002:C-LIFECYCLE-VERBS]].

- **draft**: Under discussion. Implementation MUST NOT depend on draft RFCs. Finalization is the initial publication boundary; version-changing bumps are forbidden.
- **normative**: Binding. Content in `spec` is the current version candidate; entry to `impl` seals that version as the implementation baseline. Later amendments start a new version lifecycle through a version bump per [[ADR-0016]].
- **deprecated**: Superseded. No new work or version-changing bump is permitted.

Reverse transitions are forbidden.

### Phase × Status Compatibility

| Status \ Phase | spec | impl | test | stable |
| -------------- | ---- | ---- | ---- | ------ |
| draft | ✅ | ⚠️ | ⚠️ | ❌ |
| draft | ✅ | ❌ | ❌ | ❌ |
| normative | ✅ | ✅ | ✅ | ✅ |
| deprecated | ✅ | ❌ | ❌ | ✅ |

- ⚠️ = experimental, gates are soft warnings
- ❌ = forbidden

Within one version, phase transitions are forward-only. A content-changing bump
after `impl`, `test`, or `stable` starts the next version in `spec`; it is not a
backward transition of the sealed version.

Clause version assignment follows [[RFC-0000:C-CLAUSE-DEF]] and
[[RFC-0002:C-LIFECYCLE-VERBS]].

Clause `since` is lifecycle-owned. Draft clauses receive it at finalization,
clauses created in a normative RFC already in `spec` receive the current version
immediately, and clauses created while a normative RFC is in `impl`, `test`, or
`stable` remain pending until a content bump assigns the next version.

---

## 4. Decision Tree
Expand Down Expand Up @@ -167,6 +182,8 @@ govctl loop replan LOOP-YYYY-MM-DD-NNN

# Viewing artifacts (styled markdown to stdout)
govctl rfc show RFC-0001 # Show RFC
govctl rfc get RFC-0001 changelog
govctl rfc edit RFC-0001 changelog.summary --set "Clarify current version"
govctl adr show ADR-0001 # Show ADR
govctl work show WI-ID # Show work item
govctl clause show RFC-0001:C-X # Show clause
Expand Down
27 changes: 27 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,27 @@ Release entries are curated summaries for readers. Work item traceability remain

## [Unreleased]

### Added

- RFC edit and get paths expose only the changelog entry matching the current RFC version, with summary and category mutations (WI-2026-07-16-001)

### Changed

- Lifecycle RFC clauses document current-version spec authoring, implementation-entry sealing, and current-changelog correction boundaries (WI-2026-07-16-001)
- Change-only rfc bump --change uses current-version resolution and CLI help documents its no-version-bump behavior (WI-2026-07-16-001)
- Lifecycle RFC clauses define version-changing bump eligibility and preserve changelog-only correction behavior (WI-2026-07-16-002)
- Hand-authored RFC guide documents the draft finalization and normative bump boundary (WI-2026-07-16-002)
- Lifecycle rollback specification defines target path existence and byte-content restoration boundaries (WI-2026-07-16-003)

### Fixed

- RFC and Clause edits made in spec can advance to impl without another version bump (WI-2026-07-16-001)
- RFC changelog editing rejects historical entries and lifecycle-owned version and date fields (WI-2026-07-16-001)
- Clause creation assigns since immediately only for normative spec RFCs, while draft and non-spec amendments remain pending for finalize or bump (WI-2026-07-16-001)
- Entering impl seals the current content signature and rejects unresolved pending Clause versions without rewriting them (WI-2026-07-16-001)
- Version-changing bump rejects draft and deprecated RFCs without mutation (WI-2026-07-16-002)
- Draft Clause `since` remains absent after rejected version bumps and is assigned by normative finalization (WI-2026-07-16-002)

## [0.11.0] - 2026-07-16

0.11.0 makes lifecycle corrections explicit and failure-safe. RFC amendments
Expand Down Expand Up @@ -48,6 +69,12 @@ accidental latest local release cut can be undone without rewriting history.
- ADR placeholder context now uses its own `W0113` warning instead of the
missing-reference warning code.

### Known Limitations

- In 0.11.0, changing RFC or Clause content after a version bump has entered
`spec` requires another bump before advancing to `impl`. Later releases seal
the final current-version content during the `spec` to `impl` transition.

## [0.10.2] - 2026-07-05

0.10.2 restores compatibility between the bundled Agent Skills and GitHub
Expand Down
60 changes: 54 additions & 6 deletions docs/guide/rfcs.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,12 +56,20 @@ govctl rfc list --tag caching,api

## Canonical Edit Surface

All RFC and clause fields are accessible through path-based editing:
Editable RFC and Clause fields use path-based operations. Lifecycle-owned fields
such as RFC versions, changelog dates, and Clause `since` values use dedicated
commands or automatic assignment instead:

```bash
# Lifecycle-managed fields use dedicated verbs
govctl rfc bump RFC-0010 --minor -m "Add new clause for edge case"
govctl rfc finalize RFC-0010 normative
govctl rfc bump RFC-0010 --minor -m "Add new clause for edge case"

# Correct metadata for the current RFC version only
govctl rfc get RFC-0010 changelog
govctl rfc edit RFC-0010 changelog.summary --set "Clarify edge-case behavior"
govctl rfc edit RFC-0010 changelog.fixed --add "Correct timeout wording"
govctl rfc edit RFC-0010 changelog.fixed[0] --remove

# Add to array fields
govctl rfc edit RFC-0010 refs --add RFC-0001
Expand All @@ -77,6 +85,11 @@ New clause text here
EOF
```

Finalization is the initial publication boundary for a draft RFC. A
version-changing bump requires normative status, so draft and deprecated RFCs
are rejected. Changelog-only corrections do not change the version and remain
available through either `rfc edit ... changelog` or `rfc bump --change`.

## Working with Clauses

### Create a Clause
Expand Down Expand Up @@ -107,6 +120,12 @@ text = """
The system MUST validate all inputs."""
```

`since` is assigned when the target version is known. Clauses created in a
draft RFC remain pending until finalization. Clauses created in a normative RFC
already in `spec` receive the current RFC version immediately. Clauses created
in `impl`, `test`, or `stable` remain pending until the content amendment is
released by an RFC version bump.

### Edit Clause Text

```bash
Expand All @@ -133,7 +152,7 @@ govctl clause delete RFC-0010:C-MISTAKE -f

**Safety:** Deletion is only allowed when:

- The RFC status is `draft` (normative RFCs are immutable)
- The RFC status is `draft`
- No other artifacts reference the clause

For normative RFCs, use `govctl clause deprecate RFC-0010:C-OLD` instead.
Expand Down Expand Up @@ -168,14 +187,16 @@ When the spec is complete and approved:
govctl rfc finalize RFC-0010 normative
```

This makes the RFC binding — implementation must conform to it.
This ratifies the RFC lineage. While its current version remains in `spec`, that
content is still an authoring candidate. The version becomes the implementation
baseline when it advances to `impl`.

### Deprecate

When an RFC is superseded or obsolete:

```bash
govctl rfc finalize RFC-0010 deprecated
govctl rfc deprecate RFC-0010
```

## Phase Lifecycle
Expand All @@ -197,11 +218,22 @@ govctl rfc advance RFC-0010 stable # Tested, ready for production
Phase transitions are gated:

- `spec → impl` requires `status = normative`
- `spec → impl` requires every Clause to have a resolved `since` version
- `spec → impl` seals the current RFC and Clause content signature
- Each phase has invariants that must be satisfied

The sealed signature is a content baseline, not a file lock. A code-only defect
found during `impl` can be fixed without changing the RFC. If RFC or Clause
content must change, edit it and then release that amendment with a patch,
minor, or major bump. The bump starts the new version in `spec`; phase
progression rejects the amendment until that happens. Changelog-only corrections
do not affect the sealed baseline.

## Versioning

RFCs use semantic versioning:
RFCs use semantic versioning after normative finalization. Draft RFCs remain on
their initial version while they are authored, and deprecated RFCs cannot start
a new version lifecycle:

```bash
# Bump version with changelog entry
Expand All @@ -210,6 +242,22 @@ govctl rfc bump RFC-0010 --minor -m "Add new clause for edge case"
govctl rfc bump RFC-0010 --major -m "Breaking change to API contract"
```

A content-changing bump starts the new version in `spec`. RFC and Clause content
can continue changing during that `spec` phase without another version bump;
advancing to `impl` seals the final content for the version.

Use change-only bump syntax to append categorized metadata without changing the
RFC version:

```bash
govctl rfc bump RFC-0010 --change "fix: Correct current-version wording"
```

Current-version changelog correction always resolves the entry whose version
matches the RFC version, regardless of array order. Historical entries and all
RFC/changelog version and date fields are not editable through the resource
edit surface.

## Listing and Viewing

```bash
Expand Down
Loading
Loading