From 5eff160c97becf6379181c8a54a4cbaf4053753c Mon Sep 17 00:00:00 2001 From: Ralf Anton Beier Date: Fri, 7 Aug 2026 07:41:16 +0200 Subject: [PATCH] feat(skills): drive the right side of the V + check tool currency before filing gaps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two changes, both from mining the ten unactioned June field reports, and both TESTED against a real rivet project before being written down. feature-loop step 3 — close the V when the test lands: Ten reports converged on one gap: the left side of the V grows fast because authoring it is natural, while the right side is skipped silently every feature (one repo: 257 of 269 sw-reqs unverified; another: 20 artifacts, one verifies link). Five of them independently proposed the same skill under five names. The cheap path already exists in rivet and no skill mentioned it: a source marker instead of a hand-authored YAML artifact per test. Verified end-to-end on a scratch dev-preset project with the INSTALLED binary: // rivet: verifies REQ-001 in a test rivet coverage --tests -> REQ-001 1 test marker ./src/lib.rs:6 (verifies) 1/1 requirements have test coverage (100.0%) rivet verify REQ-001 -> evidence: 1 source verifies marker(s); status changed on disk to `verified` rivet verify REQ-002 -> REFUSES: "no verifying evidence. Add an incoming verifies link ... or a marker, then re-run" That refusal is what makes this a mechanical check rather than a prose step, which was #94's explicit constraint on any new guidance ("don't add prose-only skills — they get skipped under pressure"). report-tool-friction 2b — version currency before a capability gap: A missing capability is the one friction class that expires. Three measured instances of the waste: rivet#748 filed 13 days AFTER the type it asks for shipped (reporter on dev@0.2.0, fixed in 0.3.0 on 2026-07-17); a session pinned to the oldest plugin version, hiding eight skills; this machine running rivet 0.28.0 against a v0.32.0 release. Bugs and crashes still get filed immediately — only missing-feature claims need the thirty-second version check. feature-loop 0.1.0 -> 0.2.0; report-tool-friction 0.1.0 -> 0.2.0; plugin 0.18.0. Refs #84, #88, #89, #90, #91, #92, #93, #94, #95 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../.claude-plugin/plugin.json | 2 +- .../skills/pulseengine-feature-loop/SKILL.md | 28 ++++++++++++++++++- .../skills/report-tool-friction/SKILL.md | 28 ++++++++++++++++++- 3 files changed, 55 insertions(+), 3 deletions(-) diff --git a/claude-tooling/plugins/pulseengine-claude/.claude-plugin/plugin.json b/claude-tooling/plugins/pulseengine-claude/.claude-plugin/plugin.json index 51d834d..6efc9e8 100644 --- a/claude-tooling/plugins/pulseengine-claude/.claude-plugin/plugin.json +++ b/claude-tooling/plugins/pulseengine-claude/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "pulseengine-claude", - "version": "0.17.0", + "version": "0.18.0", "description": "PulseEngine methodology as installable Claude Code tooling \u2014 philosophy + toolchain + repo-taxonomy + model-operating-contract memory, memory-persistence hooks (situational awareness at session start, working-context checkpoints across sessions/compaction), plus sixteen procedural skills (clean-room verification, release execution with a V-model traceability gate, oracle-gating, the full feature loop, the standardized release-artifact pipeline, tool-friction reporting, session-learning capture, STPA/STPA-Sec hazard-analysis audit, backend-agnostic proof synthesis, full bidirectional traceability audit across the V, greenfield verification bootstrap, release planning with an issue-driven delivery loop, an incremental issue-hunt loop, a quiesce-gated post-release repo-hygiene sweep, and a gate-potency audit that proves standing CI checks can still fail).", "author": { "name": "PulseEngine", diff --git a/claude-tooling/plugins/pulseengine-claude/skills/pulseengine-feature-loop/SKILL.md b/claude-tooling/plugins/pulseengine-claude/skills/pulseengine-feature-loop/SKILL.md index 24bce2c..ecf3aed 100644 --- a/claude-tooling/plugins/pulseengine-claude/skills/pulseengine-feature-loop/SKILL.md +++ b/claude-tooling/plugins/pulseengine-claude/skills/pulseengine-feature-loop/SKILL.md @@ -3,7 +3,7 @@ name: pulseengine-feature-loop description: This skill should be used when doing a feature end-to-end on a PulseEngine project (rivet, spar, witness, sigil, meld, loom, synth, wohl, kiln) — including "implement a feature", "add a new requirement", "extend the architecture", "write a new pass", "ship a feature end-to-end", "do this properly with traceability", "model-driven implementation", or any feature work that should pass through the full AADL → WIT → typed traceability → oracle-gated code → MC/DC → attestation → verify loop. ALWAYS use this skill when the user authorizes feature work on a PulseEngine project and the work touches more than a single file. metadata: author: pulseengine.eu - version: "0.1.0" + version: "0.2.0" --- # PulseEngine feature loop @@ -50,6 +50,32 @@ For each new property the feature claims: - Run `rivet validate` and `rivet check` — both must be green. - **Artifact:** new YAML in `requirements/`, `decisions/`, `tests/`. `rivet coverage` should show the trace topology now covering the new property. +**Close the right side of the V when the test lands — don't defer it.** The +left side grows fast because authoring it is natural; the right side gets +skipped silently, every feature, until the debt is measured in the hundreds +(one repo: **257 of 269 sw-reqs with no verification**; another: 20 artifacts +and *one* `verifies` link). The cheap path is a **source marker**, not a +hand-authored YAML artifact per test: + +```rust +// rivet: verifies REQ-001 // also: #[rivet::verifies("REQ-001")] +#[test] // Python: # rivet: verifies REQ-001 +fn add_does_not_overflow() { ... } // @rivet_verifies("REQ-001") +``` + +Then, the moment the oracle is green: + +```sh +rivet coverage --tests # marker → requirement map; the burn-down list +rivet verify REQ-001 # advances implemented → verified, opt-in and auditable +``` + +`rivet verify` **refuses without evidence** — *"no verifying evidence. Add an +incoming `verifies` link … or a `// rivet: verifies REQ-001` marker"* — so this +is a mechanical check, not a prose step. Use `partially-verifies` when the test +discharges only part of the requirement. If the loaded schema has no +verification type at all, that is the finding: see [`traceability-audit`] step 0. + ### 4. Write the code, oracle-gated per change Per [`oracle-gate-a-change`]: diff --git a/claude-tooling/plugins/pulseengine-claude/skills/report-tool-friction/SKILL.md b/claude-tooling/plugins/pulseengine-claude/skills/report-tool-friction/SKILL.md index 0955513..870740d 100644 --- a/claude-tooling/plugins/pulseengine-claude/skills/report-tool-friction/SKILL.md +++ b/claude-tooling/plugins/pulseengine-claude/skills/report-tool-friction/SKILL.md @@ -3,7 +3,7 @@ name: report-tool-friction description: This skill should be used whenever a PulseEngine tool (rivet, spar, witness, sigil, meld, loom, synth, kiln, gale, scry, smithy, thrum, temper, mcp — the roster lives in the pulseengine-toolchain memory) produces friction during real work — it errors, crashes, produces wrong or surprising output, is missing a capability you needed, has confusing/undocumented behavior, or forced you into a workaround. ALWAYS use this skill the moment you notice yourself working *around* a tool instead of *with* it, or saying "this should just work but doesn't." The friction is the signal; capturing it as an issue in the tool's own repo is the action. Fires inside [`pulseengine-feature-loop`] and [`release-execution`] and any standalone tool use. metadata: author: pulseengine.eu - version: "0.1.0" + version: "0.2.0" --- # Report tool friction @@ -30,6 +30,32 @@ File in the **tool's own repo** (`pulseengine/`), not in the consuming pro ### 2. Search for a duplicate first `gh issue list --repo pulseengine/ --search "" --state all`. If an open issue already covers it, add a comment with your fresh repro instead of opening a new one. Label-search for the friction label too. +### 2b. Check you are not reporting a gap that is already fixed + +**A missing *capability* is the one friction class that expires.** Before filing +"tool X cannot do Y", confirm you are on a current version — record both numbers +in the issue: + +```sh + --version +gh release list -R pulseengine/ --limit 1 +``` + +Embedded schemas and rule sets ship *inside* the binary, so a stale install +reports a stale capability. Three measured instances of this exact waste: + +- a "the schema has no verification type" issue filed **13 days after** that type + shipped — the reporter's binary was one release behind, and the fix had + already landed; +- an agent session pinned to the **oldest** installed plugin version, silently + hiding eight skills, so their absence looked like a capability gap; +- a machine running rivet **0.28.0 against a v0.32.0 release** — four minor + versions of shipped fixes invisible to everything running there. + +A bug or a crash is worth filing immediately regardless. A *missing feature* is +worth thirty seconds of version-checking first, because the cost of getting it +wrong is a maintainer re-deriving a fix they already shipped. + ### 3. File it automatically, then mention it Open the issue without pausing the work, then note it in your response to the user (link + one line). Don't batch, don't wait for permission — friction is cheap to capture and expensive to forget. The body, kept short: