agent-quality-police 0.2.4 → 0.2.6

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-police",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Strict governance framework for coding agents that blocks testing and typing bypasses.",
   "author": {
     "name": "Davy Massoneto",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-police",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Strict governance framework for coding agents that blocks testing and typing bypasses.",
   "author": {
     "name": "Davy Massoneto",

package/AGENTS.md

@@ -15,7 +15,7 @@
 4. Execute with TDD when tests are viable.
 5. Run the matching audit agents before final approval.
 
-## Mandatory Skill Routing
+## Skill Routing
 
 - Use [quality-index](.claude/skills/quality-index/SKILL.md) first when the task spans multiple concerns.
 - Use [typescript-zero-bypass](.claude/skills/typescript-zero-bypass/SKILL.md) for any `.ts` or `.tsx` change.
@@ -25,7 +25,7 @@
 - Use [refactoring-with-safety](.claude/skills/refactoring-with-safety/SKILL.md) for refactors that are not pure bug fixes.
 - Use [governance-installation](.claude/skills/governance-installation/SKILL.md) when installing or updating this framework in another repository.
 
-## Non-Negotiables
+## Quality Rules
 
 - TDD is mandatory when tests are technically viable.
 - A passing test suite without behavior proof is not a green build.
@@ -38,7 +38,7 @@
 - Inline structural types are prohibited.
 - Reviewers must reject suspicious diffs instead of “accepting with caveats.”
 
-## Execution Contract
+## Review Flow
 
 - Fix the root problem, not the symptom.
 - Keep tests direct, short, and behavior-based.
@@ -46,26 +46,10 @@
 - Keep policy text severe and actionable; do not soften language to preserve agent comfort.
 - After any change to canonical framework sources such as `framework/skills/`, `framework/rules/`, `docs/policy/`, or `framework/agents/specs/`, run `python3 scripts/build_framework.py` before claiming the repository is consistent.
 - After the build step, run `python3 scripts/validate_framework.py`. If scripts changed, run `python3 -m unittest tests/test_framework_tools.py` and `node --test tests/node/install.test.mjs`.
-
-## Audit Flow
-
-- `implementer`: execution agent, allowed to write, never allowed to weaken rules.
-- `tdd-warden`: verifies there was a real RED phase and that tests prove behavior.
-- `bypass-auditor`: hunts bypasses, fake narrowing, config weakening, helper noise, and non-probative mocks.
-- `pr-gatekeeper`: final verdict, does not rewrite code.
-
-## Output Expectations
-
-- Implementation output should state what behavior is covered, what tests were run, and what remains blocked.
-- Audit output should list concrete findings with file evidence and required correction.
-- Gate output should end with `APPROVED` or `REJECTED`.
-
-## Repository Layout
-
-- [system-layout](docs/policy/system-layout.md)
+- Use `bypass-auditor` for typing, config, mocks, helpers, or suspicious diffs.
+- Use `tdd-warden` when behavior or tests changed or should have changed.
+- Use `pr-gatekeeper` only for final approve-or-reject review.
 
 ## Tool-Specific Notes
 
-- Claude Code should enter through `CLAUDE.md` and `.claude/rules/`.
-- Codex should enter through this file and use `.agents/skills/` plus `.codex/agents/`.
-- OpenCode should enter through this file and load extra instructions from `opencode.json`.
+- AGENTS-aware tools should load only their local tool-specific skills and agents.

package/CLAUDE.md

@@ -6,6 +6,19 @@
 - Prefer current local code and current official documentation over memory.
 - Load only the smallest relevant skill set for the task.
 
+## Startup Sequence
+
+1. Read [quality-definition](docs/policy/quality-definition.md) when the task needs repository policy context.
+2. Read [workflow](docs/policy/workflow.md) when the repository defines one.
+3. Load only the relevant skill set from `.claude/skills/`.
+
+## Skill Routing
+
+- Use [quality-index](.claude/skills/quality-index/SKILL.md) when the task spans multiple concerns.
+- Use [typescript-zero-bypass](.claude/skills/typescript-zero-bypass/SKILL.md) for `.ts` or `.tsx` changes.
+- Use [vite-vitest-tdd](.claude/skills/vite-vitest-tdd/SKILL.md) for Vite or Vitest TDD.
+- Use [react-public-api-testing](.claude/skills/react-public-api-testing/SKILL.md) for React behavior tests.
+
 ## Quality Rules
 
 - Use behavior-first tests when tests are viable.
@@ -22,8 +35,6 @@
 ## Tool-Specific Notes
 
 - Claude Code should enter through `CLAUDE.md` and `.claude/rules/`.
-- Codex should enter through this file and use `.agents/skills/` plus `.codex/agents/`.
-- OpenCode should enter through this file and load extra instructions from `opencode.json`.
 
 ## Claude Code
 

package/framework/entrypoints/policy.md

@@ -0,0 +1,23 @@
+## Priority
+
+{{priority_body}}
+
+## Startup Sequence
+
+{{startup_sequence_body}}
+
+## Skill Routing
+
+{{skill_routing_body}}
+
+## Quality Rules
+
+{{quality_rules_body}}
+
+## Review Flow
+
+{{review_flow_body}}
+
+## Tool-Specific Notes
+
+{{tool_specific_notes}}

package/lib/install.mjs

@@ -35,15 +35,21 @@ export function supportedTargets() {
 }
 
 async function loadEntrypointPolicy(packageRoot) {
-  return (await readFile(packagePath(packageRoot, "framework", "entrypoints", "global-policy.md"), "utf8")).trimEnd();
+  return (await readFile(packagePath(packageRoot, "framework", "entrypoints", "policy.md"), "utf8")).trimEnd();
 }
 
 function renderTemplate(content, replacements) {
   let rendered = content;
-  for (const [key, value] of Object.entries(replacements)) {
-    rendered = rendered.replaceAll(`{{${key}}}`, value);
+  while (true) {
+    let updated = rendered;
+    for (const [key, value] of Object.entries(replacements)) {
+      updated = updated.replaceAll(`{{${key}}}`, value);
+    }
+    if (updated === rendered) {
+      return updated;
+    }
+    rendered = updated;
   }
-  return rendered;
 }
 
 function entrypointReplacements({
@@ -52,11 +58,12 @@ function entrypointReplacements({
   primarySkillRoot,
   skillRoot,
   systemLayoutPath,
-  claudeEntrypointLabel,
-  claudeRulesRoot,
-  codexSkillsRoot,
-  codexAgentsRoot,
-  opencodeConfigPath
+  priorityBody,
+  startupSequenceBody,
+  skillRoutingBody,
+  qualityRulesBody,
+  reviewFlowBody,
+  toolSpecificNotes
 }) {
   return {
     quality_definition_path: qualityDefinitionPath,
@@ -70,14 +77,60 @@ function entrypointReplacements({
     refactoring_with_safety_skill_path: `${skillRoot}/refactoring-with-safety/SKILL.md`,
     governance_installation_skill_path: `${skillRoot}/governance-installation/SKILL.md`,
     system_layout_path: systemLayoutPath,
-    claude_entrypoint_label: claudeEntrypointLabel,
-    claude_rules_root: claudeRulesRoot,
-    codex_skills_root: codexSkillsRoot,
-    codex_agents_root: codexAgentsRoot,
-    opencode_config_path: opencodeConfigPath
+    priority_body: priorityBody,
+    startup_sequence_body: startupSequenceBody,
+    skill_routing_body: skillRoutingBody,
+    quality_rules_body: qualityRulesBody,
+    review_flow_body: reviewFlowBody,
+    tool_specific_notes: toolSpecificNotes
   };
 }
 
+function globalPolicySections() {
+  return {
+    priorityBody: [
+      "- Direct system, developer, and user instructions override this file.",
+      "- Prefer current local code and current official documentation over memory.",
+      "- Load only the smallest relevant skill set for the task."
+    ].join("\n"),
+    startupSequenceBody: [
+      "1. Read [quality-definition]({{quality_definition_path}}) when the task needs repository policy context.",
+      "2. Read [workflow]({{workflow_path}}) when the repository defines one.",
+      "3. Load only the relevant skill set from `{{primary_skill_root}}`."
+    ].join("\n"),
+    skillRoutingBody: [
+      "- Use [quality-index]({{quality_index_skill_path}}) when the task spans multiple concerns.",
+      "- Use [typescript-zero-bypass]({{typescript_zero_bypass_skill_path}}) for `.ts` or `.tsx` changes.",
+      "- Use [vite-vitest-tdd]({{vite_vitest_tdd_skill_path}}) for Vite or Vitest TDD.",
+      "- Use [react-public-api-testing]({{react_public_api_testing_skill_path}}) for React behavior tests."
+    ].join("\n"),
+    qualityRulesBody: [
+      "- Use behavior-first tests when tests are viable.",
+      "- Avoid type bypasses, comment bypasses, config weakening, and fake greens.",
+      "- Prefer named types and explicit models over inline structural shortcuts."
+    ].join("\n"),
+    reviewFlowBody: [
+      "- Before final approval, run the relevant auditors for the actual risk surface.",
+      "- Use `bypass-auditor` for typing, config, mocks, helpers, or suspicious diffs.",
+      "- Use `tdd-warden` when behavior or tests changed or should have changed.",
+      "- Use `pr-gatekeeper` only for final approve-or-reject review."
+    ].join("\n")
+  };
+}
+
+function toolNotesFor(target, { claudeEntrypointLabel = "CLAUDE.md", claudeRulesRoot = "rules/", codexSkillsRoot = "skills/", codexAgentsRoot = "agents/", opencodeConfigPath = "opencode.json" } = {}) {
+  if (target === "claude") {
+    return `- Claude Code should enter through \`${claudeEntrypointLabel}\` and \`${claudeRulesRoot}\`.`;
+  }
+  if (target === "codex") {
+    return `- Codex should enter through this file and use \`${codexSkillsRoot}\` plus \`${codexAgentsRoot}\`.`;
+  }
+  if (target === "opencode") {
+    return `- OpenCode should enter through this file and load extra instructions from \`${opencodeConfigPath}\`.`;
+  }
+  return "";
+}
+
 function renderAgentsRoot(policy, replacements) {
   return `# AGENTS.md\n\n${renderTemplate(policy, replacements).trimEnd()}\n`;
 }
@@ -139,11 +192,8 @@ function rootReplacements(target) {
       primarySkillRoot: "skills/",
       skillRoot: "skills",
       systemLayoutPath: "docs/policy/system-layout.md",
-      claudeEntrypointLabel: "CLAUDE.md",
-      claudeRulesRoot: "rules/",
-      codexSkillsRoot: "../.agents/skills/",
-      codexAgentsRoot: "../.codex/agents/",
-      opencodeConfigPath: "../.config/opencode/opencode.json"
+      ...globalPolicySections(),
+      toolSpecificNotes: toolNotesFor("claude", { claudeEntrypointLabel: "CLAUDE.md", claudeRulesRoot: "rules/" })
     });
   }
   if (target === "codex") {
@@ -153,11 +203,8 @@ function rootReplacements(target) {
       primarySkillRoot: "../.agents/skills/",
       skillRoot: "../.agents/skills",
       systemLayoutPath: "docs/policy/system-layout.md",
-      claudeEntrypointLabel: "../.claude/CLAUDE.md",
-      claudeRulesRoot: "../.claude/rules/",
-      codexSkillsRoot: "../.agents/skills/",
-      codexAgentsRoot: "agents/",
-      opencodeConfigPath: "../.config/opencode/opencode.json"
+      ...globalPolicySections(),
+      toolSpecificNotes: toolNotesFor("codex", { codexSkillsRoot: "../.agents/skills/", codexAgentsRoot: "agents/" })
     });
   }
   if (target === "opencode") {
@@ -167,11 +214,8 @@ function rootReplacements(target) {
       primarySkillRoot: "skills/",
       skillRoot: "skills",
       systemLayoutPath: "docs/policy/system-layout.md",
-      claudeEntrypointLabel: "../../.claude/CLAUDE.md",
-      claudeRulesRoot: "../../.claude/rules/",
-      codexSkillsRoot: "../../.agents/skills/",
-      codexAgentsRoot: "../../.codex/agents/",
-      opencodeConfigPath: "opencode.json"
+      ...globalPolicySections(),
+      toolSpecificNotes: toolNotesFor("opencode", { opencodeConfigPath: "opencode.json" })
     });
   }
   throw new Error(`Unsupported target: ${target}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-quality-police",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Strict governance framework for coding agents that blocks testing and typing bypasses.",
   "type": "module",
   "license": "MIT",

package/framework/entrypoints/global-policy.md

@@ -1,24 +0,0 @@
-## Priority
-
-- Direct system, developer, and user instructions override this file.
-- Prefer current local code and current official documentation over memory.
-- Load only the smallest relevant skill set for the task.
-
-## Quality Rules
-
-- Use behavior-first tests when tests are viable.
-- Avoid type bypasses, comment bypasses, config weakening, and fake greens.
-- Prefer named types and explicit models over inline structural shortcuts.
-
-## Review Flow
-
-- Before final approval, run the relevant auditors for the actual risk surface.
-- Use `bypass-auditor` for typing, config, mocks, helpers, or suspicious diffs.
-- Use `tdd-warden` when behavior or tests changed or should have changed.
-- Use `pr-gatekeeper` only for final approve-or-reject review.
-
-## Tool-Specific Notes
-
-- Claude Code should enter through `{{claude_entrypoint_label}}` and `{{claude_rules_root}}`.
-- Codex should enter through this file and use `{{codex_skills_root}}` plus `{{codex_agents_root}}`.
-- OpenCode should enter through this file and load extra instructions from `{{opencode_config_path}}`.

package/framework/entrypoints/repo-policy.md

@@ -1,69 +0,0 @@
-## Priority
-
-- Direct system, developer, and user instructions override this file.
-- [`docs/policy/quality-definition.md`]({{quality_definition_path}}) is the canonical definition of quality in this repository.
-- If any skill, rule, example, or agent prompt contradicts the quality definition, the quality definition wins.
-- Generated projections must not become the source of truth.
-
-## Startup Sequence
-
-1. Read [quality-definition]({{quality_definition_path}}).
-2. Read [workflow]({{workflow_path}}).
-3. Load the smallest relevant skill set from `{{primary_skill_root}}`.
-4. Execute with TDD when tests are viable.
-5. Run the matching audit agents before final approval.
-
-## Mandatory Skill Routing
-
-- Use [quality-index]({{quality_index_skill_path}}) first when the task spans multiple concerns.
-- Use [typescript-zero-bypass]({{typescript_zero_bypass_skill_path}}) for any `.ts` or `.tsx` change.
-- Use [vite-vitest-tdd]({{vite_vitest_tdd_skill_path}}) when working with Vite, Vitest, or unit/component TDD.
-- Use [react-public-api-testing]({{react_public_api_testing_skill_path}}) for React component behavior tests.
-- Use [anti-bypass-audit]({{anti_bypass_audit_skill_path}}) when reviewing diffs, suspicious helpers, or weakened configs.
-- Use [refactoring-with-safety]({{refactoring_with_safety_skill_path}}) for refactors that are not pure bug fixes.
-- Use [governance-installation]({{governance_installation_skill_path}}) when installing or updating this framework in another repository.
-
-## Non-Negotiables
-
-- TDD is mandatory when tests are technically viable.
-- A passing test suite without behavior proof is not a green build.
-- `any`, type assertions, non-null assertions, ts-comment bypasses, and lint/config weakening are automatic failures.
-- `Map` in public or domain-facing contracts is suspicious by default and must be treated as a modeling bypass unless a stronger repository rule explicitly allows it.
-- Helpers, factories, mocks, branches, or narrowing added only to silence the type system or to make tests easier are automatic failures.
-- Zod is allowed only at external input boundaries.
-- Joi is allowed only for environment validation when it is genuinely needed.
-- Strong named types are required.
-- Inline structural types are prohibited.
-- Reviewers must reject suspicious diffs instead of “accepting with caveats.”
-
-## Execution Contract
-
-- Fix the root problem, not the symptom.
-- Keep tests direct, short, and behavior-based.
-- Prefer explicit domain names over generic utilities.
-- Keep policy text severe and actionable; do not soften language to preserve agent comfort.
-- After any change to canonical framework sources such as `framework/skills/`, `framework/rules/`, `docs/policy/`, or `framework/agents/specs/`, run `python3 scripts/build_framework.py` before claiming the repository is consistent.
-- After the build step, run `python3 scripts/validate_framework.py`. If scripts changed, run `python3 -m unittest tests/test_framework_tools.py` and `node --test tests/node/install.test.mjs`.
-
-## Audit Flow
-
-- `implementer`: execution agent, allowed to write, never allowed to weaken rules.
-- `tdd-warden`: verifies there was a real RED phase and that tests prove behavior.
-- `bypass-auditor`: hunts bypasses, fake narrowing, config weakening, helper noise, and non-probative mocks.
-- `pr-gatekeeper`: final verdict, does not rewrite code.
-
-## Output Expectations
-
-- Implementation output should state what behavior is covered, what tests were run, and what remains blocked.
-- Audit output should list concrete findings with file evidence and required correction.
-- Gate output should end with `APPROVED` or `REJECTED`.
-
-## Repository Layout
-
-- [system-layout]({{system_layout_path}})
-
-## Tool-Specific Notes
-
-- Claude Code should enter through `{{claude_entrypoint_label}}` and `{{claude_rules_root}}`.
-- Codex should enter through this file and use `{{codex_skills_root}}` plus `{{codex_agents_root}}`.
-- OpenCode should enter through this file and load extra instructions from `{{opencode_config_path}}`.