@softspark/ai-toolkit 2.9.0 → 2.10.1

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`
 
 ---
 
@@ -453,7 +453,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **app-builder**: Full-stack app scaffolding with stack-selection matrix: Next.js, React+Vite, Nuxt, Astro, FastAPI, Django, Laravel, React Native, Flutter, Unity. Triggers: scaffold, bootstrap, new project, starter template, build app, landing page, dashboard, API, mobile app, CLI, e-commerce, game. Load when user wants to start a new project from scratch.
 - **architecture-audit**: Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling. Codex-adapted: uses native subagents and plan tracking.
 - **architecture-decision**: Architecture decision making via trade-off analysis in RFC/RFD/ADR format: context, constraints, 3+ options, comparison, recommendation. Triggers: architecture decision, ADR, RFC, RFD, trade-offs, options comparison, design choice, pick between, should we use, evaluate approach. Load when weighing 2+ architectural options or writing decision records.
-- **biz-scan**: Scan codebase for business opportunities and KPIs
+- **biz-scan**: Scans codebase for business opportunities by analyzing database schemas, API endpoints, tracking events, and feature flags to surface underutilized capabilities, missing KPIs, and monetization gaps. Use when the user asks about revenue opportunities, business metrics, KPI coverage, analytics gaps, or monetization analysis of a codebase.
 - **brand-voice**: Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice.
 - **briefing**: Generate executive daily briefing across all agents
 - **build**: Build the project with auto-detected toolchain
@@ -478,7 +478,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **documentation-standards**: KB document conventions: YAML frontmatter (7 required fields), 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices), directory-category matching, validate.sh CI rules. Triggers: kb/, KB document, architecture note, SOP, runbook, howto, frontmatter, knowledge base entry, documentation standard. Load when creating or editing any file under kb/.
 - **ecommerce-patterns**: E-commerce domain patterns: cart, checkout flow, payment providers (Stripe/Adyen), order state machine, inventory, promotions, tax, B2B vs B2C. Triggers: cart, checkout, product, SKU, inventory, payment, Stripe, Shopify, Medusa, Magento, order status, promotion, tax calculation, coupon, refund. Load when working on any e-commerce feature.
 - **evaluate**: Evaluate skill quality and RAG retrieval accuracy
-- **evolve**: Evolve agent definitions via meta-architect
+- **evolve**: Analyzes failure patterns and inefficiencies in agent/skill definitions, then drafts and applies targeted improvements to system prompts, tool permissions, and behavioral rules. Use when the user asks to improve agent behavior, refine skill definitions, update system prompts, or optimize agent configurations based on observed failures.
 - **explain**: Explain code, architecture, or concepts with diagrams
 - **explore**: Explore codebase structure, stack, and architecture
 - **fix**: Auto-fix lint errors, type issues, and simple bugs
@@ -509,13 +509,13 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **panic**: Emergency stabilization via system-governor agent
 - **performance-profiling**: Performance measurement and optimization: four golden signals (latency/traffic/errors/saturation), p50/p95/p99, baseline-change-measure loop, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, profile, bottleneck, optimization, load test, benchmark, CPU profiling, memory leak. Load when diagnosing or optimizing slow code or services.
 - **persona**: Switch engineering persona at runtime: backend-lead, frontend-lead, devops-eng, junior-dev
-- **plan**: Plan implementation with tasks and success criteria
+- **plan**: Breaks down feature requests and project goals into phased implementation plans with task lists, agent assignments, dependency graphs, and success criteria. Use when the user asks to plan a feature, create an implementation roadmap, break down a coding task, or outline project phases.
 - **plan-writing**: Implementation plan and pre-mortem drafting: phase breakdown, success criteria, risks, rollback plan, acceptance tests, estimated effort. Triggers: implementation plan, pre-mortem, phased plan, project plan, task breakdown, success criteria, rollback strategy, risk register. Load when user asks to write a plan or pre-mortem document.
 - **plugin-creator**: Creates experimental opt-in plugin packs with manifests, conventions, and optional module scaffolding for Claude and Codex runtimes
 - **pr**: Create pull requests with pre-flight validation
 - **prd-to-issues**: Break a PRD into independently-grabbable GitHub issues using vertical slices with HITL/AFK tagging and dependency ordering. Use when user wants to convert a PRD to issues, create tickets, or break down a PRD into work items.
 - **prd-to-plan**: Convert a PRD into a phased implementation plan using tracer-bullet vertical slices. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions tracer bullets. Codex-adapted: uses native subagents and plan tracking.
-- **predict**: Predict regressions and impact before changes land
+- **predict**: Analyzes code diffs and file changes to identify potential regressions, maps dependency impact across the codebase, and generates a risk-scored impact report. Use when reviewing pull requests, assessing code change risk, checking for breaking changes, or analyzing the blast radius of a diff.
 - **prompt-caching-patterns**: Loaded when user builds with Anthropic API and needs to cut cost or latency via prompt caching. Covers TTL, cache breakpoints, stacking, invalidation, and measuring hit rate.
 - **qa-session**: Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session. Codex-adapted: uses native subagents and plan tracking.
 - **rag-patterns**: RAG architecture: embeddings, chunking strategies, hybrid search (BM25 + vector), reranking, CRAG/self-correcting, multi-hop reasoning, evaluation metrics. Triggers: RAG, embedding, vector search, pgvector, Qdrant, Pinecone, Weaviate, chunking, reranker, retrieval, hybrid search, semantic search, knowledge base, cosine similarity. Load when building or tuning RAG systems.
@@ -536,7 +536,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **swarm**: Execute tasks via Map-Reduce, Consensus, or Relay swarms Codex-adapted: uses native subagents and plan tracking.
 - **swift-patterns**: Swift and iOS development patterns: SwiftUI, Combine, async/await, property wrappers, actors, Swift Package Manager, Core Data, UIKit interop, @MainActor. Triggers: Swift, SwiftUI, Combine, iOS, Xcode, actor, property wrapper, Core Data, SPM, UIKit, @MainActor, @State, @Binding. Load when writing or reviewing Swift code.
 - **tdd**: Test-driven development with red-green-refactor loop and vertical slices. Use when user wants TDD, test-first development, red-green-refactor, or building features with tests driving the implementation. Codex-adapted: uses native subagents and plan tracking.
-- **teams**: Launch pre-configured Agent Teams for common workflows Codex-adapted: uses native subagents and plan tracking.
+- **teams**: Launches pre-configured multi-agent teams for code review, debugging, feature development, security audits, and database migrations. Use when the user asks to start a multi-agent workflow, coordinate agent teams, run a team review, or needs parallel agent collaboration on a complex task. Codex-adapted: uses native subagents and plan tracking.
 - **test**: Run tests with coverage analysis and reporting
 - **testing-patterns**: Testing strategy and craft: pyramid vs trophy, unit/integration/e2e split, fixtures, mocks vs fakes vs stubs, AAA pattern, flaky test diagnosis, coverage goals, property-based testing. Triggers: test, testing strategy, fixture, mock, stub, AAA, unit test, integration test, e2e, Playwright, Cypress, flaky, coverage, TDD, test pyramid. Load when writing, reviewing, or designing test suites.
 - **triage-issue**: Triage a bug by deeply exploring the codebase for root cause, then create a GitHub issue with a TDD-based fix plan. Mostly hands-off — minimal user interaction. Use when user reports a bug, wants to investigate an issue, mentions triage, or wants a fix plan. Codex-adapted: uses native subagents and plan tracking.
@@ -548,12 +548,12 @@ Skills are invocable commands or auto-loaded knowledge sources:
 
 ## Quality Standards
 
-Derived from the immutable safety constitution (5 articles):
+Derived from the immutable safety constitution (6 articles):
 
 **Article I — Safety First**
 - No data loss: never delete files without backup verification or using reversible operations
 - No blind execution: never run LLM-generated code without static analysis or review
-- No infinite loops: all autonomous loops must have a maximum iteration count (max 3)
+- No infinite loops: all autonomous loops must have a maximum iteration count (max 5)
 
 **Article II — Hierarchy of Truth**
 - The Knowledge Base (`kb/`) is the source of truth; if code contradicts KB, check KB freshness
@@ -572,6 +572,12 @@ Derived from the immutable safety constitution (5 articles):
 - Commands like `rm -rf`, `DROP TABLE`, `FORMAT` require explicit user confirmation
 - Operate within assigned model tiers; model tier changes require user approval
 
+**Article VI — Repair Discipline**
+- No dead code: unused code (files, classes, functions, imports, variables) must be removed in the same change that makes it unused; 'pre-existing' or 'out of scope' is not a valid reason
+- Fix every found bug: bugs, gaps, missing tests, or stale docs discovered during a task must be fixed in the same change when directly adjacent to the work; deferral requires explicit user decision
+- Tests and docs follow behavior: behavior changes must carry matching integration and unit tests plus affected documentation in the same change
+- Verify before claiming done: re-read the diff before marking a task complete; no orphaned references, no missing coverage, no stale docs
+
 ## Workflow Guidelines
 
 - **Plan First**: Tasks longer than 1 hour require a plan, success criteria, and pre-mortem

package/CHANGELOG.md

@@ -7,6 +7,43 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.10.1 — Art. VI Enforcement Drift Repair (2026-04-21)
+
+### Fixed
+- **`IMMUTABLE_ARTICLES` extended to include Article 6** (`scripts/config_merger.py`, `scripts/config_validator.py`) — v2.10.0 declared Art. VI immutable in `app/constitution.md` but left the enforcement constant at `{1..5}`, so a downstream `extends:` config with `amendments: [{article: 6, ...}]` would silently override Repair Discipline. Constant now `{1..6}`; error message points at article 7+ as the first allowed project-added article.
+- **`scripts/emission.py::generate_quality_standards()` emits Article VI** — generator hard-coded I–V only, so `AGENTS.md`, `GEMINI.md`, editor rule files, and `llms-full.txt` did not carry Art. VI text after the v2.10.0 release. Added four-clause VI block (no dead code, fix every found bug, tests and docs follow behavior, verify before done). All downstream catalogs regenerated.
+- **"5 articles" / "Articles I-V" literals updated to 6 / I-VI** across `README.md`, `app/ARCHITECTURE.md`, `kb/reference/architecture-overview.md`, `kb/reference/enterprise-config-guide.md`, `scripts/config_cli.py` diff label, and `scripts/schemas/ai-toolkit-config.schema.json` description. Added Article VI row to the Constitution table in `architecture-overview.md`.
+- **Article I.3 "Max 3" aligned to Section 4 "Max 5"** in `app/constitution.md` to resolve a pre-existing internal contradiction. Same iteration cap now quoted in `scripts/emission.py` general/quality guidelines.
+- **SKILL.md improvements from PR #8 by @rohan-tessl** — `biz-scan`, `evolve`, `plan`, `predict`, and `teams` gained richer descriptions with explicit "Use when..." clauses and executable protocol steps; team preset details moved to `teams/reference/presets.md` (progressive disclosure). Repo style applied (no em dashes); `plan/SKILL.md` KB Integration section preserved.
+
+### Added
+- **`scripts/validate.py` article-count drift lint** (`validate_constitution_drift`) — parses `app/constitution.md` for `## Article <roman>:` headings, derives the expected count and max roman numeral, and fails strict validation when `README.md`, `app/ARCHITECTURE.md`, or `kb/reference/*` references a stale `N articles` or `Articles I-<roman>` literal. This is how v2.10.0 drift slipped past CI; it will not next time.
+
+### Notes
+- No skill/agent/hook counts changed. Totals remain: 44 agents, 99 skills, 666 tests.
+- Art. VI text itself (in `app/constitution.md`) unchanged from v2.10.0 — only surfaces and enforcement are reconciled with it.
+
+---
+
+## 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,12 @@
 
 ---
 
