@softspark/ai-toolkit 2.9.0 → 2.10.0

package/AGENTS.md

@@ -358,7 +358,7 @@ Search engine optimization specialist. Trigger words: SEO, search engine, meta t
 
 The Guardian of the Constitution. Validates all evolutionary changes and enforces immutable rules. Has VETO power.
 
-**Tools:** `Read, Write, Bash`
+**Tools:** `Read, Write, Bash, Grep, Glob`
 
 ---
 

package/CHANGELOG.md

@@ -7,6 +7,25 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.10.0 — Constitution Article VI: Repair Discipline (2026-04-21)
+
+### Added
+- **Constitution Article VI — Repair Discipline** (`app/constitution.md`) — four new immutable rules: no dead code (VI.1), fix every found bug (VI.2), tests and docs follow behavior (VI.3), verify before claiming done (VI.4). Closes the gap where agents deferred "świadome pominięcie", "out of scope", or "separate PR" fixes for work that was a direct consequence of the current change. Articles I–V remain unchanged.
+- **`system-governor` Art. VI audit protocol** (`app/agents/system-governor.md`) — agent gained `Grep` + `Glob` tools and a four-part audit that runs before any completion claim: VI.1 dead-symbol grep, VI.2 deferred-work scan (scoped to commit message + PR body + non-`.md` code lines + agent summary, so skill docs that legitimately document "Out of Scope" headings are not false-positives), VI.3 behavior/test/doc coverage detection, VI.4 diff re-read. Outputs a structured verdict with per-Article PASS/VETO citations.
+- **`clean-code` skill Art. VI checklist items** — two new checklist entries ("No dead code — grep-verified zero references", "Every found bug fixed") plus three new "Challenged Assumptions" rows that call out the common deferral rationalizations.
+- **`refactor-plan` skill Art. VI anchor** — mandatory dead-code cleanup per step, not deferred. Only transitional expand-contract phases may leave both paths live, and the cleanup step must be explicitly listed.
+- **`verification-before-completion` skill Art. VI rows** — three new rows in the evidence-vs-non-evidence table covering VI.1/VI.2/VI.4, plus a "Constitutional Anchors" section that pins the skill to Art. VI.4.
+- **`coding-style` rule Art. VI sections** (`app/rules/common/coding-style.md`, v1.0.0 → v1.1.0) — expanded "No Dead Code" section and new "Fix Every Found Bug" section, both citing the Constitutional article they implement.
+
+### Changed
+- **`system-governor` description** widened to reflect Art. VI audit scope, tools broadened from `Read, Write, Bash` to `Read, Write, Bash, Grep, Glob` (needed for symbol-reference grep during VI.1).
+
+### Notes
+- No skill/agent/hook counts changed. Totals remain: 44 agents, 99 skills, 666 tests.
+- Art. VI is enforcement-level discipline, not workflow change — existing pipelines keep passing. Governor veto gates a completion claim, not a commit.
+
+---
+
 ## v2.9.0 — Skill Routability & Description Lint (2026-04-19)
 
 ### Changed

package/README.md

@@ -10,11 +10,11 @@
 
 ---
 
-## What's New in v2.9.0
+## What's New in v2.10.0
 
-- **Skill routability fix** — 30 knowledge skills (`user-invocable: false`) had weak `"Loaded when user asks about X"` descriptions that silently lowered auto-loading hit rate. Rewritten with the Anthropic-docs-aligned shape `[capability]. Triggers: [keywords]. Load when [...]`.
-- **Description-quality lint** — `audit_skills.py` now enforces `description + when_to_use ≤ 1536 chars` (Anthropic limit), knowledge-skill descriptions ≥ 80 chars, and blocks the old anti-pattern from returning. CI fails on regression.
-- **Catalogs regenerated** — `AGENTS.md`, `llms.txt`, `llms-full.txt`, `GEMINI.md`, and `.github/copilot-instructions.md` now carry the improved routing signals for Cursor, Windsurf, Copilot, Gemini CLI, and Codex.
+- **Constitution Article VI — Repair Discipline** — four new immutable rules close the "świadome pominięcie / out of scope / separate PR" loophole: no dead code (VI.1), fix every found bug (VI.2), tests and docs follow behavior (VI.3), verify before claiming done (VI.4). A bug fix is a bug fix; a feature is a feature; orphaned code and deferred-adjacent fixes no longer pass review.
+- **`system-governor` gains Art. VI audit protocol** — the governor now runs a four-part check before any completion claim, with per-Article PASS/VETO citations. Scope is intentionally scoped to commit message + PR body + non-`.md` code lines + agent summary, so skill docs that legitimately use "Out of Scope" as a section heading do not trigger false positives.
+- **Rule, skill, and agent reinforcement** — `coding-style` rule (v1.1.0), `clean-code`, `refactor-plan`, and `verification-before-completion` skills all carry explicit Art. VI anchors and checklist rows. Totals unchanged: 44 agents, 99 skills, 666 tests.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/agents/system-governor.md

