fable5-assurance-toolkit 0.3.0rc5__tar.gz

fable5_assurance_toolkit-0.3.0rc5/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 [yyyy] [name of copyright owner]
+
+   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.
+

fable5_assurance_toolkit-0.3.0rc5/MANIFEST.in

@@ -0,0 +1,8 @@
+include VERSION
+graft tests
+graft fixtures
+graft contracts
+graft docs
+graft examples
+global-exclude __pycache__
+global-exclude *.py[cod]

fable5_assurance_toolkit-0.3.0rc5/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: fable5-assurance-toolkit
+Version: 0.3.0rc5
+Summary: Local deterministic assurance controls reconstructed under a new lineage
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/dormitivegit/fable5-assurance-toolkit
+Project-URL: Issues, https://github.com/dormitivegit/fable5-assurance-toolkit/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# FABLE5 Assurance Toolkit
+
+FABLE5 is a local, deterministic command-line toolkit for applying assurance
+and conformance controls to AI-assisted software-engineering workflows. It
+turns structured task inputs, governance packs, terminal states, corpus
+manifests, handoffs, closeouts, and evaluation records into reproducible
+findings that humans and automation can inspect.
+
+AI-assisted changes can move faster than the evidence needed to review them.
+FABLE5 makes selected behavioral contracts explicit and repeatable without a
+hosted service, background agent, network call, or model invocation. It
+complements tests and human review; it does not replace either or make release
+decisions.
+
+## Quick start
+
+FABLE5 requires Python 3.11 or newer and has no non-standard-library Python
+runtime dependencies. For the checkout-based examples below, run commands from
+the repository root. Install it in an isolated environment:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+assurance --version
+assurance --help
+```
+
+Run a deterministic governance-pack check against the included fixture:
+
+```sh
+assurance check fixtures/governance/valid-pack.json --format json
+```
+
+For authorization-bearing `check`, `guard`, and `closeout` inputs, the caller
+supplies the expected identity with `--authority-id <IDENTITY>`. Leading and
+trailing whitespace is ignored; the remaining identifier is compared exactly
+and case-sensitively. This is an out-of-band caller input; the document being
+validated cannot set or override it. Read-only validation does not require an
+authority ID.
+
+For repository-only development without installation, use:
+
+```sh
+PYTHONPATH=src python3 -m assurance_toolkit --version
+PYTHONPATH=src python3 -m assurance_toolkit --help
+```
+
+Run the complete test suite:
+
+```sh
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src \
+  python3 -m unittest discover -s tests -v
+```
+
+Use `--format json` when another tool or AI agent will consume the result. Run
+`python3 -m assurance_toolkit <command> --help` for command-specific options.
+
+## Start here: choose a command
+
+| If you need to… | Start with |
+| --- | --- |
+| assess the risk and required controls for a bounded proposed action | `assurance classify fixtures/classify/read-local-document.json --format json` |
+| validate a structured governance document before relying on it | `assurance check PACK.json --format json` |
+| inspect a terminal state or target collision without changing either | `assurance guard STATE.json TARGET --executor NAME --format json` |
+| freeze or verify the exact bytes of a bounded source set | `assurance corpus freeze ROOT --manifest MANIFEST --format json` or `assurance corpus verify MANIFEST --format json` |
+| structurally inspect a handoff or closeout record | `assurance handoff HANDOFF.json --carrier CARRIER --format json` or `assurance closeout CLOSEOUT.json --format json` |
+| prepare preserved evaluation cases or score supplied judgments | `assurance eval prepare CASES.jsonl --out PREPARED.json --format json` or `assurance eval score CASES.jsonl SCORES.jsonl --format json` |
+
+The commands report bounded evidence. They do not authorize a change, decide a
+merge, or replace human review.
+
+For an already accepted corpus manifest, bind verification to its exact raw
+bytes as well as its semantic records:
+
+```sh
+assurance corpus verify MANIFEST \
+  --accepted-manifest-sha256 SHA256 \
+  --format json
+```
+
+The accepted SHA-256 is caller supplied. It anchors the exact manifest bytes
+and therefore the recorded scope declaration; it does not prove that the
+chosen roots or exclusions are complete, optimal, or authorized.
+
+Corpus manifests bind sources to the absolute filesystem paths recorded at
+freeze time. Verification expects those paths to keep identifying the intended
+sources; a manifest is not a portable "freeze on one machine, verify under a
+different layout" artifact. Manifests also disclose absolute paths and
+per-file hashes, so do not publish sensitive manifests verbatim or freeze
+credential-bearing roots.
+
+`--exclude` uses path containment/prefix semantics, not shell glob matching.
+With `--detect-new`, current normal verification reports
+`CI10_NEW_SOURCE_DETECTED` as `WARN`; when it is the only finding, the process
+still exits `0`. Consumers that need new-file gating must inspect structured
+findings as well as the process exit status.
+
+## CLI output and exit contract
+
+The normative, machine-readable contract is
+[`contracts/schemas/CLI_OUTPUT_CONTRACT.json`](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/contracts/schemas/CLI_OUTPUT_CONTRACT.json).
+It distinguishes ModuleResult JSON, CLI parse-failure JSON, argparse usage
+text, help/version text, and the existing synthetic-pilot JSON shape. In
+particular, parse-failure JSON uses the command string as `module_id` and
+`recovery-1` as `rule_set_version`; argparse usage failures emit no JSON.
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | PASS or successful non-error command |
+| 1 | generic FAIL |
+| 2 | input/invocation-class FAIL |
+| 3 | generic HOLD |
+| 4 | integrity-family HOLD |
+| 5 | terminal/target-family HOLD |
+
+For structured module outcomes, finding severity first determines whether the
+outcome is blocking: `ERROR` and `HOLD` block, while `WARN` and `INFO` do not
+block under the normal profile. `--profile strict` can promote `WARN` to
+effective blocking for the final decision without changing the serialized
+finding's severity label. A non-blocking finding does not select a nonzero exit
+solely because its prefix belongs to an exit family.
+
+For effectively blocking module outcomes, PM-03 normally applies the
+terminal-family exit floor/pin and PM-04 normally applies the integrity-family
+exit floor/pin, subject to explicit decision exceptions published in the
+normative CLI contract. This module-selected effective exit family is distinct
+from the family suggested by an individual finding prefix. After severity,
+profile promotion, any module floor/pin, and any exact exception are resolved,
+precedence remains
+`terminal(5) > integrity(4) > HOLD-severity(3) > input-class(2) > generic(1)`.
+The table above is a summary; consumers that need exact decision behavior must
+use the normative JSON contract.
+
+This build publishes the current output/exit contract, not the complete
+current-generation input contract needed to reauthor every preserved A1 case.
+A1 remains predecessor-generation evidence only, not a current release gate,
+compatibility claim, or adoption claim. Any future reactivation requires
+sufficient normative input and output authority plus fresh execution and
+discriminating-power evidence.
+
+## Try the end-to-end example
+
+Run a deterministic walkthrough that surrounds a simulated agent-generated
+change with risk, integrity, and handoff evidence:
+
+```sh
+./examples/agent-change-assurance/run.sh
+```
+
+The example is local, network-free, self-cleaning, and leaves acceptance to a
+human reviewer. See the [example guide](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/examples/agent-change-assurance/README.md)
+for the expected flow and claim boundaries.
+
+## Try a machine-consumer integration
+
+From the repository root, run:
+
+```sh
+python3 examples/machine-consumer/run.py
+```
+
+This small, disposable example creates a bounded source set, consumes JSON
+from `corpus verify --detect-new`, and takes a review branch when a nonblocking
+`WARN` finding is present even though the process exit is `0`. It demonstrates
+why a consumer must inspect structured findings rather than branch on exit
+status alone. See the [machine-consumer guide](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/examples/machine-consumer/README.md).
+
+## Modules
+
+| Module | CLI surface | Purpose |
+| --- | --- | --- |
+| PM-01 Risk Router | `classify` | Classifies task risk from the effects of a proposed action. |
+| PM-02 Governance Pack Validator | `check` | Validates structured claims, decisions, actions, and exact source references. |
+| PM-03 Terminal State and Artifact Guard | `guard` | Performs a read-only preflight for terminal-state and target-collision conditions. |
+| PM-04 Corpus Integrity Guard | `corpus freeze`, `corpus verify` | Creates and verifies bounded, hash-addressed corpus manifests. |
+| PM-05 Handoff and Closeout Validator | `handoff`, `closeout` | Checks handoff carriers and closeout records against explicit contracts. |
+| PM-06 Successor Evaluation Harness | `eval prepare`, `eval score` | Prepares preserved evaluation cases and scores externally supplied judgments. |
+
+The `pilot run` surface provides four synthetic pilots (`A`, `B`, `C1`, and
+`C2`) for exercising selected module interactions inside a newly supplied
+disposable root. Pilot C2 is the only pilot-local writer that demonstrates an
+atomic no-clobber seam; it is not reachable from ordinary project workflows.
+
+## Design properties
+
+- **Deterministic:** rules, findings, ordering, and output formats are designed
+  for repeatable inspection from the same bounded inputs.
+- **Local-first and network-free:** the core modules use only the Python
+  standard library and do not contact remote services. Synthetic Pilot B uses
+  an already installed local Git executable as its test subject with hooks and
+  user/system configuration disabled.
+- **Explicit contracts:** versioned schemas, identities, fixtures, and
+  evaluation records keep behavioral expectations reviewable in the
+  repository.
+- **Fail-closed parsing:** malformed or incomplete inputs produce structured
+  failure findings instead of implied success.
+- **Bounded side effects:** validation and guard surfaces are read-only;
+  artifact-producing commands require explicit destinations, and synthetic
+  pilot writes are confined to a caller-supplied disposable root.
+- **No hidden control plane:** there is no daemon, database, web UI, installed
+  hook, automatic model call, semantic auto-score, or automatic promotion path.
+
+See [Architecture](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/docs/ARCHITECTURE.md),
+[module scope and non-goals](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/docs/MODULE_SCOPE_AND_NON_GOALS.md), and
+[known limitations](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/docs/LIMITATIONS_AND_FUTURE_SEAMS.md) for the detailed
+boundaries. Read [validated workflows](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/docs/VALIDATED_WORKFLOWS.md) for two
+bounded, maintainer-controlled downstream cases and their claim limits.
+
+## AI-agent and maintainer workflow
+
+1. A human or automation supplies a bounded input and chooses the applicable
+   FABLE5 command and profile.
+2. An AI agent or CI job runs the command, preserves its structured output, and
+   treats nonzero exit codes and findings as review evidence.
+3. The submitter runs the test suite and explains any intentional behavioral
+   contract change in the pull request.
+4. A maintainer reviews the code, tests, deterministic output, compatibility,
+   and security impact before deciding whether to merge or release.
+
+FABLE5 reports on the contracts it implements. It does not establish business
+truth, infer authorization, approve its own changes, or promote a candidate to
+production. Those decisions remain with people responsible for the project.
+
+## Project status and provenance
+
+```text
+PRODUCT_VERSION=0.3.0-recovery.5
+PYTHON_DISTRIBUTION_VERSION=0.3.0rc5
+STATUS=full-functional-recovery-candidate
+LINEAGE_ID=FABLE5-ASSURANCE-TOOLKIT-FULL-FUNCTIONAL-RECOVERY-20260713
+```
+
+This repository is a clean-room functional reconstruction under a new Git
+lineage, based on accepted architecture, contracts, sanitized fixtures, tests,
+and pilot requirements. It claims continuity of the accepted functional
+contract, not recovery of historical source bytes, commits, or tags. The
+`v0.3.0-recovery.1` tag identifies the first recovery candidate in the
+reconstructed lineage; `v0.3.0-recovery.2` records the subsequent public
+open-source surface hardening; `v0.3.0-recovery.3` generalizes the public
+authorization contract for external maintainers; and `v0.3.0-recovery.4`
+publishes the current contract hardening and consumer guidance. The prepared
+`v0.3.0-recovery.5` release adds first-run navigation, validated
+maintainer-controlled workflow summaries, a runnable machine-consumer path,
+and PEP 517 distribution metadata; it does not itself publish a package.
+
+The current status means the six modules and public interface have been
+reconstructed and mechanically tested. Bounded independent review exists for
+the current contract/runtime correction; this is not a claim of comprehensive
+independent review, user acceptance, external validation, canonical promotion,
+production readiness, or ecosystem adoption. See
+[status semantics](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/docs/STATUS_SEMANTICS.md) and
+[recovery lineage](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/docs/RECOVERY_LINEAGE.md) for the precise claims.
+
+## Contributing
+
+Focused issues and pull requests are welcome. Read
+[CONTRIBUTING.md](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/CONTRIBUTING.md) for test, determinism, and AI-assisted
+contribution expectations. Maintainer roles are documented in
+[MAINTAINERS.md](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/MAINTAINERS.md).
+
+## Security
+
+Do not report vulnerabilities or exploit details in a public issue. Follow the
+private reporting process in [SECURITY.md](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/SECURITY.md).
+
+## License
+
+Licensed under the [Apache License 2.0](https://github.com/dormitivegit/fable5-assurance-toolkit/blob/main/LICENSE).