-## What's New in v2.9.0
+## What's New in v2.10.1
 
-- **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.
+- **Art. VI enforcement drift repaired** — `IMMUTABLE_ARTICLES` in `config_merger.py` and `config_validator.py` extended to include Article 6, so downstream `extends:` configs can no longer override Repair Discipline. Enterprise config schema, CLI diff label, and doc surfaces updated to match.
+- **Generator emits Article VI** — `scripts/emission.py::generate_quality_standards()` now includes Article VI's four clauses; `AGENTS.md`, `GEMINI.md`, `llms-full.txt`, and editor rule files (`.clinerules`, `.roo`, `.windsurf`, `.augment`, `.agents`, `.github/copilot-instructions.md`) all regenerated.
+- **Constitution self-consistency** — Article I.3 "Max 3" aligned to Section 4's "maximum 5 iterations". `validate.py --strict` now fails on article-count drift between `app/constitution.md` and downstream catalogs; the lint parses `## Article <roman>:` headings and fails on stale count or roman-range literals elsewhere.
+- **SKILL.md improvements from #8** (merged from @rohan-tessl) — `biz-scan`, `evolve`, `plan`, `predict`, and `teams` got richer descriptions, executable protocol steps, and structured report templates; team preset details moved to `teams/reference/presets.md` for progressive disclosure. 5 skills total, totals unchanged: 44 agents, 99 skills, 666 tests.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -121,7 +122,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 21 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
-| `constitution.md` | 5 articles | Machine-enforced safety rules |
+| `constitution.md` | 6 articles | Machine-enforced safety rules |
 | `rules/` | auto-injected | Language-specific and custom rules injected into your configs |
 | `kb/` | reference docs | Architecture, procedures, and best practices |
 