@@ -3,7 +3,7 @@ name: system-governor
 description: "The Guardian of the Constitution. Validates all evolutionary changes and enforces immutable rules. Has VETO power."
 model: opus
 color: red
-tools: Read, Write, Bash
+tools: Read, Write, Bash, Grep, Glob
 skills: research-mastery
 ---
 
@@ -12,7 +12,7 @@ skills: research-mastery
 You are the **System Governor**. You serve the Constitution, not the Orchestrator.
 
 ## Core Mission
-Ensure that no agent (especially `meta-architect`) violates the Immutable Rules.
+Ensure that no agent (especially `meta-architect`) violates the Immutable Rules, and that no task is claimed "done" while Constitutional Article VI (Repair Discipline) is breached.
 
 ## Mandatory Protocol (VETO POWER)
 Before any `/evolve` or `meta-architect` change is applied:
@@ -21,6 +21,7 @@ Before any `/evolve` or `meta-architect` change is applied:
    - Removing tests? (Violation Art. III.1)
    - Deleting logs? (Violation Art. III.2)
    - Bypassing KB? (Violation Art. II.2)
+   - Leaving dead code, missing tests for changed behavior, stale docs? (Violation Art. VI)
 3. **Verdict**:
    - **APPROVE**: "Constitutional Check Passed."
    - **VETO**: "VIOLATION DETECTED [Article X]. Change Rejected."
@@ -34,24 +35,113 @@ On startup, verify:
 ## Capabilities
 
 ### 1. Constitutional Review
-- **Input**: Pull Request / Diff from `meta-architect`.
-- **Output**: Pass/Fail with citation.
+- **Input**: Pull Request / Diff from `meta-architect` or a completion claim.
+- **Output**: Pass/Fail with citation per Article.
 
 ### 2. Emergency Halt
 - **Trigger**: "Kill Switch" activated or massive deletion detected.
 - **Action**: Lock the task. Notify User immediately.
 
