From 8f011253afa1973a8f4e9c411418f001a08400a7 Mon Sep 17 00:00:00 2001 From: nullhack Date: Sun, 19 Apr 2026 10:20:33 -0400 Subject: [PATCH 1/3] 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. --- .opencode/skills/verify/SKILL.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/.opencode/skills/verify/SKILL.md b/.opencode/skills/verify/SKILL.md index 5e2ee07..805bb87 100644 --- a/.opencode/skills/verify/SKILL.md +++ b/.opencode/skills/verify/SKILL.md @@ -17,7 +17,11 @@ This skill guides the reviewer through Step 4: independent verification that the **You never move `.feature` files.** After producing an APPROVED report: update TODO.md `Next:` to `Run @product-owner — accept feature at Step 5.` then stop. The PO accepts the feature and moves the file. -The reviewer produces one written report (see template below) that includes: all gate results, the SE Self-Declaration Audit, the **Reviewer Stance Declaration**, and the final APPROVED/REJECTED verdict. Do not start until the software-engineer has committed all work and communicated the Self-Declaration verbally in the handoff message. +## When to Use (Step 4) + +After the software-engineer signals Step 3 is complete and all self-verification checks pass. Do not start verification until the software-engineer has committed all work and communicated the Self-Declaration verbally in the handoff message. + +The reviewer produces one written report (see template below) that includes: all gate results, the SE Self-Declaration Audit, the **Reviewer Stance Declaration**, and the final APPROVED/REJECTED verdict. ## Step-by-Step @@ -159,6 +163,18 @@ If the feature involves user interaction: run the app, provide real input, verif Record what input was given and what output was observed. +### 8. Self-Declaration Audit + +Read the software-engineer's Self-Declaration from the handoff message. + +For every **AGREE** claim: +- Find the `file:line` — does it hold? + +For every **DISAGREE** claim: +- REJECT — the software-engineer must fix before requesting review again. + +Undeclared violations → REJECT. + ### 9. Write the Report ```markdown From 3d96aa8afd0a2c93bd213eee239190f8ccc5ea6d Mon Sep 17 00:00:00 2001 From: nullhack Date: Sun, 19 Apr 2026 10:45:22 -0400 Subject: [PATCH 2/3] refactor(reviewer): slim reviewer.md and verify skill to reduce token load MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .opencode/skills/verify/SKILL.md | 18 +----------------- 1 file changed, 1 insertion(+), 17 deletions(-) diff --git a/.opencode/skills/verify/SKILL.md b/.opencode/skills/verify/SKILL.md index 805bb87..5e2ee07 100644 --- a/.opencode/skills/verify/SKILL.md +++ b/.opencode/skills/verify/SKILL.md @@ -17,11 +17,7 @@ This skill guides the reviewer through Step 4: independent verification that the **You never move `.feature` files.** After producing an APPROVED report: update TODO.md `Next:` to `Run @product-owner — accept feature at Step 5.` then stop. The PO accepts the feature and moves the file. -## When to Use (Step 4) - -After the software-engineer signals Step 3 is complete and all self-verification checks pass. Do not start verification until the software-engineer has committed all work and communicated the Self-Declaration verbally in the handoff message. - -The reviewer produces one written report (see template below) that includes: all gate results, the SE Self-Declaration Audit, the **Reviewer Stance Declaration**, and the final APPROVED/REJECTED verdict. +The reviewer produces one written report (see template below) that includes: all gate results, the SE Self-Declaration Audit, the **Reviewer Stance Declaration**, and the final APPROVED/REJECTED verdict. Do not start until the software-engineer has committed all work and communicated the Self-Declaration verbally in the handoff message. ## Step-by-Step @@ -163,18 +159,6 @@ If the feature involves user interaction: run the app, provide real input, verif Record what input was given and what output was observed. -### 8. Self-Declaration Audit - -Read the software-engineer's Self-Declaration from the handoff message. - -For every **AGREE** claim: -- Find the `file:line` — does it hold? - -For every **DISAGREE** claim: -- REJECT — the software-engineer must fix before requesting review again. - -Undeclared violations → REJECT. - ### 9. Write the Report ```markdown From a889b45026e86088cff66355c9bbbe863002fd0c Mon Sep 17 00:00:00 2001 From: nullhack Date: Sun, 19 Apr 2026 14:01:57 -0400 Subject: [PATCH 3/3] feat(release): integrate living-docs into git-release process --- .opencode/skills/git-release/SKILL.md | 21 +++++++++++++++++---- .opencode/skills/living-docs/SKILL.md | 13 ++++++++----- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/.opencode/skills/git-release/SKILL.md b/.opencode/skills/git-release/SKILL.md index 34bd11f..fe85972 100644 --- 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 /__init__.py CHANGELOG.md uv.lock +git add pyproject.toml /__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 - [ ] `/__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 index 29e0b80..ba2264b 100644 --- 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 ``` -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)