flowharness 0.1.0__tar.gz

flowharness-0.1.0/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.

flowharness-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: flowharness
+Version: 0.1.0
+Summary: Architectural Drift Index and risk scan over a repo's agent-rules surface — local, deterministic, zero network
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: flowharness-core==0.1.0
+Requires-Dist: flowharness-inspection==0.1.0
+Requires-Dist: flowharness-portability==0.1.0
+Requires-Dist: httpx>=0.27 ; extra == 'remote'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/flowharness-ai
+Provides-Extra: remote
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# flowharness (flowharness-scan console script)
+
+<img src="assets/badge-example.svg" alt="flowharness drift badge" height="22" />
+
+**The Architectural Drift Index + Vibe-Risk scan for your repo's agent-rules surface.**
+
+Local · static · deterministic · zero network · zero model calls · zero config.
+
+</div>
+
+---
+
+`flowharness-scan` reads the agent-rules surface of a repository — `CLAUDE.md`,
+`.cursorrules`, `.cursor/rules/*.mdc`, `AGENTS.md`, `.continue/**`, `.opencode/**`,
+`playbook/**`, and an [agentharnesses](https://github.com/agentharnesses/agentharnesses)
+bundle (`HARNESS.md` + `skills/**/SKILL.md` + routing/reference files) — and tells you
+two things in one pass:
+
+- **How messy** it is — the **Architectural Drift Index** (0–100): duplication,
+  contradictions, orphaned rules, and cross-harness divergence.
+- **How dangerous** it is — a **quarantine verdict**: leaked secrets, indirect
+  prompt-injection, unattested/always-on guidance.
+
+## Quickstart
+
+No install required:
+
+```console
+$ uvx flowharness scan .
+flowharness-scan: drift index 30/100 - QUARANTINE (policy scoring/1)
+```
+
+`uvx flowharness init` scaffolds a new repo's agent-rules surface the same way, with no
+persistent install. `flowharness` and `flowharness-scan` are the same entry point (see below);
+`uvx --from flowharness flowharness-scan .` also works if you prefer the explicit name.
+
+> **Note:** these packages currently install top-level modules named `core`, `inspection`,
+> `evaluation`, and `portability`. Prefer `uvx` (isolated environments) over `pip install`
+> into a shared venv until the 0.2 module-namespace rename lands.
+
+Exit codes wire straight into CI / pre-commit: **PASS = 0 · NEEDS_HUMAN = 1 · FAIL = 2.**
+
+## Output modes
+
+```console
+$ flowharness-scan .                      # terminal banner (default)
+$ flowharness-scan . --json               # full inspection/v1 report (content-addressed)
+$ flowharness-scan . --badge > drift.svg  # local SVG badge for your README
+```
+
+## Gating
+
+```console
+$ flowharness-scan . --fail-on risk        # fail on the quarantine verdict (default)
+$ flowharness-scan . --fail-on "index>40"  # fail when the drift index exceeds 40
+$ flowharness-scan . --policy scoring.toml # custom, versioned scoring weights
+```
+
+### Baseline (only fail on *new* drift)
+
+```console
+$ flowharness-scan . --set-baseline > .flowharness-baseline.json   # commit this once
+$ flowharness-scan . --baseline .flowharness-baseline.json --fail-on baseline
+```
+
+`--set-baseline` writes nothing into your repo — it prints the baseline to stdout, so
+the scanner stays strictly read-only on the project directory.
+
+## Platform (opt-in network: `pull` / `upload`)
+
+The default scan path is **strictly zero-network**. The `pull`/`upload` subcommands and
+`scan --upload` are the *only* paths that touch the network (install the `[remote]` extra for the
+`httpx` dependency). They authenticate with a scoped bearer token.
+
+```console
+$ export FLOWHARNESS_API_URL=https://app.example.com   # required (or pass --api-url)
+$ export FLOWHARNESS_TOKEN=fht_...                      # the scoped bearer token
+
+$ flowharness-scan pull <release_id>                    # fetch a release's pins -> offline cache
+$ flowharness-scan . --upload --enrollment <id>         # scan, then upload the InspectionRecord
+$ flowharness-scan upload sync  --enrollment <id> --release <id> --observed observed.json
+$ flowharness-scan upload eval  --run run.json          # signs the report (X-Signature) + uploads
+```
+
+Notes: a leading token that names a real directory is scanned, not treated as a subcommand
+(`flowharness-scan ./pull` scans `./pull`). A remote `http://` URL is refused before any socket
+opens. Non-2xx responses map to stable exit codes (10–16); a duplicate upload (`409`) is treated as
+an idempotent success. `FLOWHARNESS_TOKEN` is the eval-signing HMAC key and is never written to disk.
+
+## `status` — am I running what the channel publishes?
+
+`flowharness status` answers two questions in one line — *is the applied release the channel's
+head?* and *has anyone edited the governed files?* — and it is **strictly read-only**: it writes
+nothing in any mode, and under `--offline` it opens no socket and imports no `httpx` at all.
+
+```console
+$ flowharness status
+flowharness: 2 releases behind stable (rel_9 → rel_11) — 'flowharness pull' to catch up
+
+$ flowharness status --json          # the flowharness/status/v1 payload, canonical bytes
+$ flowharness status --check         # exit 7 on proven divergence; stdout is unchanged
+$ flowharness status --offline       # local facts only; freshness is reported as unknown
+$ flowharness status --dir path/to/repo --channel beta --api-url https://app.example.com
+```
+
+`flowharness` and `flowharness-scan` are two names for the same entry point — the examples above
+and below use them interchangeably, and every subcommand works under either.
+
+Run it from anywhere inside the repo: `status` walks **up** to the nearest ancestor holding
+`.flowharness/` or `flowharness.toml`, stopping at a `.git` boundary, the way `git status` does.
+`--channel` overrides `[flowharness].channel`, which overrides the `stable` default.
+`--api-url` is accepted and ignored under `--offline`.
+
+**Exit map.** Bare `status` **always exits 0** — a corrupt lockfile, a dead network, a typo'd
+`flowharness.toml`, or an unreadable governed file is a *reported state*, never an exit code, so
+the verb is safe in a shell prompt. `--check` returns **7** on proven divergence (a governed file
+drifted, or the applied release is provably behind the head); if nothing diverged but the probe
+itself failed, it returns that failure's code (10–17). A bad flag or a `--dir` that does not
+exist is the usual argparse **2**.
+
+Divergence requires *proof*: an unreadable origin, an unrecognised origin, or an unorderable pair
+of release versions is reported as `unknown` (`drift.known: false` in the JSON) and `--check`
+returns 0 rather than claiming a divergence it did not observe.
+
+**Not yet here.** `--diff` (show the actual edits) lands with PR-D; serverless freshness (a git
+remote instead of a channel) lands with PR-F.
+
+**Known limitations.** Drift is byte-comparison against the lockfile's hashes, so: a filename
+stored NFC on Linux and NFD on macOS can flip between "converged" and "missing", and
+`core.autocrlf=true` on Windows makes every governed text file read as `modified`. Every
+governed file is re-hashed on every run (a megabyte at a time — a huge file is slow, never an
+out-of-memory), and a console that cannot encode the banner's `·`/`—`/`→` gets those characters
+back-slash-escaped rather than a traceback.
+
+Behind a corporate proxy or a private CA, note that the client sets `trust_env=False`: `status`,
+`pull` and `upload` deliberately ignore `HTTP_PROXY`/`HTTPS_PROXY` and
+`SSL_CERT_FILE`/`SSL_CERT_DIR`/`REQUESTS_CA_BUNDLE`, and there is not yet an explicit option to
+put them back.
+
+## Pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+-   repo: https://github.com/suleimanmahmoud/flowharness
+    rev: <tag>
+    hooks:
+    -   id: flowharness-scan
+```
+
+## What it flags
+
+| Dimension | Check | Catches |
+| --- | --- | --- |
+| duplication | `DuplicationCheck` | the same guideline pasted across files/sections |
+| contradiction | `ContradictionCheck` | retry-vs-fail-fast, tests-first-vs-prototype, … |
+| orphans | `OrphanCheck` | rules no active harness loads; leftovers of removed tools |
+| divergence | `DivergenceCheck` | the "same" rule that differs across harnesses |
+| risk | `LeakageCheck` | secrets/credentials/template-vars — **redacted to fingerprints** |
+| risk | `InjectionHeuristicsCheck` | indirect prompt-injection (override / exfil / fetch-and-execute) |
+| risk | `AttestationCheck` / `BoundsCheck` | unattested or implicitly always-on guidance |
+
+A finding **never contains a secret value**; the report carries structural metadata
+only (no rule-body text).
+
+## Guarantees
+
+- **Deterministic** — identical directory state ⇒ byte-identical report; ids and the
+  `report_hash` are content hashes; no timestamps.
+- **Read-only & offline** — the scanner only ever reads the project directory; no
+  network, no model calls on the default path.
+- **Fast** — a 50-unit repo scans in tens of milliseconds (budget: < 2 s).
+
+## Report
+
+`--json` emits the `inspection/v1` schema — snapshot metadata, redacted findings, the
+risk assessment, and the scored drift index — documented in
+[`docs/specs/inspection-report-v1.md`](../../docs/specs/inspection-report-v1.md).

flowharness-0.1.0/README.md

@@ -0,0 +1,179 @@
+<div align="center">
+
+# flowharness (flowharness-scan console script)
+
+<img src="assets/badge-example.svg" alt="flowharness drift badge" height="22" />
+
+**The Architectural Drift Index + Vibe-Risk scan for your repo's agent-rules surface.**
+
+Local · static · deterministic · zero network · zero model calls · zero config.
+
+</div>
+
+---
+
+`flowharness-scan` reads the agent-rules surface of a repository — `CLAUDE.md`,
+`.cursorrules`, `.cursor/rules/*.mdc`, `AGENTS.md`, `.continue/**`, `.opencode/**`,
+`playbook/**`, and an [agentharnesses](https://github.com/agentharnesses/agentharnesses)
+bundle (`HARNESS.md` + `skills/**/SKILL.md` + routing/reference files) — and tells you
+two things in one pass:
+
+- **How messy** it is — the **Architectural Drift Index** (0–100): duplication,
+  contradictions, orphaned rules, and cross-harness divergence.
+- **How dangerous** it is — a **quarantine verdict**: leaked secrets, indirect
+  prompt-injection, unattested/always-on guidance.
+
+## Quickstart
+
+No install required:
+
+```console
+$ uvx flowharness scan .
+flowharness-scan: drift index 30/100 - QUARANTINE (policy scoring/1)
+```
+
+`uvx flowharness init` scaffolds a new repo's agent-rules surface the same way, with no
+persistent install. `flowharness` and `flowharness-scan` are the same entry point (see below);
+`uvx --from flowharness flowharness-scan .` also works if you prefer the explicit name.
+
+> **Note:** these packages currently install top-level modules named `core`, `inspection`,
+> `evaluation`, and `portability`. Prefer `uvx` (isolated environments) over `pip install`
+> into a shared venv until the 0.2 module-namespace rename lands.
+
+Exit codes wire straight into CI / pre-commit: **PASS = 0 · NEEDS_HUMAN = 1 · FAIL = 2.**
+
+## Output modes
+
+```console
+$ flowharness-scan .                      # terminal banner (default)
+$ flowharness-scan . --json               # full inspection/v1 report (content-addressed)
+$ flowharness-scan . --badge > drift.svg  # local SVG badge for your README
+```
+
+## Gating
+
+```console
+$ flowharness-scan . --fail-on risk        # fail on the quarantine verdict (default)
+$ flowharness-scan . --fail-on "index>40"  # fail when the drift index exceeds 40
+$ flowharness-scan . --policy scoring.toml # custom, versioned scoring weights
+```
+
+### Baseline (only fail on *new* drift)
+
+```console
+$ flowharness-scan . --set-baseline > .flowharness-baseline.json   # commit this once
+$ flowharness-scan . --baseline .flowharness-baseline.json --fail-on baseline
+```
+
+`--set-baseline` writes nothing into your repo — it prints the baseline to stdout, so
+the scanner stays strictly read-only on the project directory.
+
+## Platform (opt-in network: `pull` / `upload`)
+
+The default scan path is **strictly zero-network**. The `pull`/`upload` subcommands and
+`scan --upload` are the *only* paths that touch the network (install the `[remote]` extra for the
+`httpx` dependency). They authenticate with a scoped bearer token.
+
+```console
+$ export FLOWHARNESS_API_URL=https://app.example.com   # required (or pass --api-url)
+$ export FLOWHARNESS_TOKEN=fht_...                      # the scoped bearer token
+
+$ flowharness-scan pull <release_id>                    # fetch a release's pins -> offline cache
+$ flowharness-scan . --upload --enrollment <id>         # scan, then upload the InspectionRecord
+$ flowharness-scan upload sync  --enrollment <id> --release <id> --observed observed.json
+$ flowharness-scan upload eval  --run run.json          # signs the report (X-Signature) + uploads
+```
+
+Notes: a leading token that names a real directory is scanned, not treated as a subcommand
+(`flowharness-scan ./pull` scans `./pull`). A remote `http://` URL is refused before any socket
+opens. Non-2xx responses map to stable exit codes (10–16); a duplicate upload (`409`) is treated as
+an idempotent success. `FLOWHARNESS_TOKEN` is the eval-signing HMAC key and is never written to disk.
+
+## `status` — am I running what the channel publishes?
+
+`flowharness status` answers two questions in one line — *is the applied release the channel's
+head?* and *has anyone edited the governed files?* — and it is **strictly read-only**: it writes
+nothing in any mode, and under `--offline` it opens no socket and imports no `httpx` at all.
+
+```console
+$ flowharness status
+flowharness: 2 releases behind stable (rel_9 → rel_11) — 'flowharness pull' to catch up
+
+$ flowharness status --json          # the flowharness/status/v1 payload, canonical bytes
+$ flowharness status --check         # exit 7 on proven divergence; stdout is unchanged
+$ flowharness status --offline       # local facts only; freshness is reported as unknown
+$ flowharness status --dir path/to/repo --channel beta --api-url https://app.example.com
+```
+
+`flowharness` and `flowharness-scan` are two names for the same entry point — the examples above
+and below use them interchangeably, and every subcommand works under either.
+
+Run it from anywhere inside the repo: `status` walks **up** to the nearest ancestor holding
+`.flowharness/` or `flowharness.toml`, stopping at a `.git` boundary, the way `git status` does.
+`--channel` overrides `[flowharness].channel`, which overrides the `stable` default.
+`--api-url` is accepted and ignored under `--offline`.
+
+**Exit map.** Bare `status` **always exits 0** — a corrupt lockfile, a dead network, a typo'd
+`flowharness.toml`, or an unreadable governed file is a *reported state*, never an exit code, so
+the verb is safe in a shell prompt. `--check` returns **7** on proven divergence (a governed file
+drifted, or the applied release is provably behind the head); if nothing diverged but the probe
+itself failed, it returns that failure's code (10–17). A bad flag or a `--dir` that does not
+exist is the usual argparse **2**.
+
+Divergence requires *proof*: an unreadable origin, an unrecognised origin, or an unorderable pair
+of release versions is reported as `unknown` (`drift.known: false` in the JSON) and `--check`
+returns 0 rather than claiming a divergence it did not observe.
+
+**Not yet here.** `--diff` (show the actual edits) lands with PR-D; serverless freshness (a git
+remote instead of a channel) lands with PR-F.
+
+**Known limitations.** Drift is byte-comparison against the lockfile's hashes, so: a filename
+stored NFC on Linux and NFD on macOS can flip between "converged" and "missing", and
+`core.autocrlf=true` on Windows makes every governed text file read as `modified`. Every
+governed file is re-hashed on every run (a megabyte at a time — a huge file is slow, never an
+out-of-memory), and a console that cannot encode the banner's `·`/`—`/`→` gets those characters
+back-slash-escaped rather than a traceback.
+
+Behind a corporate proxy or a private CA, note that the client sets `trust_env=False`: `status`,
+`pull` and `upload` deliberately ignore `HTTP_PROXY`/`HTTPS_PROXY` and
+`SSL_CERT_FILE`/`SSL_CERT_DIR`/`REQUESTS_CA_BUNDLE`, and there is not yet an explicit option to
+put them back.
+
+## Pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+-   repo: https://github.com/suleimanmahmoud/flowharness
+    rev: <tag>
+    hooks:
+    -   id: flowharness-scan
+```
+
+## What it flags
+
+| Dimension | Check | Catches |
+| --- | --- | --- |
+| duplication | `DuplicationCheck` | the same guideline pasted across files/sections |
+| contradiction | `ContradictionCheck` | retry-vs-fail-fast, tests-first-vs-prototype, … |
+| orphans | `OrphanCheck` | rules no active harness loads; leftovers of removed tools |
+| divergence | `DivergenceCheck` | the "same" rule that differs across harnesses |
+| risk | `LeakageCheck` | secrets/credentials/template-vars — **redacted to fingerprints** |
+| risk | `InjectionHeuristicsCheck` | indirect prompt-injection (override / exfil / fetch-and-execute) |
+| risk | `AttestationCheck` / `BoundsCheck` | unattested or implicitly always-on guidance |
+
+A finding **never contains a secret value**; the report carries structural metadata
+only (no rule-body text).
+
+## Guarantees
+
+- **Deterministic** — identical directory state ⇒ byte-identical report; ids and the
+  `report_hash` are content hashes; no timestamps.
+- **Read-only & offline** — the scanner only ever reads the project directory; no
+  network, no model calls on the default path.
+- **Fast** — a 50-unit repo scans in tens of milliseconds (budget: < 2 s).
+
+## Report
+
+`--json` emits the `inspection/v1` schema — snapshot metadata, redacted findings, the
+risk assessment, and the scored drift index — documented in
+[`docs/specs/inspection-report-v1.md`](../../docs/specs/inspection-report-v1.md).

flowharness-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "flowharness"
+version = "0.1.0"
+description = "Architectural Drift Index and risk scan over a repo's agent-rules surface — local, deterministic, zero network"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "flowharness-core==0.1.0",
+    "flowharness-inspection==0.1.0",
+    "flowharness-portability==0.1.0",
+]
+
+[project.optional-dependencies]
+remote = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/flowharness-ai"
+
+[project.scripts]
+flowharness = "flowharness_scan.cli:main"
+flowharness-scan = "flowharness_scan.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "flowharness_scan"
+
+[tool.uv.sources.flowharness-core]
+workspace = true
+
+[tool.uv.sources.flowharness-inspection]
+workspace = true
+
+[tool.uv.sources.flowharness-portability]
+workspace = true

flowharness-0.1.0/pyproject.toml.orig

@@ -0,0 +1,50 @@
+[project]
+# Dist name is the bare `flowharness` (name verified free 2026-07; claimed at first
+# v0.1.0 publish) so the spec-pinned
+# `uvx flowharness scan` invocation (product/07 §4.1, ci_governance_spec §2.7) resolves
+# verbatim. Module stays `flowharness_scan`; `flowharness-scan` console script kept for back-compat.
+name = "flowharness"
+version = "0.1.0"
+description = "Architectural Drift Index and risk scan over a repo's agent-rules surface — local, deterministic, zero network"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# Internal deps pin ==0.1.0: the six OSS packages version in lockstep (release.yml builds
+# them from one tag), and [tool.uv.sources] workspace=true overrides these locally.
+dependencies = [
+    "flowharness-core==0.1.0",
+    "flowharness-inspection==0.1.0",
+    "flowharness-portability==0.1.0",
+]
+
+# The opt-in network client (`pull`/`upload`) needs httpx; the default scan path stays
+# zero-network and zero-dependency-on-httpx (rule 10). Install with `flowharness[remote]`.
+[project.optional-dependencies]
+remote = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/flowharness-ai"
+
+[project.scripts]
+# `flowharness` is the primary verb-router alias; `flowharness-scan` is KEPT for
+# back-compat. Both dispatch the same `main` (PR-P2-B D-P2-7 / decision D-4).
+flowharness = "flowharness_scan.cli:main"
+flowharness-scan = "flowharness_scan.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "flowharness_scan"
+
+[tool.uv.sources]
+flowharness-core = { workspace = true }
+flowharness-inspection = { workspace = true }
+flowharness-portability = { workspace = true }