Gov

CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- tag list loads artifacts once instead of N times (WI-2026-04-21-002)
+- tag delete performs safety check via batch usage map instead of per-tag scan (WI-2026-04-21-002)
+- RFC detail view shows tags in header (WI-2026-04-21-003)
+- ADR rendered markdown shows tags in metadata (WI-2026-04-21-003)
+- Work item rendered markdown shows tags in metadata (WI-2026-04-21-003)
+- Clause rendered markdown shows tags in metadata (WI-2026-04-21-003)
+- RFC list view has tags column (WI-2026-04-21-003)
+- ADR list view has tags column (WI-2026-04-21-003)
+- Work list view has tags column (WI-2026-04-21-003)
+- Clause list view has tags column (WI-2026-04-21-003)
+- Tags system documented (tag new/delete/list, --tag filter, controlled vocabulary) (WI-2026-04-21-005)
+- Guard subcommands documented (guard new/list/show/set/delete) (WI-2026-04-21-005)
+- verify command has its own section (WI-2026-04-21-005)
+- self-update documented in guide (WI-2026-04-21-005)
+- init-skills documented (--format, --dir) (WI-2026-04-21-005)
+- migrate vs /migrate distinction clarified (WI-2026-04-21-005)
+- describe command documented (WI-2026-04-21-005)
+- release command documented (WI-2026-04-21-005)
+- TUI keyboard shortcuts documented (WI-2026-04-21-005)
+- Canonical edit surface documented (WI-2026-04-21-005)
+
 ## [0.8.4] - 2026-04-15
 
 ### Added

docs/guide/adrs.md

@@ -62,12 +62,66 @@ We need a caching layer that can handle
 EOF
 ```
 
-For alternatives (pros/cons/rejection reason), path-based edits are supported:
+### Canonical Edit Paths
+
+All ADR fields are accessible through a unified path-based edit interface:
+
+```bash
+# Scalar fields
+govctl adr edit ADR-0003 content.decision --set "We will use Redis"
+govctl adr edit ADR-0003 content.context --stdin < context.md
+
+# Array fields — add, remove, tick
+govctl adr edit ADR-0003 refs --add RFC-0010
+govctl adr edit ADR-0003 refs --at 0 --remove
+
+# Nested alternatives
+govctl adr edit ADR-0003 content.alternatives --add "Option C: Use etcd"
+govctl adr edit ADR-0003 "content.alternatives[0].pros" --add "Fast reads"
+govctl adr edit ADR-0003 "content.alternatives[0].cons" --add "Operational cost"
+govctl adr edit ADR-0003 "content.alternatives[0].status" --set accepted
+govctl adr edit ADR-0003 "content.alternatives[0].rejection_reason" --set "Too complex"
+
+# Tick alternative status
+govctl adr edit ADR-0003 content.alternatives --tick accepted --at 0
+```
+
+Path aliases are available for common fields:
+
+| Alias          | Resolves to                                |
+| -------------- | ------------------------------------------ |
+| `decision`     | `content.decision`                         |
+| `context`      | `content.context`                          |
+| `consequences` | `content.consequences`                     |
+| `alt`          | `content.alternatives`                     |
+| `pro`          | `content.alternatives[i].pros`             |
+| `con`          | `content.alternatives[i].cons`             |
+| `reason`       | `content.alternatives[i].rejection_reason` |
+
+### Legacy Set/Add/Remove Verbs
+
+The original verbs remain available and compile into the same edit pipeline:
+
+```bash
+govctl adr set ADR-0003 decision "We will use Redis because..."
+govctl adr add ADR-0003 alternatives "Option C"
+govctl adr remove ADR-0003 refs RFC-0001
+```
+
+### Tagging ADRs
+
+Once tags are registered in the project vocabulary, apply them to ADRs:
 
 ```bash
-# Direct nested edit
-govctl adr set ADR-0001 "alt[2].pros[0]" "Updated pro"
-govctl adr add ADR-0001 "alt[0].cons" "New disadvantage"
+govctl adr edit ADR-0003 tags --add caching
+govctl adr edit ADR-0003 tags --add performance
+```
+
+Filter lists by tag:
+
+```bash
+govctl adr list --tag caching
+govctl adr list --tag caching,performance
 ```
 
 ## Status Lifecycle
@@ -79,6 +133,21 @@ proposed → accepted → superseded
 
 ### Accept a Decision
 
+Before accepting, the ADR must have at least 2 alternatives with 1 accepted and 1 rejected per [[ADR-0042]]:
+
+```bash
+govctl adr edit ADR-0003 "content.alternatives[0].status" --set accepted
+govctl adr edit ADR-0003 "content.alternatives[1].status" --set rejected
+
+govctl adr accept ADR-0003
+```
+
+Use `--force` for historical backfills where alternatives cannot be reconstructed:
+
+```bash
+govctl adr accept ADR-0003 --force
+```
+
 When consensus is reached:
 
 ```bash

docs/guide/getting-started.md

@@ -134,15 +134,108 @@ govctl render
 
 Generates human-readable markdown in `docs/`.
 