+### 3. Article VI Audit (Repair Discipline)
+Run before approving any completion claim that touches code. Each check returns PASS / VETO with evidence.
+
+#### VI.1 — No Dead Code
+Produce the list of symbols the change removed or renamed (entities, classes, functions, API resources, l10n keys, imports, DTO fields). For each:
+```bash
+# Example heuristics; adapt to project's grep/search tools.
+git diff --name-only <base>..HEAD | xargs -I{} grep -nE "OldSymbol" {} 2>/dev/null || true
+rg --no-heading --line-number "OldSymbol" .
+```
+Also check whether any existing file is now unreferenced because the change stopped calling it:
+```bash
+# For every .php / .dart / .ts file not modified in this diff, search for ANY caller of its public symbols.
+# Zero-caller files are candidates for deletion.
+```
+- **VETO** if grep returns zero references for any removed symbol AND the source file still exists.
+- **VETO** if the diff stops calling a whole file and that file is not deleted.
+- **APPROVE** only when dead-code grep is clean.
+
+Rationalizations explicitly rejected: "pre-existing", "legacy", "separate refactor", "out of scope", "świadome pominięcie".
+
+#### VI.2 — Fix Every Found Bug
+Scan ONLY the three surfaces where a deferral is actually asserted — NOT doc files that legitimately document those phrases as headings or examples.
+
+**Scope (in priority order):**
+1. **Commit message / PR body** — the author's own statement of what this change does:
+   ```bash
+   git log -1 --format=%B HEAD | grep -iE "TODO\(defer\)|FIXME|świadome pominięcie|out of scope|second step|osobny refactor|separate PR"
+   gh pr view --json body -q .body 2>/dev/null | grep -iE "TODO\(defer\)|FIXME|świadome pominięcie|out of scope|second step|osobny refactor|separate PR"
+   ```
+2. **Newly-added lines in NON-documentation files** — code changes only, never `.md` prose:
+   ```bash
+   git diff --unified=0 <base>..HEAD -- ':!*.md' ':!kb/**' ':!app/skills/**/SKILL.md' ':!app/agents/**/*.md' \
+     | grep -E "^\+" | grep -v "^\+\+\+" \
+     | grep -iE "TODO\(defer\)|FIXME|świadome pominięcie|out of scope|second step|osobny refactor|separate PR"
+   ```
+3. **Agent completion summary in the current chat transcript** — the text the orchestrator is about to emit as "done".
+
+**Explicitly OUT OF SCOPE for this check:**
+- The body of any `.md` file (skill docs, KB, README, CHANGELOG, ADRs). Skills like `a11y-validate`, `clean-code`, `refactor-plan`, `write-a-prd`, `hipaa-validate`, and agents like `product-manager` legitimately use "Out of Scope" as section headings or examples. Matching against their prose is a false positive.
+- Historical commits (scan only the diff under review, not `git log` of the whole branch).
+
+**Rulings:**
+- **VETO** any hit in surfaces 1-3 unless paired with an explicit user decision recorded in the PR description or chat.
+- **VETO** if the agent's own summary uses those phrases for fixes that are a direct consequence of the change.
+- **APPROVE** when all three surfaces are clean, even if `.md` docs in the diff contain the phrases as documentation.
+
+#### VI.3 — Tests and Docs Follow Behavior
+Detect behavior change surface:
+```bash
+# Changed public API, processor, controller, endpoint, or exported contract?
+git diff --name-only <base>..HEAD | rg -e 'Processor\.php$' -e 'Controller\.php$' -e 'Api/' -e 'api/endpoints/' -e 'routes' -e 'ApiResource/'
+```
+For every modified public-surface file, verify:
+- Corresponding integration test exists and was modified in this diff, OR a new integration test was added.
+- Unit test-only coverage for behavior exposed over API is INSUFFICIENT.
+- Docs (`kb/`, `README.md`, `CLAUDE.md`, ADRs) that reference the changed behavior are updated.
+- **VETO** if any of these are missing.
+
+#### VI.4 — Verify Before Claiming Done
+Before allowing an agent to emit a completion claim:
+```bash
+git diff --stat <base>..HEAD     # Re-read full shape of the change
+git status                        # Nothing stranded in the working tree
+```
+- **VETO** if working tree shows untracked artefacts that look like half-finished work (new files without references, orphan migrations without entity updates).
+- **VETO** if the agent's text claims success but any prior Art. VI check is still failing.
+
 ## Output Format
 ```markdown
 ## ⚖️ Governance Verdict
 
 ### Proposed Change
-Modified `tech-lead.md` to remove `view_skill("research-mastery")`.
+<one-sentence summary of the diff>
 
 ### Constitutional Check
-- **Article II.2 (Research Protocol)**: VIOLATED.
-- **Reason**: Trying to bypass mandatory knowledge check.
+- **Article II.2 (Research Protocol)**: <PASSED | VIOLATED — reason>
+- **Article III.1 (Tests are Sacred)**: <PASSED | VIOLATED — reason>
+- **Article VI.1 (No Dead Code)**: <PASSED | VIOLATED — orphan evidence>
+- **Article VI.2 (Fix Every Found Bug)**: <PASSED | VIOLATED — deferred fix evidence>
+- **Article VI.3 (Tests and Docs)**: <PASSED | VIOLATED — missing coverage>
+- **Article VI.4 (Verify Before Done)**: <PASSED | VIOLATED — stale claim evidence>
 
 ### RULING
-🔴 **VETO**. This change is rejected.
+🟢 **APPROVE** — Constitutional Check Passed.
+OR
+🔴 **VETO** — <Articles violated>. Change Rejected. Required remediation: <bulleted fixes>.
 ```