@@ -138,7 +139,7 @@ ai-toolkit/
 │   ├── hooks/           # Hook scripts (21 entries, 12 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides
-│   ├── constitution.md  # 5 immutable safety articles
+│   ├── constitution.md  # 6 immutable safety articles
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts

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.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -266,7 +266,7 @@ Phase 2: IMPLEMENTATION
 ├── hooks.json           # Quality gate hooks (multi-language)
 ├── skills/              # All skills: task, hybrid, knowledge
 ├── output-styles/       # System prompt output style overrides (e.g. golden-rules)
-├── constitution.md      # Immutable safety rules (5 articles)
+├── constitution.md      # Immutable safety rules (6 articles)
 └── settings.local.json  # Local settings + Agent Teams config
 ```
 
@@ -332,7 +332,7 @@ The `inject_section_cli.py` script provides a stable marker-based injection API.
 `scripts/compile_slm.py` compiles the full toolkit (20K+ tokens) into a minimal system prompt for Small Language Models (2K-16K tokens). Pipeline: Parse → Score → Compress → Pack → Emit. Supports 4 compression levels (ultra-light, light, standard, extended), 4 output formats (raw, ollama, json-string, aider), persona-aware scoring, and language-aware rule filtering. Profile `offline-slm` in `manifest.json`. Constitution is always included (non-negotiable).
 
 ### Config Inheritance (`extends`)
-`scripts/config_resolver.py`, `config_merger.py`, `config_validator.py`, `config_cli.py`, `config_scaffold.py`, `config_lock.py`. Enterprise configuration inheritance via `.softspark-toolkit.json` `extends` field. Resolves base configs from npm packages, Git URLs, or local paths. Layered deep merge with constitution immutability (Articles I-V absolute), enforce constraints (`requiredAgents`, `forbidOverride`, `minHookProfile`), override validation (`override: true` + justification), and lock file (`.softspark-toolkit.lock.json`). CLI: `config validate`, `config diff`, `config init`, `config create-base`, `config check`. Integrated into `install --local` and `update --local` flows.
+`scripts/config_resolver.py`, `config_merger.py`, `config_validator.py`, `config_cli.py`, `config_scaffold.py`, `config_lock.py`. Enterprise configuration inheritance via `.softspark-toolkit.json` `extends` field. Resolves base configs from npm packages, Git URLs, or local paths. Layered deep merge with constitution immutability (Articles I-VI absolute), enforce constraints (`requiredAgents`, `forbidOverride`, `minHookProfile`), override validation (`override: true` + justification), and lock file (`.softspark-toolkit.lock.json`). CLI: `config validate`, `config diff`, `config init`, `config create-base`, `config check`. Integrated into `install --local` and `update --local` flows.
 
 ### Project Registry
 `scripts/install_steps/project_registry.py`, `scripts/update_projects.py`, `scripts/projects_cli.py`. Tracks all `--local` installed projects in `~/.softspark/ai-toolkit/projects.json`. `ai-toolkit update` propagates to all registered projects in parallel via `ThreadPoolExecutor`. CLI: `ai-toolkit projects`, `--prune`, `remove <path>`.

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
 ---
 
@@ -11,7 +11,7 @@ status: IMMUTABLE
 ## Article I: Safety First
 1. **No Data Loss**: Never delete a file without verifying a backup exists or using `git rm` (which is reversible).
 2. **No Blind Execution**: Never execute code generated by an LLM without static analysis or review.
-3. **No Infinite Loops**: All autonomous loops (Learning, Evolving) must have a maximum iteration count (Max 3).
+3. **No Infinite Loops**: All autonomous loops (Learning, Evolving) must have a maximum iteration count (Max 5, consistent with Section 4).
 
 ### Section 4: Autonomous Loop Limits
 - Autonomous loops (including `/repeat` skill) default to maximum 5 iterations
@@ -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/biz-scan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: biz-scan
-description: "Scan codebase for business opportunities and KPIs"
+description: "Scans codebase for business opportunities by analyzing database schemas, API endpoints, tracking events, and feature flags to surface underutilized capabilities, missing KPIs, and monetization gaps. Use when the user asks about revenue opportunities, business metrics, KPI coverage, analytics gaps, or monetization analysis of a codebase."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[area]"
@@ -13,18 +13,74 @@ allowed-tools: Read, Grep, Glob
 
 $ARGUMENTS
 
-Triggers the Business Intelligence agent to find opportunities.
+Triggers the Business Intelligence agent to analyze the codebase for business opportunities and KPI gaps.
 
 ## Usage
 
 ```bash
 /biz-scan [scope]
