hotfix(v6.1.20260419): verify/reviewer fixes + living-docs release integration (#77)

nullhack · web-flow · commit 633e70142900 · 2026-04-19T14:04:03.000-04:00
* fix(verify): correct stale Self-Declaration location references SE Self-Declaration is communicated verbally in the handoff message, not written to TODO.md. Three references in verify/SKILL.md still pointed to TODO.md from the v4.1 era when it was a written block. * refactor(reviewer): slim reviewer.md and verify skill to reduce token load - reviewer.md: remove default hypothesis, After APPROVED block, and Available Skills list — all duplicated from verify/SKILL.md which is always loaded in the same session (ai-agents.md #24, #26) - verify/SKILL.md v4.0: - drop Standards Summary table (pure restatement of inline content) - drop 'When to Use' section (no information beyond skill name) - OC size/nesting rules (5d rules 1 and 7) cross-reference 6b thresholds instead of repeating values - replace 5d OC table with design-patterns skill reference (on-demand loading per ai-agents.md #23); commitment-device structure preserved inside that skill - move Self-Declaration Audit to Step 5 (before code review) — if SE flagged a DISAGREE, reviewer saves all of code review before rejecting - DISAGREE handling: triage gate instead of hard reject — accepts genuine out-of-SE-control constraints with a note and suggested alternative; rejects weak/unjustified deviations with specific fix - renumber code review sub-sections 5a-5g → 6a-6g * feat(release): integrate living-docs into git-release process
diff --git a/.opencode/skills/git-release/SKILL.md b/.opencode/skills/git-release/SKILL.md
@@ -82,17 +82,29 @@ Add at the top:
 - description (#PR-number)
 ```
 
-### 5. Regenerate lockfile and commit version bump
+### 5. Update living docs
+
+Run the `living-docs` skill to reflect the newly accepted feature in C4 diagrams and the glossary. This step runs inline — do not commit separately.
+
+Load and execute the full `living-docs` skill now:
+- Update `docs/c4/context.md` (C4 Level 1)
+- Update `docs/c4/container.md` (C4 Level 2, if multi-container)
+- Update `docs/glossary.md` (living glossary)
+
+The `living-docs` commit step is **skipped** here — all changed files are staged together with the version bump in step 6.
+
+### 6. Regenerate lockfile and commit version bump
 
 After updating `pyproject.toml`, regenerate the lockfile — CI runs `uv sync --locked` and will fail if it is stale:
 
 ```bash
 uv lock
-git add pyproject.toml <package>/__init__.py CHANGELOG.md uv.lock
+git add pyproject.toml <package>/__init__.py CHANGELOG.md uv.lock \
+  docs/c4/context.md docs/c4/container.md docs/glossary.md
 git commit -m "chore(release): bump version to v{version} - {Adjective Animal}"
 ```
 
-### 6. Create GitHub release
+### 7. Create GitHub release
 
 Assign the SHA first so it expands correctly inside the notes string:
 
@@ -123,7 +135,7 @@ gh release create "v{version}" \
 **SHA**: \`${SHA}\`"
 ```
 
-### 7. If a hotfix commit follows the release tag
+### 8. If a hotfix commit follows the release tag
 
 If CI fails after the release (e.g. a stale lockfile) and a hotfix commit is pushed, reassign the tag and GitHub release to that commit:
 
@@ -151,6 +163,7 @@ The release notes and title do not need to change — only the target commit mov
 - [ ] `uv lock` run after version bump — lockfile must be up to date
 - [ ] `<package>/__version__` matches `pyproject.toml` version
 - [ ] CHANGELOG.md updated
+- [ ] `living-docs` skill run — C4 diagrams and glossary reflect the new feature
 - [ ] Release name not used before
 - [ ] Release notes follow the template format
 - [ ] If a hotfix was pushed after the tag: tag reassigned to hotfix commit
diff --git a/.opencode/skills/living-docs/SKILL.md b/.opencode/skills/living-docs/SKILL.md
@@ -15,8 +15,8 @@ The glossary is a secondary artifact derived from the code, the domain model, an
 
 ## When to Use
 
-- **PO at Step 5** — after the feature is accepted and moved to `completed/`, run this skill to reflect the new feature in C4 diagrams and glossary.
-- **Stakeholder on demand** — when the stakeholder asks "what does the system look like?" or "what does term X mean in this context?".
+- **As part of the release process (Step 5)** — the `git-release` skill calls this skill inline at step 5, before the version-bump commit. Do not commit separately; the release process stages all files together.
+- **Stakeholder on demand** — when the stakeholder asks "what does the system look like?" or "what does term X mean in this context?". In this case, commit with the standalone message in Step 5 below.
 
 ## Ownership Rules
 
@@ -183,13 +183,15 @@ If `docs/glossary.md` already exists:
 
 ## Step 5 — Commit
 
-After both C4 diagrams and glossary are updated:
+**When called from the release process**: skip this step — the `git-release` skill stages and commits all files together.
+
+**When run standalone** (stakeholder on demand): commit after all diagrams and glossary are updated:
 
 ```
 docs(living-docs): update C4 and glossary after <feature-name>
 ```
 
-If this is a stakeholder-requested update without a specific feature trigger:
+If triggered without a specific feature (general refresh):
 
 ```
 docs(living-docs): refresh C4 diagrams and glossary
@@ -207,4 +209,5 @@ docs(living-docs): refresh C4 diagrams and glossary
 - [ ] No existing glossary entry removed
 - [ ] Every new term has a traceable source in completed feature files or `docs/architecture.md`; no term is invented
 - [ ] No edits made to `docs/architecture.md` or `docs/discovery.md`
-- [ ] Committed with `docs(living-docs): ...` message
+- [ ] If standalone: committed with `docs(living-docs): ...` message
+- [ ] If called from release: files staged but not committed (release process commits)