+## Interactive TUI
+
+govctl includes an optional interactive terminal dashboard:
+
+```bash
+govctl tui
+```
+
+### TUI Keyboard Shortcuts
+
+| Key        | Action                                   |
+| ---------- | ---------------------------------------- |
+| `1` / `r`  | View RFCs                                |
+| `2` / `a`  | View ADRs                                |
+| `3` / `w`  | View Work Items                          |
+| `j` / `↓`  | Navigate down                            |
+| `k` / `↑`  | Navigate up                              |
+| `Enter`    | Open detail view                         |
+| `Esc`      | Go back                                  |
+| `/`        | Filter list (type query, Enter to apply) |
+| `g`        | Jump to top                              |
+| `G`        | Jump to bottom                           |
+| `Ctrl+d`   | Scroll half page down (detail view)      |
+| `Ctrl+u`   | Scroll half page up (detail view)        |
+| `PageDown` | Scroll page down (detail view)           |
+| `PageUp`   | Scroll page up (detail view)             |
+| `?`        | Toggle help overlay                      |
+| `q`        | Quit                                     |
+
+## Cutting a Release
+
+When a set of work items is complete and ready for release:
+
+```bash
+# Collect all unreleased done work items into a version
+govctl release 0.2.0
+
+# Specify a custom date
+govctl release 0.2.0 --date 2026-04-15
+```
+
+This records the release in `gov/releases.toml` and makes those work items available for changelog generation.
+
 ## Adopting govctl in an Existing Project
 
 `govctl init` is safe to run in existing repositories — it only creates the `gov/` directory structure alongside existing files.
 
 For AI-assisted migration, use the `/migrate` skill to systematically discover undocumented decisions, backfill ADRs, and annotate source code with `[[...]]` references.
 
+### `govctl migrate` vs the `/migrate` Skill
+
+|            | `govctl migrate`                                    | `/migrate` skill                                      |
+| ---------- | --------------------------------------------------- | ----------------------------------------------------- |
+| **What**   | Upgrade existing govctl artifacts to current format | Adopt govctl in an existing project                   |
+| **When**   | After updating govctl version                       | When starting governance in a brownfield repo         |
+| **Effect** | Rewrites TOML/JSON files in `gov/`                  | Discovers decisions, backfills ADRs, annotates source |
+| **Risk**   | Low — transactional, reversible                     | Medium — requires human review of generated ADRs      |
+
+Run `govctl migrate` when govctl tells you a migration is needed (error `E0505`). Use the `/migrate` skill when bringing a legacy project under governance for the first time.
+
+## Canonical Edit Surface
+
+All artifact fields are accessible through a unified path-based edit interface:
+
+```bash
+# Set a scalar value
+govctl rfc edit RFC-0010 version --set 1.2.0
+
+# Add to an array
+govctl adr edit ADR-0003 refs --add RFC-0010
+
+# Remove by index
+govctl work edit WI-2026-01-17-001 acceptance_criteria --at 0 --remove
+
+# Tick checklist items
+govctl adr edit ADR-0003 alternatives --tick accepted --at 0
+govctl work edit WI-2026-01-17-001 acceptance_criteria --tick done --at 0
+```
+
+Nested object fields use dot-delimited paths:
+
+```bash
+govctl adr edit ADR-0003 content.decision --set "We will use Redis"
+govctl adr edit ADR-0003 "content.alternatives[0].pros" --add "Low latency"
+govctl work edit WI-2026-01-17-001 "journal[0].scope" --set backend
+```
+
+## CLI Self-Description
+
+govctl provides a machine-readable command catalog:
+
+```bash
+govctl describe
+govctl describe --context   # Includes project context
+govctl describe --output json
+```
+
+This is designed for agent discoverability — agents can inspect available commands and their semantics without hardcoded knowledge.
+
 ## Next Steps
 
 - [Working with RFCs](./rfcs.md) — Full RFC lifecycle
 - [Working with ADRs](./adrs.md) — Decision records
 - [Working with Work Items](./work-items.md) — Task tracking
-- [Validation & Rendering](./validation.md) — Quality gates and guards
+- [Validation & Rendering](./validation.md) — Quality gates, guards, tags, and more

docs/guide/rfcs.md

@@ -38,6 +38,45 @@ refs = []
 summary = "Brief summary of this RFC."
 ```
 
+## Tagging RFCs
+
+Once tags are registered in the project vocabulary, apply them to RFCs:
+
+```bash
+govctl rfc edit RFC-0010 tags --add caching
+govctl rfc edit RFC-0010 tags --add api
+```
+
+Filter lists by tag:
+
+```bash
+govctl rfc list --tag caching
+govctl rfc list --tag caching,api
+```
+
+## Canonical Edit Surface
+
+All RFC and clause fields are accessible through path-based editing:
+
+```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
+
+# Add to array fields
+govctl rfc edit RFC-0010 refs --add RFC-0001
+govctl rfc edit RFC-0010 owners --add "@co-maintainer"
+
+# Remove by index or pattern
+govctl rfc edit RFC-0010 refs --at 0 --remove
+govctl rfc edit RFC-0010 owners --remove "@old-owner" --exact
+
+# Edit clause text
+govctl clause edit RFC-0010:C-SCOPE text --stdin <<'EOF'
+New clause text here
+EOF
+```
+
 ## Working with Clauses
 
 ### Create a Clause
@@ -104,6 +143,7 @@ For normative RFCs, use `govctl clause deprecate RFC-0010:C-OLD` instead.
 ```bash
 govctl clause list
 govctl clause list RFC-0010
+govctl clause list --tag core    # Filter by tag
 ```
 
 ### View a Clause
@@ -176,5 +216,6 @@ govctl rfc bump RFC-0010 --major -m "Breaking change to API contract"
 govctl rfc list
 govctl rfc list normative    # Filter by status
 govctl rfc list impl         # Filter by phase
+govctl rfc list --tag api    # Filter by tag
 govctl rfc show RFC-0010     # Styled markdown to stdout
 ```