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
17 changes: 13 additions & 4 deletions .claude/agents/adr-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,10 @@ It does not edit artifacts, execute lifecycle verbs, create work items, or perfo
When invoked:

1. Read the rendered ADR using `govctl adr show <ADR-ID>` (never read the raw TOML file — use the rendered markdown)
2. Run or inspect `govctl check` diagnostics when evaluating source-sensitive reference syntax
3. Evaluate against the checklist below
4. Report findings organized by severity
2. Run or inspect `govctl check` diagnostics for source-sensitive references and projection ownership
3. If rendered structure is duplicated or `E0307` is reported, inspect the owning field with `govctl adr get <ADR-ID> <context|decision|consequences>`
4. Evaluate against the checklist below
5. Report findings organized by severity

## Review Checklist

Expand Down Expand Up @@ -56,6 +57,14 @@ When invoked:
- [ ] Rejected alternatives have a rejection reason
- [ ] Alternatives are genuinely different approaches (not strawmen)

### Projection Ownership

- [ ] The rendered title, Context, Decision, Consequences, and Alternatives sections each appear once
- [ ] Free-form content does not add `Options Considered`, `Alternatives Considered`, or another renderer-owned heading
- [ ] The structured `alternatives` field is the only options inventory
- [ ] Content does not repeat the generated reference inventory as a heading or standalone list
- [ ] Any `E0307` diagnostic is Critical and is fixed before acceptance; `--force` is not a projection-ownership bypass

### References

- [ ] Links to related RFCs/ADRs that constrained or informed the decision
Expand Down Expand Up @@ -98,4 +107,4 @@ Overall: [PASS / NEEDS WORK / MAJOR ISSUES]

If no findings exist, say so explicitly and still include the overall status.

The most common failure modes are an empty or dishonest Negative section, ADRs that drift into execution tracking, ADRs that try to act like mini-RFCs, ADRs that invent unreferenced product obligations, and ADRs that jump straight to a decision without first documenting the alternatives discussion. If the review finds any of those, flag them as Critical.
The most common failure modes are an empty or dishonest Negative section, duplicated renderer-owned structure, ADRs that drift into execution tracking, ADRs that try to act like mini-RFCs, ADRs that invent unreferenced product obligations, and ADRs that jump straight to a decision without first documenting the alternatives discussion. If the review finds any of those, flag them as Critical.
17 changes: 12 additions & 5 deletions .claude/skills/adr-writer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,6 @@ What specific issue are we addressing?
### Constraints

What existing RFCs, ADRs, or technical limitations restrict our options?

### Options Considered

Brief overview (details go in the alternatives field).
```

**Key principle:** A reader 6 months from now must understand _why_ this decision was needed without asking anyone.
Expand Down Expand Up @@ -214,7 +210,7 @@ Examples:

### Quality Checklist

- **Context is complete.** Problem statement, constraints, and options are all present.
- **Context is complete.** Problem statement, constraints, and decision drivers are present.
- **Alternatives come first.** The discussion is visible in `alternatives` before the final decision prose settles the issue.
- **Decision is decisive.** Starts with "We will..." — not "We might..." or "We could...".
- **Consequences are honest.** Negative section is non-empty with mitigations.
Expand Down Expand Up @@ -251,6 +247,15 @@ decision = "Use `HashMap<String, Vec<ClauseSpec>>` for clause storage"

## Rendering Rules

Each semantic section has one canonical authoring surface:

| Content | Canonical owner |
| --------------------------------------------------- | ------------------------------------- |
| ADR title, metadata, and fixed section headings | Renderer |
| Reference inventory | `refs` |
| Options, statuses, pros/cons, and rejection reasons | `content.alternatives` |
| Explanatory body prose and allowed subsections | `context`, `decision`, `consequences` |

The renderer auto-generates structural elements from TOML metadata. **Do NOT include these in content fields:**

- `## Context`, `## Decision`, `## Consequences` headings — auto-generated for each section
Expand All @@ -260,12 +265,14 @@ The renderer auto-generates structural elements from TOML metadata. **Do NOT inc
- ADR title (`# ADR-NNNN: Title`) — auto-generated from metadata

Content fields should contain only the body prose and `[[...]]` references.
Use structured alternatives as the only options inventory; do not add an `Options Considered` or `Alternatives Considered` subsection to prose. `govctl check` and `govctl adr accept` enforce this boundary for proposed ADRs per [[RFC-0000:C-ADR-PROJECTION-OWNERSHIP]].

## Common Mistakes

| Mistake | Fix |
| ------------------------------------- | -------------------------------------------------------- |
| `## Context` in content field | Don't — the renderer adds section headings automatically |
| `### Options Considered` in context | Use structured `content.alternatives` only |
| Empty Negative section | Every decision has trade-offs — document them |
| Decision written before alternatives | Add and evaluate alternatives first; then write decision |
| No alternatives for a new ADR | Add at least one rejected option |
Expand Down
32 changes: 32 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,38 @@ Release entries are curated summaries for readers. Work item traceability remain

## [Unreleased]

### Added

- Proposed ADR checks and acceptance reject renderer-owned headings with field-and-heading diagnostics, including under `--force` (WI-2026-07-15-003)
- Projection validation ignores fenced-code headings and preserves historical terminal ADR compatibility (WI-2026-07-15-003)
- CLI support implements the governed latest-release correction flow (WI-2026-07-15-005)

### Changed

- Detected content amendment bumps start the new RFC version at `spec`, while signature baselines and changelog-only updates preserve phase (WI-2026-07-15-001)
- Unreleased `done` Work Items can return to `active`, while release-referenced items remain `done` (WI-2026-07-15-002)
- RFC finalize exposes only the normative target while deprecation remains a separate verb (WI-2026-07-15-004)
- Release governance artifacts define the correction boundary for the latest local release cut (WI-2026-07-15-005)
- Reviewed ADRs retain decision rationale without task execution sections (WI-2026-07-15-006)

### Fixed

- RFC bump failure paths preserve the original RFC and clause files (WI-2026-07-15-001)
- RFC lifecycle commands reject forbidden deprecated and implementation phase combinations (WI-2026-07-15-001)
- Schema migration converts legacy RFC signatures into content-only amendment baselines without changing RFC versions, phases, or changelogs (WI-2026-07-15-001)
- Project validation rejects Work Item IDs referenced by multiple releases (WI-2026-07-15-002)
- ADR writer and reviewer guidance assign each rendered section to one authoring surface (WI-2026-07-15-003)
- Existing ADR sources render without duplicated alternatives sections (WI-2026-07-15-003)
- ADR projection conflicts normalize formatted artifact titles by visible CommonMark text (WI-2026-07-15-003)
- Lifecycle command write failures preserve governed artifact bytes (WI-2026-07-15-004)
- Phase-only RFC advancement remains outside amendment detection after legacy signature normalization (WI-2026-07-15-004)
- RFC and Clause invalid-transition diagnostics identify valid targets or terminal states (WI-2026-07-15-004)
- Release creation and schema validation reject invalid dates and missing refs (WI-2026-07-15-004)
- Work Item schema and serialization checks match required scalars and omitted empty-list semantics (WI-2026-07-15-004)
- Release correction failure paths preserve release and Work Item data (WI-2026-07-15-005)
- Legacy release version syntax remains supported alongside latest-release undo (WI-2026-07-15-005)
- ADR placeholder context emits a dedicated diagnostic code (WI-2026-07-15-006)

## [0.10.2] - 2026-07-05

0.10.2 restores compatibility between the bundled Agent Skills and GitHub
Expand Down
Loading
Loading