countersign-cli 0.2.0__tar.gz

countersign_cli-0.2.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.

countersign_cli-0.2.0/NOTICE

@@ -0,0 +1,5 @@
+Countersign
+Copyright 2026 Krishna
+
+This product includes software developed by the Countersign authors.
+Licensed under the Apache License, Version 2.0.

countersign_cli-0.2.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: countersign-cli
+Version: 0.2.0
+Summary: Your agent signs. Countersign proves it. Deterministic verification of agent completion claims, with tamper-evident receipts.
+Author: Krishna
+License-Expression: Apache-2.0
+Keywords: ai-agents,verification,ci,developer-tools,evidence
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+<!-- audited on 20260903 -->
+# Countersign
+
+**Your agent signs. Countersign proves it.**
+
+Agents report work as done that was never done. A plausible final message becomes the record of what was verified, and nobody can tell the difference between "the tests passed" and "the agent said the tests passed". Countersign is the difference: a deterministic gate that makes every completion claim falsifiable, runs the disproof commands itself, and writes a tamper-evident receipt.
+
+```
+$ countersign verify
+
+Countersign run 20260902T104512-a3f8c21e
+  commit 4a1b09f0c3d2e1f4a5b6c7d8e9f0a1b2c3d4e5f6 · 214 files scanned · 8120 ms
+
+✗ marker scan: 3 finding(s)
+    src/app/page.tsx:41  [unfinished-marker]  // TODO: wire this to the real API
+    src/lib/pricing.ts:12  [fabricated-data]  return 49.99  // fake data until billing lands
+    src/lib/notify.py:8  [empty-body]  def send_invoice(order_id: str) -> None:
+✗ claim tests-pass: The full test suite passes
+    command: npm test
+    output ends: 2 failing
+– note: test files were excluded from the marker scan by policy (exclude_tests = true)
+
+NOT COUNTERSIGNED · 3 finding(s), 1 failed claim(s)
+The work did not pass its own declared checks. Fix the code or the claims.
+```
+
+## Why this exists
+
+Three things became true at once in 2026:
+
+1. Most new code is written by agents, and agents report success for work that was never finished, plausibly and at scale.
+2. Teams ship that code anyway, because "looks done" and "is done" stopped being distinguishable by reading a pull request.
+3. Vendors bolted self-verification onto their own agents, which is the fox counting the chickens. An audit trail written by the system being audited proves what the system says it did. Independence is structural, not a feature.
+
+Countersign is independent by construction: it runs outside the agent, checks deterministically, records everything to a hash-chained register, and refuses to countersign work that did not pass its own declared checks. No model judgement participates in any verdict.
+
+## The claims protocol
+
+An agent (or a human) declares what is true about the work in `claims.toml`. Each claim carries the command that fails if the claim is false:
+
+```toml
+[[claim]]
+id = "tests-pass"
+statement = "The full test suite passes"
+command = "npm test"
+expect = "exit 0"
+
+[[claim]]
+id = "pricing-is-live"
+statement = "The pricing endpoint returns real numbers, not seed data"
+command = "curl -sf http://localhost:8000/api/pricing"
+expect = "output contains"
+needle = "unit_price"
+```
+
+If nobody can say what command would disprove the claim, the claim was not a claim. Three expectations are supported: `exit 0`, `nonzero exit` (negative tests), and `output contains`. A claim that runs past its timeout is killed together with everything it spawned and recorded as timed out, which fails the gate.
+
+Claim commands run through your shell, in the repository root, with your privileges. Treat `claims.toml` like any other executable file in the repository: review changes to it the way you review changes to CI configuration.
+
+## Who guards the claims
+
+The agent that wrote the code can also write the claims, and the quiet way past a gate is not to fix the code but to soften the claim. Three things make that visible:
+
+- **Required claims.** `required = ["tests-pass"]` in `countersign.toml` names claim ids that must be declared. A required claim nobody wrote is recorded as `MISSING` and fails the gate, so deleting the claim is not a way out.
+- **Claims diff.** `countersign verify --claims-base origin/main` (the GitHub action does this on every pull request) compares `claims.toml` with the base branch and names every change. A removed claim, a changed expectation or a changed needle is a weakening and fails the gate (`fail_on_weakened = true`); a changed command is listed for the reviewer. `countersign claims diff --base origin/main` prints the same diff on its own.
+- **Claims from the agent's own report.** `countersign claims from-report done.md` (or `-` for standard input) turns the checkable sentences of an agent's completion message into proposed claims: "all tests pass" becomes the repository's test command, "created src/pricing.ts" becomes a file check, a URL becomes a request that must succeed. The agent's own sentence is kept as the statement, so the receipt later says which promise held. Deterministic English patterns; a sentence whose command cannot be derived from the repository is reported as unresolved, never guessed. `--write` appends them to `claims.toml`.
+- **Starter claims.** `countersign init` reads the build files that are actually there (package.json scripts, pytest or ruff configuration, go.mod, Cargo.toml) and writes a `claims.toml` with the stack's own test, lint and type-check commands, marking `tests-pass` as required. Nothing is guessed; a repository with no recognised build files gets a commented example.
+
+## The marker scan
+
+Eleven rules ported from a gate that ran daily on a production tree of more than 500 source files, reviewed file by file, with zero false positives, plus a structural check for functions whose body does nothing and explains nothing, which catches unfinished work that forgot to advertise itself. A bare `pass`, `...` or `{}` is a stub; the same body with a docstring or a comment is a documented decision (an irreversible migration's `downgrade`, a `close()` with nothing to close) and is not reported. Python is checked through the parser (overloads, abstract and Protocol methods are exempt). TypeScript and JavaScript are checked by a comment-and-string-aware scan of function declarations, class and object methods, and exported arrow functions (constructors, Angular lifecycle hooks, unexported callbacks, `.d.ts` and minified files are exempt). The eleven marker rules apply to every language in scope.
+
+Point `paths` at production source (the original gate covered `src/`, the dashboard and the clients, not seed scripts or migrations); prose about stubs in a seed script is not a stub. Test files are excluded by policy: test code legitimately fabricates data, and the receipt says so. A genuine false positive is exempted in the source itself, on the line, where a reviewer sees it. Every exemption that suppressed a finding is counted on the receipt; a marker that suppresses nothing is reported as inert so a stale one cannot hide.
+
+## Receipts, register, reproduce
+
+- Every run appends to `.countersign/register.jsonl`: an append-only, hash-chained log. Edit any earlier line and `countersign check` says so. Appends are locked, so two runs on one checkout cannot break the chain by racing.
+- What the register proves, exactly: that no entry was altered after it was written by anyone who did not also rewrite every entry after it. It lives on the machine that ran the checks, so on its own it is evidence against accident and against third parties, not against the machine's owner. Tamper evidence against the owner requires the register head to be anchored outside the machine, which is what a hosted anchoring service is for.
+- Every run writes a JSON receipt and, unless asked not to, a single-file HTML evidence pack: what was checked, how, what was found, what was not covered. The pack and the Markdown summary open with the result in plain words, written for the person who asked the agent for the feature rather than for the engineer reading the tables. Receipts name the git commit and say whether the working tree had uncommitted changes when it was scanned.
+- `countersign reproduce --run <id>` re-derives a recorded run from the same inputs and compares, result for result. The run recorded the SHA-256 of the config and claims files it read; if they changed, you are told.
+
+Exit codes: 0 countersigned or reproduced, 1 not countersigned (or the register is damaged, or the run did not reproduce), 2 usage error including a config or claims file that cannot be honoured as written, 130 interrupted.
+
+## Install and run
+
+```bash
+pip install countersign-cli
+countersign init         # writes countersign.toml, a starter claims.toml and, on GitHub, the workflow
+countersign verify       # scan + claims gate; writes receipt, pack, register
+countersign check        # the register's hash chain
+countersign reproduce --run <id>
+countersign claims diff --base origin/main
+```
+
+The user guide, with screenshots of every command and the evidence pack, is in [docs/guide.md](docs/guide.md).
+
+Requires Python 3.11+. Zero dependencies, standard library only, on purpose: it has to run inside any CI runner, any locked-down laptop, any air-gapped environment, with no supply-chain conversation. It also runs without installing: `PYTHONPATH=/path/to/countersign python3 -m countersign verify`.
+
+## CI usage (GitHub Actions)
+
+When the repository's origin is on github.com, `countersign init` also writes `.github/workflows/countersign.yml`. Commit it and push; from then on every push to the default branch and every pull request runs Countersign, and pull requests get the claims diff against their base branch. The file it writes is this:
+
+```yaml
+- uses: krishnaflipprr/countersign@v0.2
+  with:
+    config: countersign.toml
+```
+
+The action runs Countersign straight from its checkout (no pip install, nothing fetched from PyPI). The verdict lands in the job step summary; receipts upload as artifacts. Set `fail-on: warn` to record without failing. If your config moves the receipts directory, set `receipts-dir` to match. Set `attest: true` to sign the receipt with GitHub Artifact Attestations; that is free for public repositories on every plan, while private repositories need GitHub Enterprise Cloud, and the job must grant `id-token: write` and `attestations: write`. Workflows run on the account that owns the repository, on its Actions minutes.
+
+## What Countersign is not
+
+Not a security scanner, not a code review, not a statement of fitness for any purpose. It verifies declared claims deterministically and scans for unfinished-work markers. The evidence pack states its own limits on every page.
+
+## Try the demo
+
+The `demo/` directory is a small accounts service with defects planted in it: a marker comment, fabricated return data, a function that raises instead of doing work, a body that does nothing, plus one true claim and one false one.
+
+```bash
+countersign verify --config demo/countersign.toml
+```
+
+Expected outcome: NOT COUNTERSIGNED, four findings listed, the false claim caught.
+
+## Status and roadmap
+
+v0.1. Working: marker scan, structural empty-body check (Python, TypeScript, JavaScript), claims protocol with required claims and claims diff, register, receipts, evidence packs, reproduce, CI action, starter config and workflow from `init`. Next: wiring cross-checks (frontend fields against the backend endpoints that feed them), agent-report parsing (verify the claims in an agent's own completion message), public receipt badges, hosted receipt verification. The register and evidence-pack engine is shared with Gaigentic Verify, which applies it to regulated finance decisions; Countersign itself makes no regulatory claim.
+
+## License
+
+Apache License 2.0 (see LICENSE and NOTICE). The command line tool, every scan rule, the claims protocol, the register, receipts, packs and reproduce are open source in full and stay fully functional offline. Hosted anchoring, badges and organisation features are a separate service.

countersign_cli-0.2.0/README.md

@@ -0,0 +1,131 @@
+<!-- audited on 20260903 -->
+# Countersign
+
+**Your agent signs. Countersign proves it.**
+
+Agents report work as done that was never done. A plausible final message becomes the record of what was verified, and nobody can tell the difference between "the tests passed" and "the agent said the tests passed". Countersign is the difference: a deterministic gate that makes every completion claim falsifiable, runs the disproof commands itself, and writes a tamper-evident receipt.
+
+```
+$ countersign verify
+
+Countersign run 20260902T104512-a3f8c21e
+  commit 4a1b09f0c3d2e1f4a5b6c7d8e9f0a1b2c3d4e5f6 · 214 files scanned · 8120 ms
+
+✗ marker scan: 3 finding(s)
+    src/app/page.tsx:41  [unfinished-marker]  // TODO: wire this to the real API
+    src/lib/pricing.ts:12  [fabricated-data]  return 49.99  // fake data until billing lands
+    src/lib/notify.py:8  [empty-body]  def send_invoice(order_id: str) -> None:
+✗ claim tests-pass: The full test suite passes
+    command: npm test
+    output ends: 2 failing
+– note: test files were excluded from the marker scan by policy (exclude_tests = true)
+
+NOT COUNTERSIGNED · 3 finding(s), 1 failed claim(s)
+The work did not pass its own declared checks. Fix the code or the claims.
+```
+
+## Why this exists
+
+Three things became true at once in 2026:
+
+1. Most new code is written by agents, and agents report success for work that was never finished, plausibly and at scale.
+2. Teams ship that code anyway, because "looks done" and "is done" stopped being distinguishable by reading a pull request.
+3. Vendors bolted self-verification onto their own agents, which is the fox counting the chickens. An audit trail written by the system being audited proves what the system says it did. Independence is structural, not a feature.
+
+Countersign is independent by construction: it runs outside the agent, checks deterministically, records everything to a hash-chained register, and refuses to countersign work that did not pass its own declared checks. No model judgement participates in any verdict.
+
+## The claims protocol
+
+An agent (or a human) declares what is true about the work in `claims.toml`. Each claim carries the command that fails if the claim is false:
+
+```toml
+[[claim]]
+id = "tests-pass"
+statement = "The full test suite passes"
+command = "npm test"
+expect = "exit 0"
+
+[[claim]]
+id = "pricing-is-live"
+statement = "The pricing endpoint returns real numbers, not seed data"
+command = "curl -sf http://localhost:8000/api/pricing"
+expect = "output contains"
+needle = "unit_price"
+```
+
+If nobody can say what command would disprove the claim, the claim was not a claim. Three expectations are supported: `exit 0`, `nonzero exit` (negative tests), and `output contains`. A claim that runs past its timeout is killed together with everything it spawned and recorded as timed out, which fails the gate.
+
+Claim commands run through your shell, in the repository root, with your privileges. Treat `claims.toml` like any other executable file in the repository: review changes to it the way you review changes to CI configuration.
+
+## Who guards the claims
+
+The agent that wrote the code can also write the claims, and the quiet way past a gate is not to fix the code but to soften the claim. Three things make that visible:
+
+- **Required claims.** `required = ["tests-pass"]` in `countersign.toml` names claim ids that must be declared. A required claim nobody wrote is recorded as `MISSING` and fails the gate, so deleting the claim is not a way out.
+- **Claims diff.** `countersign verify --claims-base origin/main` (the GitHub action does this on every pull request) compares `claims.toml` with the base branch and names every change. A removed claim, a changed expectation or a changed needle is a weakening and fails the gate (`fail_on_weakened = true`); a changed command is listed for the reviewer. `countersign claims diff --base origin/main` prints the same diff on its own.
+- **Claims from the agent's own report.** `countersign claims from-report done.md` (or `-` for standard input) turns the checkable sentences of an agent's completion message into proposed claims: "all tests pass" becomes the repository's test command, "created src/pricing.ts" becomes a file check, a URL becomes a request that must succeed. The agent's own sentence is kept as the statement, so the receipt later says which promise held. Deterministic English patterns; a sentence whose command cannot be derived from the repository is reported as unresolved, never guessed. `--write` appends them to `claims.toml`.
+- **Starter claims.** `countersign init` reads the build files that are actually there (package.json scripts, pytest or ruff configuration, go.mod, Cargo.toml) and writes a `claims.toml` with the stack's own test, lint and type-check commands, marking `tests-pass` as required. Nothing is guessed; a repository with no recognised build files gets a commented example.
+
+## The marker scan
+
+Eleven rules ported from a gate that ran daily on a production tree of more than 500 source files, reviewed file by file, with zero false positives, plus a structural check for functions whose body does nothing and explains nothing, which catches unfinished work that forgot to advertise itself. A bare `pass`, `...` or `{}` is a stub; the same body with a docstring or a comment is a documented decision (an irreversible migration's `downgrade`, a `close()` with nothing to close) and is not reported. Python is checked through the parser (overloads, abstract and Protocol methods are exempt). TypeScript and JavaScript are checked by a comment-and-string-aware scan of function declarations, class and object methods, and exported arrow functions (constructors, Angular lifecycle hooks, unexported callbacks, `.d.ts` and minified files are exempt). The eleven marker rules apply to every language in scope.
+
+Point `paths` at production source (the original gate covered `src/`, the dashboard and the clients, not seed scripts or migrations); prose about stubs in a seed script is not a stub. Test files are excluded by policy: test code legitimately fabricates data, and the receipt says so. A genuine false positive is exempted in the source itself, on the line, where a reviewer sees it. Every exemption that suppressed a finding is counted on the receipt; a marker that suppresses nothing is reported as inert so a stale one cannot hide.
+
+## Receipts, register, reproduce
+
+- Every run appends to `.countersign/register.jsonl`: an append-only, hash-chained log. Edit any earlier line and `countersign check` says so. Appends are locked, so two runs on one checkout cannot break the chain by racing.
+- What the register proves, exactly: that no entry was altered after it was written by anyone who did not also rewrite every entry after it. It lives on the machine that ran the checks, so on its own it is evidence against accident and against third parties, not against the machine's owner. Tamper evidence against the owner requires the register head to be anchored outside the machine, which is what a hosted anchoring service is for.
+- Every run writes a JSON receipt and, unless asked not to, a single-file HTML evidence pack: what was checked, how, what was found, what was not covered. The pack and the Markdown summary open with the result in plain words, written for the person who asked the agent for the feature rather than for the engineer reading the tables. Receipts name the git commit and say whether the working tree had uncommitted changes when it was scanned.
+- `countersign reproduce --run <id>` re-derives a recorded run from the same inputs and compares, result for result. The run recorded the SHA-256 of the config and claims files it read; if they changed, you are told.
+
+Exit codes: 0 countersigned or reproduced, 1 not countersigned (or the register is damaged, or the run did not reproduce), 2 usage error including a config or claims file that cannot be honoured as written, 130 interrupted.
+
+## Install and run
+
+```bash
+pip install countersign-cli
+countersign init         # writes countersign.toml, a starter claims.toml and, on GitHub, the workflow
+countersign verify       # scan + claims gate; writes receipt, pack, register
+countersign check        # the register's hash chain
+countersign reproduce --run <id>
+countersign claims diff --base origin/main
+```
+
+The user guide, with screenshots of every command and the evidence pack, is in [docs/guide.md](docs/guide.md).
+
+Requires Python 3.11+. Zero dependencies, standard library only, on purpose: it has to run inside any CI runner, any locked-down laptop, any air-gapped environment, with no supply-chain conversation. It also runs without installing: `PYTHONPATH=/path/to/countersign python3 -m countersign verify`.
+
+## CI usage (GitHub Actions)
+
+When the repository's origin is on github.com, `countersign init` also writes `.github/workflows/countersign.yml`. Commit it and push; from then on every push to the default branch and every pull request runs Countersign, and pull requests get the claims diff against their base branch. The file it writes is this:
+
+```yaml
+- uses: krishnaflipprr/countersign@v0.2
+  with:
+    config: countersign.toml
+```
+
+The action runs Countersign straight from its checkout (no pip install, nothing fetched from PyPI). The verdict lands in the job step summary; receipts upload as artifacts. Set `fail-on: warn` to record without failing. If your config moves the receipts directory, set `receipts-dir` to match. Set `attest: true` to sign the receipt with GitHub Artifact Attestations; that is free for public repositories on every plan, while private repositories need GitHub Enterprise Cloud, and the job must grant `id-token: write` and `attestations: write`. Workflows run on the account that owns the repository, on its Actions minutes.
+
+## What Countersign is not
+
+Not a security scanner, not a code review, not a statement of fitness for any purpose. It verifies declared claims deterministically and scans for unfinished-work markers. The evidence pack states its own limits on every page.
+
+## Try the demo
+
+The `demo/` directory is a small accounts service with defects planted in it: a marker comment, fabricated return data, a function that raises instead of doing work, a body that does nothing, plus one true claim and one false one.
+
+```bash
+countersign verify --config demo/countersign.toml
+```
+
+Expected outcome: NOT COUNTERSIGNED, four findings listed, the false claim caught.
+
+## Status and roadmap
+
+v0.1. Working: marker scan, structural empty-body check (Python, TypeScript, JavaScript), claims protocol with required claims and claims diff, register, receipts, evidence packs, reproduce, CI action, starter config and workflow from `init`. Next: wiring cross-checks (frontend fields against the backend endpoints that feed them), agent-report parsing (verify the claims in an agent's own completion message), public receipt badges, hosted receipt verification. The register and evidence-pack engine is shared with Gaigentic Verify, which applies it to regulated finance decisions; Countersign itself makes no regulatory claim.
+
+## License
+
+Apache License 2.0 (see LICENSE and NOTICE). The command line tool, every scan rule, the claims protocol, the register, receipts, packs and reproduce are open source in full and stay fully functional offline. Hosted anchoring, badges and organisation features are a separate service.

countersign_cli-0.2.0/countersign/__init__.py

@@ -0,0 +1,8 @@
+# audited on 20260903
+"""Countersign: deterministic verification of agent completion claims.
+
+The agent signs (claims the work is done). Countersign only countersigns
+after the claim survived deterministic checks it can re-run later.
+"""
+
+__version__ = "0.2.0"

countersign_cli-0.2.0/countersign/__main__.py

@@ -0,0 +1,4 @@
+# audited on 20260903
+from .cli import main
+
+raise SystemExit(main())