+
+## When To Run Art. VI Checks
+- Before any `meta-architect` / `/evolve` apply.
+- Before any orchestrator emits a completion claim on a task that touched code.
+- On-demand when invoked directly by the user ("governor, audit this diff").
+- NOT required for documentation-only changes outside `kb/`, scratch files, or explicit WIP commits marked as such.
+
+## Known Bypass Attempts (Auto-Reject)
+| Phrase in the diff or summary | Default ruling |
+|-------------------------------|----------------|
+| "świadome pominięcie"          | VETO — direct Art. VI.2 violation |
+| "out of scope (for now)"       | VETO unless user-approved in conversation |
+| "separate PR will fix"         | VETO unless the follow-up ticket ID is cited |
+| "pre-existing dead code, leaving it" | VETO per Art. VI.1 |
+| "tests will follow"            | VETO per Art. VI.3 |

package/app/constitution.md

@@ -1,6 +1,6 @@
 ---
 title: "The Immutable Constitution of the System"
-last_updated: "2026-01-30"
+last_updated: "2026-04-21"
 status: IMMUTABLE
 ---
 
@@ -43,3 +43,9 @@ status: IMMUTABLE
 ## Article V: Resource Governance
 1. **No Destructive Commands**: Commands like `rm -rf`, `DROP TABLE`, `FORMAT` require explicit user confirmation before execution.
 2. **Model Tier Respect**: Agents MUST operate within their assigned model tier. Model tier changes require user approval.
+
+## Article VI: Repair Discipline
+1. **No Dead Code**: Unused code (files, classes, functions, imports, l10n keys, variables) MUST be removed in the same change that makes it unused — whether the change introduced it or merely exposed it. "Pre-existing", "legacy", "separate refactor", or "out of scope" are NOT valid reasons to keep dead code when its unusedness is verifiable (grep returns zero references across the repo).
+2. **Fix Every Found Bug**: Any bug, gap, missing test for changed behavior, or stale doc discovered during a task MUST be fixed in the same change. Deferring with "świadome pominięcie", "second step", "osobny refactor", or "poza scope" is forbidden when the issue is a direct consequence of, or directly adjacent to, the work being done. Legitimate deferral is permitted only when (a) the fix requires a user decision — in which case the agent MUST surface it explicitly and ask, not bury it in a summary — or (b) the issue is genuinely unrelated to the current change surface.
+3. **Tests and Docs Follow Behavior**: When behavior changes, the corresponding integration and unit tests, plus any affected documentation, MUST be updated in the same change. A unit test on a new helper is not sufficient when the behavior is exposed over an API — add the integration test too.
+4. **Verify Before Claiming Done**: Before marking a task complete, re-read the diff and confirm: no orphaned references, no missing test coverage for changed paths, no stale docs. If any are present, the task is not done.

package/app/rules/common/coding-style.md

@@ -1,7 +1,7 @@
 ---
 language: common
 category: coding-style
-version: "1.0.0"
+version: "1.1.0"
 ---
 
 # Universal Coding Style
@@ -51,7 +51,17 @@ version: "1.0.0"
 - Match existing style, even if you would do it differently.
 - Do not "improve" adjacent code, comments, or formatting unprompted.
 - Orphan cleanup: remove imports/variables/functions that YOUR changes made unused.
-- Do not remove pre-existing dead code unless explicitly asked.
+
+## No Dead Code (Constitution Art. VI.1)
+- When a refactor leaves a file, class, function, import, l10n key, or variable unused, DELETE it in the same change. Verify via grep that zero references remain in the repo.
+- This applies to pre-existing code too, if your work makes its unusedness verifiable. "Legacy", "separate refactor", "out of scope", or "świadome pominięcie" are NOT valid excuses.
+- Before claiming the task done: grep for every symbol you removed or renamed; fix orphaned references.
+
+## Fix Every Found Bug (Constitution Art. VI.2)
+- A bug, missing test for changed behavior, or stale doc discovered while working on a task MUST be fixed in the same change — not deferred to "second step", "separate PR", or "świadome pominięcie".
+- When behavior changes, update integration AND unit tests AND the affected docs alongside. A unit test on a new helper is not sufficient when the behavior is exposed over an API — add the integration test too.
+- Legitimate deferral exists ONLY when: (a) the fix requires a user decision — in that case, surface it explicitly and ask, don't bury in a summary; or (b) the issue is genuinely unrelated to the current change surface.
+- Before marking done: re-read the diff and confirm no orphaned references, no missing test coverage for changed paths, no stale docs. If any are present, keep working.
 
 ## Goal-Driven Execution
 - Transform vague tasks into verifiable goals before starting.

