code-audit-validator 1.2.0__py3-none-any.whl

code_audit_validator-1.2.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: code-audit-validator
+Version: 1.2.0
+Summary: Deterministic conformance checker for AUDIT.md agent-audit outputs — CyberSkill code-audit-framework
+Author-email: CyberSkill <info@cyberskill.world>
+License: 
+                                         Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright 2026 CYBERSKILL SOFTWARE SOLUTIONS CONSULTANCY AND DEVELOPMENT JOINT STOCK COMPANY
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Project-URL: Homepage, https://github.com/cyberskill-official/code-audit-framework
+Project-URL: Changelog, https://github.com/cyberskill-official/code-audit-framework/blob/main/CHANGELOG.md
+Keywords: ai-agents,code-audit,llm,evals,prompt-engineering
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# evals/ — regression gate for AUDIT.md
+
+Every change to `AUDIT.md` must keep this suite green. The harness validates
+**agent outputs** (a run's `docs/BACKLOG.md` + `docs/HANDOFF.md`) against the
+machine-checkable subset of the protocol's rules, and proves each rule is
+**load-bearing** by fault injection: a `B*` fixture plants a known fault set
+(usually exactly one; `B16` deliberately plants three to verify exact-set
+reporting), and the validator must catch exactly that set — no more, no less.
+A trap that stops tripping means a rule has silently died. `G*` fixtures are
+the precision half: compliant-but-tricky outputs (negated prose, redaction
+markers, adversarial formatting, minimal-valid) that must NOT trip anything —
+the suite proves rules fire *and* don't over-fire.
+
+Two checks make the rest load-bearing: `TEMPLATE-NONCONFORMANT` (output that
+doesn't follow the Phase 2 template can no longer silently escape the other
+tripwires — BS-12) and the CONFIG preflight (`CONFIG-PLACEHOLDER` /
+`CONFIG-BAD-ENUM`, which also auto-loads `PROTECTED_AREAS` from the target's
+AUDIT.md so R3 needs no `--protected` double entry — BS-13).
+
+## Files
+
+| File | Role |
+|---|---|
+| `code_audit_validator.py` | The validator implementation. Zero dependencies (stdlib only); published to PyPI as `code-audit-validator`. |
+| `validate.py` | Repo-side CLI shim over the module above — every documented `python3 evals/validate.py …` invocation goes through it. |
+| `fixtures/` | `G*` = compliant outputs that must pass. `B*` = fault-injection traps that must fail with declared codes. |
+| `rules.json` | Rule registry: rule → AUDIT.md anchor → violation codes → fixtures proving it. Coverage gaps are declared honestly. |
+| `baseline.json` | Last recorded matrix (fixture → outcome) pinned to an AUDIT.md version + sha256. |
+| `run-evals.sh` | Runner; `--record` refreshes `baseline.json`. |
+
+## Commands
+
+```bash
+python3 evals/validate.py --all                  # full suite, human output
+python3 evals/validate.py --all --json           # machine-readable
+./evals/run-evals.sh --record                    # run + pin baseline to current AUDIT.md
+python3 evals/validate.py --run <dir>            # validate a real run's docs/ output
+python3 evals/validate.py --run <dir> --report json   # structured findings export (loops, tasks, metrics, violations)
+python3 evals/validate.py --run <dir> --report sarif  # GitHub code-scanning format
+python3 evals/scripts/retro-summary.py           # retro scores per protocol version (did each release help?)
+```
+
+Point `--run` at the target repo root (or its `docs/`): if the target's
+`AUDIT.md` is found, its CONFIG is preflighted and `PROTECTED_AREAS` is loaded
+automatically; `--protected` extends it.
+
+## Adding a fixture
+
+1. Create `evals/fixtures/<Gnn|Bnn>-<slug>/` with `fixture.yaml` + `docs/BACKLOG.md` (and `docs/HANDOFF.md` if relevant).
+2. `fixture.yaml` is flat `key: value` (no YAML library needed):
+
+   ```yaml
+   id: B11-my-trap
+   description: one line
+   expect: fail                  # or pass
+   expected_violations: [R1-NO-OUTPUT]
+   exercises_rules: [R1]
+   protected_areas: []
+   ```
+
+3. For `expect: fail`, the validator must report **exactly** `expected_violations` — plant one fault per fixture unless the fixture's purpose is exact-set verification (B16). Keep `docs/BACKLOG.md` template-conformant (Mode line + tables or the R7 line) so the planted fault is the only signal; ship a near-miss `G*` sibling when adding a new rule, so precision is pinned alongside recall.
+4. Register the fixture in `rules.json` under the rule(s) it exercises — `validate.py --all` fails on registry drift in either direction (BS-10).
+5. Run `./evals/run-evals.sh --record`.
+
+## What the validator cannot see (declared gaps)
+
+The authoritative register is [`improve/BLINDSPOTS.md`](../improve/BLINDSPOTS.md)
+— one row per blind spot, with status and evidence. Headlines:
+
+- Whether code changes were genuinely valuable (retro item 9 — human judgment).
+- Whether findings were padded (retro item 3 — judgment; the validator only guarantees padding is never *required*).
+- Live-agent properties: actual command execution, 3-strike counting, resume behavior (R4). For hard guarantees on those, use deterministic hooks/CI in the target repo, not prompt text.
+- Run completeness: `--run` accepts a docs/ directory without HANDOFF.md (legitimate mid-flight). When reviewing a run that claims to be finished, confirm HANDOFF.md exists yourself (BS-09).

code_audit_validator-1.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+code_audit_validator.py,sha256=wHjVqctyszLqItjOWsTHXKmyOcukGWdRCw5ves2l-F8,30632
+code_audit_validator-1.2.0.dist-info/licenses/LICENSE,sha256=jJWC4b-3FDgRCe4Gfdb_n-LKUnciQNXYULpwys0F1R4,11408
+code_audit_validator-1.2.0.dist-info/licenses/NOTICE,sha256=rVFViBLv6GtWf1Yuva-PqX2fvBqiSSC1RbClpiW9Xw4,187
+code_audit_validator-1.2.0.dist-info/METADATA,sha256=BzBqsVFjHzrISdJNR9UgsDo_dz_PmaEeV-tJa9TluHo,18367
+code_audit_validator-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+code_audit_validator-1.2.0.dist-info/entry_points.txt,sha256=I-SCERpk7v5kYRjNyednulZ0G9JWZGvylSOK3UnsxLo,66
+code_audit_validator-1.2.0.dist-info/top_level.txt,sha256=O3Z8CSTQ2fXolXghQQeFgrc6AmS3PYRi15K7XYBr3IQ,21
+code_audit_validator-1.2.0.dist-info/RECORD,,

code_audit_validator-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

code_audit_validator-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+code-audit-validate = code_audit_validator:main

code_audit_validator-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 CYBERSKILL SOFTWARE SOLUTIONS CONSULTANCY AND DEVELOPMENT JOINT STOCK COMPANY
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

code_audit_validator-1.2.0.dist-info/licenses/NOTICE

@@ -0,0 +1,3 @@
+code-audit-framework
+Copyright 2026 CYBERSKILL SOFTWARE SOLUTIONS CONSULTANCY AND DEVELOPMENT JOINT STOCK COMPANY (CyberSkill)
+https://github.com/cyberskill-official/code-audit-framework

code_audit_validator-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+code_audit_validator

code_audit_validator.py

@@ -0,0 +1,648 @@
+#!/usr/bin/env python3
+"""code_audit_validator — deterministic conformance checker for AUDIT.md outputs.
+
+(Repo-side CLI: `python3 evals/validate.py`, a thin shim over this module —
+kept so the PyPI install claims `code_audit_validator`, not the generic
+top-level name `validate`.)
+
+Checks a run's docs/ directory (BACKLOG.md + HANDOFF.md) against the
+machine-checkable subset of AUDIT.md's core rules:
+
+  R1-NO-OUTPUT       measured baseline/metric without a verbatim fenced output block
+  R1-UNLINKED-OUTPUT measured row whose verify command appears in no fenced block
+  R1-NO-REASON       UNMEASURED / NOT-APPLICABLE without a (reason)
+  R1-GUI-TOOL        GUI tool (profiler/inspector/devtools) used as a Verify command
+  R2-UNCITED         target is neither cited-with-URL nor labeled INTERNAL / N-A
+  R2-NONNUMERIC      banned non-numeric target word (Minimal / High / Strict / ...)
+  R3-PROTECTED       DONE task references a path under protected_areas
+  R5-BAD-STATUS      task status outside { OPEN, IN-PROGRESS, DONE, BLOCKED }
+  R5-BAD-SEV         severity outside { Critical, High, Medium, Low }
+  R5-BAD-ID          task ID not matching L<loop>-T<n>
+  R6-NO-ROOTCAUSE    BLOCKED task without a "Root cause:" note
+  R8-SECRET          unredacted credential pattern in any output file
+  P5-NO-STOP-REASON  HANDOFF.md does not cite which stop condition fired
+  HANDOFF-BAD-MSTATUS  metrics Status outside the closed metric-status set
+  GATED-UNAPPROVED-EXEC  executed task not on the loop's `Approved:` line (gated mode)
+  TEMPLATE-NONCONFORMANT BACKLOG.md does not follow the Phase 2 template, so the
+                     rule tripwires above cannot see it (BLINDSPOTS BS-12)
+  CONFIG-PLACEHOLDER a CONFIG value in the target's AUDIT.md still contains
+                     unedited <placeholder> text (Phase 0 preflight)
+  CONFIG-BAD-ENUM    MODE / DEPTH / BENCHMARK_MODE / SEVERITY_FLOOR outside its
+                     allowed set (Phase 0 preflight)
+
+A loop with zero findings is VALID (R7): absence of tasks is never a violation.
+
+When the run directory (or its parent, if you point --run at docs/ itself)
+contains the target's AUDIT.md, the CONFIG block is preflighted and
+PROTECTED_AREAS is loaded from it automatically — `--protected` then extends
+rather than replaces it (closes the double-entry gap, review item G-F).
+
+Usage:
+  python3 evals/validate.py --run <dir-containing-docs>  [--protected p1,p2]
+  python3 evals/validate.py --run <dir> --report json    # structured findings export
+  python3 evals/validate.py --run <dir> --report sarif   # GitHub code-scanning format
+  python3 evals/validate.py --all          # run every fixture, compare to expectations
+  python3 evals/validate.py --all --json   # machine-readable results
+
+Exit codes: 0 = all good; 1 = violations / fixture mismatch; 2 = usage error.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+FIXTURES = HERE / "fixtures"
+
+TASK_STATUSES = {"OPEN", "IN-PROGRESS", "DONE", "BLOCKED"}
+SEVERITIES = {"Critical", "High", "Medium", "Low"}
+METRIC_STATUSES = {"MEASURED", "UNMEASURED", "NOT-APPLICABLE"}
+ID_RE = re.compile(r"^L\d+-T\d+$")
+
+GUI_TOOLS = [
+    "react profiler", "react devtools", "chrome devtools", "devtools",
+    "browser inspector", "web inspector", "xcode instruments", "instruments.app",
+    "lighthouse panel", "performance tab", "network tab", "profiler tab",
+]
+
+SECRET_PATTERNS = [
+    ("aws-key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("github-token", re.compile(r"\bghp_[A-Za-z0-9]{36}\b")),
+    ("gitlab-token", re.compile(r"\bglpat-[A-Za-z0-9_-]{20}\b")),
+    ("stripe-key", re.compile(r"\bsk_live_[A-Za-z0-9]{16,}\b")),
+    ("anthropic-key", re.compile(r"\bsk-ant-[A-Za-z0-9_-]{16,}\b")),
+    ("openai-key", re.compile(r"\bsk-proj-[A-Za-z0-9_-]{20,}\b")),
+    ("google-api-key", re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b")),
+    ("npm-token", re.compile(r"\bnpm_[A-Za-z0-9]{36}\b")),
+    ("slack-token", re.compile(r"\bxox[bpoas]-[0-9A-Za-z-]{10,}\b")),
+    ("private-key", re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----")),
+    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b")),
+]
+
+BANNED_TARGET_WORDS = {
+    "minimal", "high", "strict", "low", "medium", "fast", "slow", "good",
+    "great", "optimal", "best-in-class", "world-class", "enterprise-grade",
+}
+
+UNMEASURED_RE = re.compile(r"\b(UNMEASURED|NOT-APPLICABLE)\b")
+REASONED_RE = re.compile(r"\b(?:UNMEASURED|NOT-APPLICABLE)\s*\([^)]+\)")
+URL_RE = re.compile(r"https?://\S+")
+STOP_RE = re.compile(r"Stop condition:\s*\(?[abc]\)?", re.IGNORECASE)
+
+
+CELL_SPLIT_RE = re.compile(r"(?<!\\)\|")  # an escaped \| is cell CONTENT, not a separator
+
+
+def norm(cell: str) -> str:
+    """Strip markdown wrapping without mangling shell syntax: backticks go
+    everywhere, but * and _ are stripped only at the edges (emphasis), so
+    commands like `wc -l src/*.py` survive intact. Escaped pipes (\\|) are
+    unescaped back to literal | so commands like `grep -cE "TODO\\|FIXME"`
+    round-trip to what the agent actually ran (fixture G05)."""
+    s = cell.strip().replace("`", "").replace("\\|", "|")
+    return re.sub(r"^[*_]+|[*_]+$", "", s).strip()
+
+
+def split_cells(line: str):
+    return [norm(c) for c in CELL_SPLIT_RE.split(line.strip().strip("|"))]
+
+
+def parse_tables(text: str):
+    """Yield (header_cells, rows, end_line_idx) for every markdown table."""
+    lines = text.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i].strip()
+        if line.startswith("|") and i + 1 < len(lines) and re.match(r"^\|[\s:|-]+\|?$", lines[i + 1].strip()):
+            header = split_cells(line)
+            rows, j = [], i + 2
+            while j < len(lines) and lines[j].strip().startswith("|"):
+                cells = split_cells(lines[j])
+                if any(cells):
+                    rows.append(cells)
+                j += 1
+            yield header, rows, j
+            i = j
+        else:
+            i += 1
+
+
+def section_fences(text: str, after_line: int):
+    """Contents of fenced code blocks between after_line and the next heading."""
+    lines = text.splitlines()
+    fences, current, inside = [], [], False
+    for line in lines[after_line:]:
+        if not inside and re.match(r"^#{1,3}\s", line):
+            break
+        if line.strip().startswith("```"):
+            if inside:
+                fences.append("\n".join(current))
+                current = []
+            inside = not inside
+            continue
+        if inside:
+            current.append(line)
+    return fences
+
+
+def col(header, *names):
+    """Index of first header cell containing any of names (case-insensitive)."""
+    low = [h.lower() for h in header]
+    for n in names:
+        for i, h in enumerate(low):
+            if n in h:
+                return i
+    return None
+
+
+def check_benchmark_like_table(header, rows, end_idx, text, violations, src, is_handoff):
+    mi = col(header, "metric")
+    bi = col(header, "baseline")
+    ti = col(header, "target")
+    vi = col(header, "verify")
+    si = col(header, "status")
+    if mi is None or bi is None:
+        return
+    has_measured_row = False
+    measured_rows = []  # (metric, verify) pairs claiming a measurement
+    for r in rows:
+        def cell(ix):
+            return r[ix] if ix is not None and ix < len(r) else ""
+        baseline, target, verify = cell(bi), cell(ti), cell(vi)
+        # R1 — escape hatch must carry a reason
+        for v in (baseline, cell(si) if is_handoff else ""):
+            if UNMEASURED_RE.search(v) and not REASONED_RE.search(v):
+                # In HANDOFF the reason may live in the Baseline/Final cells; only
+                # flag the cell that itself claims UNMEASURED without any reason nearby.
+                if not REASONED_RE.search(" ".join(r)):
+                    violations.append((f"R1-NO-REASON", src, f"'{v}' lacks (reason): row {r[:2]}"))
+        # Which rows claim a measurement?
+        if is_handoff:
+            status = cell(si)
+            if status and status not in METRIC_STATUSES:
+                violations.append(("HANDOFF-BAD-MSTATUS", src, f"Status '{status}' not in {sorted(METRIC_STATUSES)}"))
+            if status == "MEASURED":
+                has_measured_row = True
+                measured_rows.append((cell(mi), verify))
+        else:
+            if baseline and not UNMEASURED_RE.search(baseline):
+                has_measured_row = True
+                measured_rows.append((cell(mi), verify))
+        # R2 — honest targets
+        if ti is not None and target:
+            t = target.strip()
+            t_low = t.lower().rstrip(".")
+            if t_low in BANNED_TARGET_WORDS:
+                violations.append(("R2-NONNUMERIC", src, f"banned non-numeric target '{t}'"))
+            elif not (
+                URL_RE.search(t)
+                or "internal target" in t_low
+                or "no external benchmark applicable" in t_low
+                or t_low in {"n-a", "n/a", "—", "-"}
+            ):
+                violations.append(("R2-UNCITED", src, f"target '{t}' has no URL and no INTERNAL label"))
+        # R1 — GUI tools are not verification
+        if verify:
+            v_low = verify.lower()
+            for tool in GUI_TOOLS:
+                if tool in v_low:
+                    violations.append(("R1-GUI-TOOL", src, f"'{verify}' is a GUI tool, not a shell command"))
+                    break
+    # R1 — measured rows need verbatim output nearby…
+    fences = section_fences(text, end_idx)
+    if has_measured_row and not fences:
+        violations.append(("R1-NO-OUTPUT", src, "table has MEASURED/measured rows but no fenced raw-output block before next heading"))
+    # …and each measured row must be traceable to ITS verify command
+    elif fences:
+        joined = "\n".join(fences)
+        for metric, verify in measured_rows:
+            if verify and verify not in {"—", "-", ""} and verify not in joined:
+                violations.append(("R1-UNLINKED-OUTPUT", src, f"measured metric '{metric}': verify command '{verify}' appears in no fenced output block"))
+
+
+def check_task_table(header, rows, violations, src, protected):
+    ii = col(header, "id")
+    sev_i = col(header, "sev")
+    st_i = col(header, "status")
+    d_i = col(header, "description")
+    if ii is None or st_i is None:
+        return
+    for r in rows:
+        def cell(ix):
+            return r[ix] if ix is not None and ix < len(r) else ""
+        tid, sev, status, desc = cell(ii), cell(sev_i), cell(st_i), cell(d_i)
+        if tid and not ID_RE.match(tid):
+            violations.append(("R5-BAD-ID", src, f"task id '{tid}' != L<loop>-T<n>"))
+        if status and status not in TASK_STATUSES:
+            violations.append(("R5-BAD-STATUS", src, f"status '{status}' not in {sorted(TASK_STATUSES)}"))
+        if sev and sev not in SEVERITIES:
+            violations.append(("R5-BAD-SEV", src, f"severity '{sev}' not in {sorted(SEVERITIES)}"))
+        if status == "BLOCKED" and "root cause" not in " ".join(r).lower():
+            violations.append(("R6-NO-ROOTCAUSE", src, f"BLOCKED task '{tid}' has no 'Root cause:' note"))
+        if status == "DONE" and protected:
+            joined = " ".join(r)
+            for p in protected:
+                if p and p in joined:
+                    violations.append(("R3-PROTECTED", src, f"DONE task '{tid}' touches protected path '{p}'"))
+
+
+APPROVED_RE = re.compile(r"^Approved:\s*(.+)$", re.MULTILINE)
+MODE_GATED_RE = re.compile(r"(?mi)^\s*-?\s*Mode:\s*gated\b")
+EXECUTED_STATUSES = {"DONE", "IN-PROGRESS", "BLOCKED"}
+
+
+def check_approvals(text, violations, src):
+    """Gated-mode invariant: every executed task (DONE / IN-PROGRESS /
+    BLOCKED) in a loop section must be listed on that section's `Approved:`
+    line. The check fires when the line exists OR the section echoes
+    `Mode: gated` (v1.1.0) — a gated loop with executed tasks and no
+    `Approved:` line is a violation, not an exemption. Sections declaring
+    neither are treated as autonomous and not checked."""
+    sections = re.split(r"(?m)^## (?=Loop\b)", text)
+    for sec in sections:
+        m = APPROVED_RE.search(sec)
+        gated = MODE_GATED_RE.search(sec) is not None
+        if not m and not gated:
+            continue
+        if m:
+            raw = m.group(1).strip()
+            approved = set() if raw.lower() == "none" else {norm(x) for x in raw.split(",") if x.strip()}
+        else:
+            approved = set()
+        for header, rows, _ in parse_tables(sec):
+            ii, st_i = col(header, "id"), col(header, "status")
+            if ii is None or st_i is None or col(header, "metric") is not None:
+                continue
+            for r in rows:
+                tid = r[ii] if ii < len(r) else ""
+                status = r[st_i] if st_i < len(r) else ""
+                if status in EXECUTED_STATUSES and tid and tid not in approved:
+                    why = ("not on this loop's Approved: line" if m
+                           else "this gated loop has no Approved: line at all")
+                    violations.append(("GATED-UNAPPROVED-EXEC", src,
+                                       f"task '{tid}' is {status} but {why}"))
+
+
+def check_secrets(text, violations, src):
+    for kind, pat in SECRET_PATTERNS:
+        for m in pat.finditer(text):
+            ctx = text[max(0, m.start() - 40):m.start()]
+            if "[REDACTED:" in ctx + m.group(0):
+                continue
+            violations.append(("R8-SECRET", src, f"unredacted {kind} matching '{m.group(0)[:12]}…'"))
+
+
+MODE_LINE_RE = re.compile(r"(?mi)^\s*-?\s*Mode:\s*\S+")
+NO_FINDINGS_RE = re.compile(r"No significant findings", re.IGNORECASE)
+
+
+def check_template_conformance(text, violations, src):
+    """BLINDSPOTS BS-12 — the meta-tripwire. Every other check activates only
+    when output LOOKS like the Phase 2 template (pipe tables, headings, Mode
+    echo); a run that emits prose instead silently escapes all of them. This
+    converts that silent escape into a violation, making the rest of the rule
+    set load-bearing. Per loop section the template requires a `Mode:` line in
+    Scope & method, and EITHER (benchmark table AND task table) OR the R7
+    "No significant findings" line (a tabled-baselines-but-no-tasks loop also
+    carries that line, so benchmark-table-only sections remain conformant)."""
+    sections = re.split(r"(?m)^##\s+(?=Loop\b)", text)[1:]
+    if not sections:
+        violations.append(("TEMPLATE-NONCONFORMANT", src,
+                           "no '## Loop <N>' section found — output does not follow the Phase 2 template"))
+        return
+    for sec in sections:
+        loop_id = (sec.splitlines() or ["?"])[0].strip()
+        if not MODE_LINE_RE.search(sec):
+            violations.append(("TEMPLATE-NONCONFORMANT", src,
+                               f"'{loop_id}': Scope & method has no 'Mode:' line (required since v1.1.0)"))
+        tables = list(parse_tables(sec))
+        has_bench = any(col(h, "metric") is not None and col(h, "baseline") is not None for h, _, _ in tables)
+        has_task = any(col(h, "id") is not None and col(h, "status") is not None
+                       and col(h, "metric") is None for h, _, _ in tables)
+        if not (has_bench and has_task) and not NO_FINDINGS_RE.search(sec):
+            violations.append(("TEMPLATE-NONCONFORMANT", src,
+                               f"'{loop_id}': missing benchmark and/or task table and no 'No significant findings' line"))
+
+
+CONFIG_ENUMS = {
+    "MODE": {"gated", "autonomous"},
+    "DEPTH": {"quick", "standard", "deep"},
+    "BENCHMARK_MODE": {"auto", "provided", "none"},
+    "SEVERITY_FLOOR": {"Critical", "High", "Medium", "Low"},
+}
+PLACEHOLDER_RE = re.compile(r"<[^<>\n]*>")
+CONFIG_KEY_RE = re.compile(r"^([A-Z][A-Z_]+):\s*(.*)$")
+
+
+def parse_audit_config(audit_md: Path):
+    """Flat KEY: value parse of the CONFIG block in a target repo's AUDIT.md.
+    Trailing `# comment` text is stripped; placeholder text is preserved."""
+    cfg, in_config = {}, False
+    for line in audit_md.read_text(encoding="utf-8").splitlines():
+        if re.match(r"^##\s*CONFIG\b", line):
+            in_config = True
+            continue
+        if in_config and re.match(r"^##\s", line):
+            break
+        if not in_config:
+            continue
+        m = CONFIG_KEY_RE.match(line.strip())
+        if not m:
+            continue
+        key, raw = m.groups()
+        cfg[key] = re.split(r"\s+#", raw, 1)[0].strip()
+    return cfg
+
+
+def check_config_preflight(target_root: Path, violations, protected):
+    """Phase 0 CONFIG preflight (review gap G-D) + PROTECTED_AREAS auto-load
+    (gap G-F). Runs only when the target's AUDIT.md is present; placeholder
+    values never silently configure anything."""
+    audit = target_root / "AUDIT.md"
+    if not audit.exists():
+        return
+    cfg = parse_audit_config(audit)
+    for key, val in cfg.items():
+        if PLACEHOLDER_RE.search(val):
+            violations.append(("CONFIG-PLACEHOLDER", "AUDIT.md",
+                               f"{key} still contains unedited template text: '{val[:60]}'"))
+        elif key in CONFIG_ENUMS and val and val not in CONFIG_ENUMS[key]:
+            violations.append(("CONFIG-BAD-ENUM", "AUDIT.md",
+                               f"{key} '{val}' not in {sorted(CONFIG_ENUMS[key])}"))
+    areas = cfg.get("PROTECTED_AREAS", "")
+    if areas and not PLACEHOLDER_RE.search(areas):
+        for p in areas.split(","):
+            p = p.strip()
+            if p and p not in protected:
+                protected.append(p)
+
+
+def validate_run(run_dir: Path, protected=None):
+    """Validate one run directory (containing docs/BACKLOG.md, docs/HANDOFF.md)."""
+    protected = list(protected or [])
+    violations = []
+    docs = run_dir / "docs" if (run_dir / "docs").is_dir() else run_dir
+    # The target repo's root is docs/'s parent — whether --run was pointed at
+    # the repo root or at docs/ itself. CONFIG preflight may extend `protected`.
+    check_config_preflight(docs.parent, violations, protected)
+    backlog = docs / "BACKLOG.md"
+    handoff = docs / "HANDOFF.md"
+    if not backlog.exists():
+        violations.append(("MISSING-FILE", "docs/BACKLOG.md", "file not found"))
+    if backlog.exists():
+        text = backlog.read_text(encoding="utf-8")
+        check_template_conformance(text, violations, "BACKLOG.md")
+        check_secrets(text, violations, "BACKLOG.md")
+        check_approvals(text, violations, "BACKLOG.md")
+        for header, rows, end in parse_tables(text):
+            if col(header, "metric") is not None and col(header, "final") is None:
+                check_benchmark_like_table(header, rows, end, text, violations, "BACKLOG.md", is_handoff=False)
+            elif col(header, "status") is not None and col(header, "id") is not None:
+                check_task_table(header, rows, violations, "BACKLOG.md", protected)
+    if handoff.exists():
+        text = handoff.read_text(encoding="utf-8")
+        check_secrets(text, violations, "HANDOFF.md")
+        if not STOP_RE.search(text):
+            violations.append(("P5-NO-STOP-REASON", "HANDOFF.md", "no 'Stop condition: (a|b|c)' line"))
+        for header, rows, end in parse_tables(text):
+            if col(header, "metric") is not None:
+                check_benchmark_like_table(header, rows, end, text, violations, "HANDOFF.md", is_handoff=(col(header, "final") is not None))
+            elif col(header, "status") is not None and col(header, "id") is not None:
+                check_task_table(header, rows, violations, "HANDOFF.md", protected)
+    return violations
+
+
+LOOP_HEAD_RE = re.compile(r"^Loop\s+(\d+)\s*(?:—|-)?\s*(.*)$")
+
+
+def build_report(run_dir: Path, protected, violations):
+    """Findings export (review gap G-G): one structured object per run, for
+    roll-ups across projects, trend dashboards, and client-facing summaries.
+    Parses the same artifacts the validator checks — no second source of truth."""
+    import datetime
+    docs = run_dir / "docs" if (run_dir / "docs").is_dir() else run_dir
+    audit = docs.parent / "AUDIT.md"
+    protocol_version = None
+    protected = list(protected)
+    if audit.exists():
+        m = re.search(r"v\d+\.\d+\.\d+", audit.read_text(encoding="utf-8").splitlines()[0])
+        protocol_version = m.group(0) if m else None
+        check_config_preflight(docs.parent, [], protected)  # mirror the auto-load; violations already counted
+    report = {
+        "schema": "code-audit-framework/report@1",
+        "generated_at": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds"),
+        "run_dir": str(run_dir),
+        "protocol_version": protocol_version,
+        "protected_areas": protected,
+        "loops": [],
+        "metrics": [],
+        "summary": {},
+    }
+    backlog = docs / "BACKLOG.md"
+    if backlog.exists():
+        text = backlog.read_text(encoding="utf-8")
+        for sec in re.split(r"(?m)^##\s+(?=Loop\b)", text)[1:]:
+            first = (sec.splitlines() or [""])[0]
+            hm = LOOP_HEAD_RE.match(first.strip())
+            mode_m = re.search(r"(?mi)^\s*-?\s*Mode:\s*(\S+)", sec)
+            appr_m = APPROVED_RE.search(sec)
+            loop = {
+                "loop": int(hm.group(1)) if hm else None,
+                "date": (hm.group(2).strip() or None) if hm else None,
+                "mode": mode_m.group(1) if mode_m else None,
+                "approved": ([] if appr_m.group(1).strip().lower() == "none"
+                             else [norm(x) for x in appr_m.group(1).split(",") if x.strip()]) if appr_m else None,
+                "no_significant_findings": bool(NO_FINDINGS_RE.search(sec)),
+                "tasks": [],
+            }
+            for header, rows, _ in parse_tables(sec):
+                ii, st_i = col(header, "id"), col(header, "status")
+                if ii is None or st_i is None or col(header, "metric") is not None:
+                    continue
+                sev_i, vec_i, d_i, v_i = (col(header, "sev"), col(header, "vector"),
+                                          col(header, "description"), col(header, "verify"))
+                for r in rows:
+                    def cell(ix):
+                        return r[ix] if ix is not None and ix < len(r) else ""
+                    if cell(ii):
+                        loop["tasks"].append({
+                            "id": cell(ii), "severity": cell(sev_i), "status": cell(st_i),
+                            "vector": cell(vec_i), "description": cell(d_i), "verify": cell(v_i),
+                        })
+            report["loops"].append(loop)
+    handoff = docs / "HANDOFF.md"
+    if handoff.exists():
+        text = handoff.read_text(encoding="utf-8")
+        for header, rows, _ in parse_tables(text):
+            mi, fi = col(header, "metric"), col(header, "final")
+            if mi is None or fi is None:
+                continue
+            bi, di, ti, vi, si = (col(header, "baseline"), col(header, "delta"),
+                                  col(header, "target"), col(header, "verify"), col(header, "status"))
+            for r in rows:
+                def cell(ix):
+                    return r[ix] if ix is not None and ix < len(r) else ""
+                if cell(mi):
+                    report["metrics"].append({
+                        "metric": cell(mi), "baseline": cell(bi), "final": cell(fi),
+                        "delta": cell(di), "target": cell(ti), "verify": cell(vi), "status": cell(si),
+                    })
+    tasks = [t for l in report["loops"] for t in l["tasks"]]
+    by = lambda key: {k: sum(1 for t in tasks if t[key] == k)  # noqa: E731
+                      for k in sorted({t[key] for t in tasks if t[key]})}
+    vio_codes = {}
+    for c, _, _ in violations:
+        vio_codes[c] = vio_codes.get(c, 0) + 1
+    report["summary"] = {
+        "loops": len(report["loops"]),
+        "tasks": len(tasks),
+        "tasks_by_status": by("status"),
+        "tasks_by_severity": by("severity"),
+        "metrics_measured": sum(1 for m in report["metrics"] if m["status"] == "MEASURED"),
+        "violations": len(violations),
+        "violations_by_code": dict(sorted(vio_codes.items())),
+        "clean": not violations,
+    }
+    report["violations"] = [{"code": c, "file": s, "detail": d} for c, s, d in violations]
+    return report
+
+
+def to_sarif(report):
+    """Minimal SARIF 2.1.0 for GitHub code scanning (review F5, optional output)."""
+    rules, results = {}, []
+    for v in report["violations"]:
+        rules.setdefault(v["code"], {"id": v["code"], "name": v["code"],
+                                     "shortDescription": {"text": v["code"]}})
+        results.append({
+            "ruleId": v["code"],
+            "level": "error",
+            "message": {"text": v["detail"]},
+            "locations": [{"physicalLocation": {"artifactLocation": {"uri": f"docs/{v['file']}"
+                          if not v["file"].endswith("AUDIT.md") else v["file"]}}}],
+        })
+    return {
+        "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {"driver": {
+                "name": "code-audit-framework",
+                "informationUri": "https://github.com/cyberskill-official/code-audit-framework",
+                "version": (report.get("protocol_version") or "unknown").lstrip("v"),
+                "rules": list(rules.values()),
+            }},
+            "results": results,
+        }],
+    }
+
+
+def load_fixture_meta(fdir: Path):
+    """fixture.yaml is intentionally flat key: value (no YAML dependency)."""
+    meta = {"id": fdir.name, "expect": "pass", "expected_violations": [], "protected_areas": [], "exercises_rules": []}
+    f = fdir / "fixture.yaml"
+    if f.exists():
+        for line in f.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if ":" not in line or line.startswith("#"):
+                continue
+            k, _, v = line.partition(":")
+            k, v = k.strip(), v.strip()
+            if k in ("expected_violations", "protected_areas", "exercises_rules"):
+                meta[k] = [x.strip() for x in v.strip("[]").split(",") if x.strip()]
+            elif k in ("id", "expect", "description"):
+                meta[k] = v
+    return meta
+
+
+def check_registry(fixture_dirs):
+    """Registry drift guard (improve/BLINDSPOTS.md BS-10): rules.json must
+    agree with fixtures/ on disk, in both directions. A rule referencing a
+    missing fixture means its coverage silently died; an unregistered fixture
+    means coverage the registry does not own."""
+    problems = []
+    reg = HERE / "rules.json"
+    if not reg.exists():
+        return ["rules.json missing — registry is mandatory"]
+    try:
+        data = json.loads(reg.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        return [f"rules.json unparseable: {e}"]
+    on_disk = {d.name for d in fixture_dirs}
+    referenced = set()
+    for rule in data.get("rules", []):
+        for fx in rule.get("fixtures_exercising", []):
+            referenced.add(fx)
+            if fx not in on_disk:
+                problems.append(f"rules.json: {rule.get('rule_id', '?')} references missing fixture '{fx}'")
+    for d in sorted(on_disk - referenced):
+        problems.append(f"fixture '{d}' exists on disk but is registered under no rule in rules.json")
+    return problems
+
+
+def run_all(as_json=False):
+    results, ok = [], True
+    fixtures = sorted(d for d in FIXTURES.iterdir() if d.is_dir())
+    registry_problems = check_registry(fixtures)
+    ok &= not registry_problems
+    for fdir in fixtures:
+        meta = load_fixture_meta(fdir)
+        violations = validate_run(fdir, protected=meta["protected_areas"])
+        codes = sorted({c for c, _, _ in violations})
+        expected = sorted(set(meta["expected_violations"]))
+        if meta["expect"] == "pass":
+            fixture_ok = not violations
+            verdict_note = "clean" if fixture_ok else f"unexpected: {codes}"
+        else:  # expect: fail — the validator MUST catch exactly the planted faults
+            fixture_ok = codes == expected
+            verdict_note = "trapped as expected" if fixture_ok else f"expected {expected}, got {codes}"
+        ok &= fixture_ok
+        results.append({
+            "fixture": meta["id"], "expect": meta["expect"],
+            "violations": [f"{c} [{s}] {d}" for c, s, d in violations],
+            "codes": codes, "ok": fixture_ok, "note": verdict_note,
+        })
+    summary = {"fixtures": len(results), "passed": sum(r["ok"] for r in results), "all_ok": ok,
+               "registry_problems": registry_problems, "results": results}
+    if as_json:
+        print(json.dumps(summary, indent=2))
+    else:
+        for p in registry_problems:
+            print(f"[FAIL] REGISTRY DRIFT — {p}")
+        for r in results:
+            print(f"[{'PASS' if r['ok'] else 'FAIL'}] {r['fixture']:32s} expect={r['expect']:4s} → {r['note']}")
+        print(f"\n{summary['passed']}/{summary['fixtures']} fixtures OK — "
+              + ("ALL GREEN" if ok else "REGRESSIONS PRESENT"))
+    return 0 if ok else 1
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--run", help="validate one run directory (containing docs/)")
+    ap.add_argument("--all", action="store_true", help="run the full fixture suite")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--report", choices=["json", "sarif"],
+                    help="with --run: emit a structured findings report instead of plain violations")
+    ap.add_argument("--protected", default="", help="comma-separated protected paths (extends the target AUDIT.md's PROTECTED_AREAS)")
+    args = ap.parse_args()
+    if args.all:
+        sys.exit(run_all(as_json=args.json))
+    if args.run:
+        protected = [p for p in args.protected.split(",") if p]
+        v = validate_run(Path(args.run), protected=protected)
+        if args.report:
+            report = build_report(Path(args.run), protected, v)
+            print(json.dumps(to_sarif(report) if args.report == "sarif" else report, indent=2))
+        elif args.json:
+            print(json.dumps([{"code": c, "file": s, "detail": d} for c, s, d in v], indent=2))
+        else:
+            for c, s, d in v:
+                print(f"VIOLATION {c} [{s}] {d}")
+            print("CLEAN — no violations" if not v else f"{len(v)} violation(s)")
+        sys.exit(0 if not v else 1)
+    ap.print_help()
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()