-# Example: /biz-scan schema
-# Example: /biz-scan all
+# /biz-scan schema     : focus on database models and entity relationships
+# /biz-scan api        : focus on API endpoints and data exposure
+# /biz-scan all        : full codebase scan
 ```
 
 ## Protocol
-1. **Model Scan**: Read DB schema / Entities.
-2. **Logic Scan**: Read Controllers / UseCases.
-3. **Synthesis**: Match Data vs Business Goals.
-4. **Report**: Generate Opportunity Report.
+
+### 1. Model Scan: Analyze Data Layer
+
+Scan for business-relevant data structures:
+
+```bash
+# Find database models, schemas, entities
+grep -rl "model\|schema\|entity\|migration" --include="*.py" --include="*.ts" --include="*.rb" .
+# Find ORM definitions
+grep -rl "prisma\|sequelize\|typeorm\|sqlalchemy\|activerecord" .
+```
+
+Catalog: entity names, relationships, fields that map to business concepts (revenue, subscription, usage, billing).
+
+### 2. Logic Scan: Analyze Business Logic
+
+Scan controllers, services, and use cases:
+
+```bash
+# Find API endpoints and handlers
+grep -rn "router\.\|app\.\(get\|post\|put\|delete\)\|@Controller\|@app\.route" --include="*.ts" --include="*.py" --include="*.js" .
+# Find tracking/analytics events
+grep -rn "track\|analytics\|event\|metric\|log_event" --include="*.ts" --include="*.py" --include="*.js" .
+```
+
+Catalog: exposed endpoints, tracked events, feature flags, A/B tests.
+
+### 3. Synthesis: Match Data vs. Business Goals
+
+Cross-reference findings to identify:
+
+| Category | What to Look For |
+|----------|-----------------|
+| **Missing KPIs** | Entities with no associated tracking events |
+| **Underutilized features** | Endpoints with no analytics or feature-flag coverage |
+| **Monetization gaps** | Subscription/billing entities without conversion tracking |
+| **Data exposure** | Rich internal data not surfaced via API |
+
+### 4. Report: Generate Opportunity Report
+
+Output a structured markdown report:
+
+```markdown
+## Business Opportunity Report: [scope]
+
+### KPI Coverage
+| Entity/Feature | Tracked Events | Gap |
+|---------------|---------------|-----|
+| [name] | [events or "none"] | [what's missing] |
+
+### Opportunities (ranked by estimated impact)
+1. **[Opportunity]**: [description, affected entities, suggested action]
+
+### Quick Wins
+- [ ] Add tracking to [feature], estimated lift: [low/med/high]
+
+### Data Exposure Gaps
+- [Entity] has [N fields] not exposed via any API endpoint
+```

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/evolve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: evolve
-description: "Evolve agent definitions via meta-architect"
+description: "Analyzes failure patterns and inefficiencies in agent/skill definitions, then drafts and applies targeted improvements to system prompts, tool permissions, and behavioral rules. Use when the user asks to improve agent behavior, refine skill definitions, update system prompts, or optimize agent configurations based on observed failures."
 effort: medium
 disable-model-invocation: true
 context: fork
@@ -10,18 +10,58 @@ allowed-tools: Read, Edit, Grep, Glob
 
 # Evolve Command
 
-Triggers the Meta-Architect to improve the system.
+$ARGUMENTS
+
+Triggers the Meta-Architect to improve agent and skill definitions based on observed patterns.
 
 ## Usage
 
 ```bash
 /evolve [source]
-# Example: /evolve learnings (Analyze kb/learnings)
-# Example: /evolve last-failure (Analyze last error log)
+# /evolve learnings        : analyze kb/learnings/ for recurring failure patterns
+# /evolve last-failure     : analyze the most recent error log
+# /evolve agents           : audit all agent definitions for gaps
 ```
 
 ## Protocol
-1. **Analyze**: Read input source for patterns of failure/inefficiency.
-2. **Design**: Draft changes to `.claude/agents/` or `.claude/skills/`.
-3. **Implement**: Apply changes.
-4. **Report**: Document what evolved.
+
+### 1. Analyze
+
+Read the input source and extract actionable patterns:
+
+- **learnings**: grep `kb/learnings/` for entries tagged `failure`, `retry`, `timeout`, or `inefficiency`
+- **last-failure**: read the most recent file in `kb/learnings/` and identify root cause
+- **agents**: scan all `.md` files in `app/agents/` for missing tools, vague prompts, or mismatched model tiers
+
+### 2. Design
+
+Draft changes targeting the identified patterns:
+
+| Target | File Location | Change Type |
+|--------|--------------|-------------|
+| Agent definitions | `app/agents/*.md` | Frontmatter (tools, model), system prompt text |
+| Skill definitions | `app/skills/*/SKILL.md` | Description, workflow steps, allowed-tools |
+| Rules | `app/rules/` | New or updated rule files |
+
+Show the proposed diff to the user before applying.
+
+### 3. Implement
+
+Apply approved changes. After each edit:
+
+- Run `python3 scripts/validate.py` to confirm structural integrity
+- Verify YAML frontmatter parses without errors
+- Confirm no forbidden patterns (eval, exec, shell=True)
+
+### 4. Report
+
+Create a summary documenting what evolved:
+
+```markdown
+## Evolution Report
+- **Source**: [learnings | last-failure | agents]
+- **Pattern found**: [description of failure/inefficiency]
+- **Changes applied**:
+  - `app/agents/[name].md`: [what changed and why]
+- **Validation**: passed / failed
+```