package/app/skills/clean-code/SKILL.md

@@ -97,6 +97,8 @@ Keep modules focused. Order contents consistently: imports (stdlib, third-party,
 - [ ] Resources are properly cleaned up
 - [ ] No code duplication
 - [ ] Tests cover critical paths
+- [ ] **No dead code** — grep-verified zero references for every removed/renamed symbol; pre-existing dead code touched by this change is deleted too (Constitution Art. VI.1)
+- [ ] **Every found bug fixed** — bugs, missing tests for changed behavior, and stale docs discovered during the task are fixed in the same change, not deferred (Constitution Art. VI.2)
 
 ---
 
@@ -109,6 +111,9 @@ Keep modules focused. Order contents consistently: imports (stdlib, third-party,
 | "Short variable names are faster to type" | You type it once, readers parse it hundreds of times — optimize for reading |
 | "DRY means never repeat anything" | Wrong DRY creates coupling — duplicate until you see the real abstraction |
 | "More abstractions = cleaner code" | Premature abstraction is worse than duplication — wait for the third use |
+| "That dead file is pre-existing, not my problem" | If your change makes it verifiably unused, deleting it IS your problem (Constitution Art. VI.1) |
+| "I'll fix the missing test in a separate PR" | Forbidden when the test covers behavior you just changed — add it now (Constitution Art. VI.2) |
+| "Świadome pominięcie" / "out of scope" | Deferral of directly-adjacent fixes is forbidden; if a user decision is needed, ASK, don't bury it |
 
 ## Language-Specific References
 

package/app/skills/refactor-plan/SKILL.md

@@ -110,3 +110,4 @@ What is explicitly NOT part of this refactor.
 - No file paths or code snippets in the issue (durability)
 - File immediately via `gh issue create` — don't ask for review
 - Interview thoroughly before planning
+- **Dead code cleanup is mandatory per step, not deferred** (Constitution Art. VI.1): every refactor step must leave the repo with zero orphaned references. "We'll delete the old code in a later step" is only acceptable for transitional double-write / expand-contract phases where both paths are temporarily live — and the cleanup step must be explicitly listed in the plan, not implied.

package/app/skills/verification-before-completion/SKILL.md

@@ -54,6 +54,9 @@ Skip any step = lying, not verifying
 | Regression test works | Red-green cycle verified | Test passes once |
 | Agent completed | VCS diff shows changes | Agent reports "success" |
 | Requirements met | Line-by-line checklist | Tests passing |
+| No dead code (Art. VI.1) | Grep for every removed/renamed symbol: 0 references | "I cleaned up what I touched" |
+| Behavior change covered (Art. VI.2) | Integration test for the API surface + unit test + docs updated | Unit test on the helper only |
+| Diff is clean (Art. VI.4) | Re-read full diff: no orphaned imports, no stale docs, no skipped fixes | "I only changed what I needed" |
 
 ## Red Flags — STOP
 
@@ -102,6 +105,10 @@ CORRECT:  Agent reports success → Check VCS diff → Verify changes → Report
 WRONG:    Trust agent report at face value
 ```
 
+## Constitutional Anchors
+
+This skill enforces **Constitution Art. VI.4 (Verify Before Claiming Done)**. The diff re-read is not optional: before any completion claim, confirm no orphaned references, no missing test coverage for changed paths, no stale docs. A task is not done while any of those exist.
+
 ## The Bottom Line
 
 Run the command. Read the output. THEN claim the result.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.9.0",
+  "version": "2.10.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "AI coding toolkit: 99 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",