Add StewardCheck: task-scoped change receipts for coding workflows

.github/workflows/stewardcheck.yml

@@ -0,0 +1,47 @@
+name: StewardCheck
+
+on:
+  push:
+    paths:
+      - 'tools/stewardcheck/**'
+      - '.github/workflows/stewardcheck.yml'
+  pull_request:
+    paths:
+      - 'tools/stewardcheck/**'
+      - '.github/workflows/stewardcheck.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ['3.11', '3.12', '3.13', '3.14']
+        include:
+          - os: macos-latest
+            python: '3.13'
+          - os: windows-latest
+            python: '3.13'
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install package
+        run: python -m pip install ./tools/stewardcheck
+      - name: Unit and integration tests
+        run: python -m unittest discover -s tools/stewardcheck/tests -v
+      - name: Module and console entrypoints
+        run: |
+          python -m stewardcheck --version
+          stewardcheck --help
+      - name: Isolated end-to-end demonstration
+        run: python tools/stewardcheck/examples/demo.py

tools/stewardcheck/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.coverage*
+htmlcov/
+coverage.json

tools/stewardcheck/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 — 2026-09-30
+
+Initial alpha release of the independent StewardCheck package.
+
+- Task-start working-tree baselines, explicit path contracts, protected paths, and file-count budgets.
+- Bounded, whole-file context packets with sensitive-path exclusion and heuristic redaction.
+- Static findings for newly detected secrets, test weakening, opaque content, and partial staging.
+- Opt-in argv checks with time/output limits and workspace-bound, freshness-checked receipts.
+- JSON and Markdown output, a prerequisite inspector, regression tests, and a temporary-repository demo.
+- English and Simplified Chinese guides, a threat model, and a documented reference survey.
+
+The receipt schema and Python API are provisional in 0.x. This release does not add provider integrations, automatic edits, rollback, hooks, cryptographic attestation, or a sandbox.

tools/stewardcheck/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Keep StewardCheck small, explicit, and usable without a model service. Changes should preserve task-start baselines, non-destructive inspection, honest non-passing states, and a narrow dependency surface.
+
+## Local development
+
+From `tools/stewardcheck` in an activated Python 3.11+ virtual environment:
+
+```sh
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python examples/demo.py
+```
+
+Tests create temporary Git repositories, synthetic credentials, and short-lived subprocesses. They do not use model APIs or real credentials. Optional coverage measurement:
+
+```sh
+python -m pip install coverage
+python -m coverage run -m unittest discover -s tests
+python -m coverage report
+```
+
+Coverage is a development dependency only. A high percentage does not establish correctness or platform compatibility.
+
+## Pull requests
+
+Include the problem, a regression test, user-visible behavior, and any compatibility/security impact. Keep English and Chinese README behavior descriptions aligned. Reference external designs or specifications in `docs/research.md` and update `THIRD_PARTY.md` if third-party code or dependencies are introduced. Do not import upstream source or rule catalogs without checking their license and preserving required notices.
+
+Avoid network calls, automatic edits, automatic command approval, or new persistent planning files in the default workflow. Use the existing issue and pull request for design discussion. A new warning should explain what requires human review; a new blocker should be testable without claiming semantic certainty.
+
+## Release checklist
+
+Run the complete tests, the temporary-repository demo, and a wheel install in a clean virtual environment. Check CLI help, console and module entrypoints, package version consistency, relative documentation links, included licenses, and source-distribution contents. Confirm the CI matrix rather than assuming local Linux results prove Windows or macOS compatibility. Record measured results, unresolved platform failures, and known limitations. Never present an unrun job as passing.
+
+The initial 0.x Python API and receipt schema are provisional. Document incompatible changes in `CHANGELOG.md`; avoid silently trusting task records created by an incompatible schema. Publish source with reviewable commits. The package directory is independently installable and can be moved into a dedicated repository without depending on parent-repository scripts.

tools/stewardcheck/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afloat16
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tools/stewardcheck/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md README.zh-CN.md SECURITY.md THIRD_PARTY.md CONTRIBUTING.md CHANGELOG.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py

tools/stewardcheck/README.md

@@ -0,0 +1,139 @@
+# StewardCheck
+
+**Keep the coding flow. Check the change.**
+
+**English** | [简体中文](README.zh-CN.md)
+
+StewardCheck is a small, local CLI for LLM coding and vibecoding workflows. Capture a task's starting point, give your coding assistant a bounded context packet, and get a reviewable receipt of what changed and which checks actually ran.
+
+It complements your existing editor or coding agent. There is no model account, API key, server, runtime Python dependency, or automatic source editing.
+
+**0.1.0 · Alpha · Python 3.11+ · Git · MIT**
+
+## Why use it?
+
+A successful test command is not the whole story. Was an unrelated file changed? Were existing tests weakened? Does the test result still describe the files on disk? Did the task start with your own uncommitted work?
+
+StewardCheck connects those questions to one explicit task contract and one local receipt:
+
+| Need | Behavior |
+| --- | --- |
+| Keep changes focused | Allowed path globs, protected paths, and a changed-file budget. |
+| Preserve existing work | Compare with the actual task-start working tree, including dirty and non-ignored untracked files—not only `HEAD`. No automatic rollback. |
+| Share useful context | Whole-file Markdown packet with a strict byte budget, sensitive-path exclusion, and heuristic redaction. |
+| Make checks accountable | Execute only the argv declared at task start, and only with `check --run`. Bind results to workspace, index, and HEAD fingerprints. |
+| Avoid stale confidence | Detect changes during checks and after a receipt. Missing checks and review warnings do not produce a green verdict. |
+| Catch common review hazards | Newly detected credential patterns, deleted tests, fewer assertion markers, additional skip markers, and partial staging. |
+
+This is a **working-tree task review**, not a staged-only commit gate, semantic code reviewer, sandbox, backup system, or security certification.
+
+## Install
+
+With [pipx](https://pipx.pypa.io/stable/), install the package from this repository:
+
+```sh
+pipx install "git+https://github.com/Afloat16/ai-dev-steward.git#subdirectory=tools/stewardcheck"
+stewardcheck --version
+```
+
+Alternatively, clone the repository and install `tools/stewardcheck` with `python -m pip install ./tools/stewardcheck` inside an activated virtual environment. This package is independent of the parent repository's agent skill. The documented installation uses Git; no PyPI publication is assumed.
+
+## A small workflow
+
+Run from the Git repository you want to work on. This example assumes a Python project using `unittest`; choose your project's real test command.
+
+```sh
+stewardcheck start "Fix empty-input handling" \
+  --scope "src/**" --scope "tests/**" \
+  --check "python -m unittest discover -s tests" \
+  --accept "Empty input returns an empty result without changing existing behavior"
+
+stewardcheck packet
+```
+
+Review the packet, then paste it into your coding assistant. Ask it to implement the task within the declared scope. The packet is printed locally; StewardCheck never sends it to a model.
+
+After reviewing the edits and the declared command:
+
+```sh
+stewardcheck check --run
+stewardcheck report --format json
+```
+
+A passing check means the declared commands exited successfully and no implemented rule requires review. It does **not** mean the human acceptance criteria were proven. Those remain explicitly unchecked in the receipt.
+
+For an entirely self-contained demonstration after cloning and installing:
+
+```sh
+python tools/stewardcheck/examples/demo.py
+```
+
+The demo uses a temporary Git repository and real subprocess checks. It demonstrates a passing fix, a stale receipt, and an out-of-scope blocker without modifying your current project.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `start "task"` | Capture the task contract and actual working-tree baseline. |
+| `packet` | Print a bounded context packet. Default maximum: 32,000 UTF-8 bytes. |
+| `check` | Inspect the task delta without running declared commands. |
+| `check --run` | Inspect the delta and explicitly execute the pinned checks when there are no static blockers. |
+| `report` | Print the latest receipt and detect whether it is stale; never rerun commands. |
+| `doctor` | Inspect prerequisites and suggest possible check commands without executing them. |
+
+Every subcommand accepts `--root PATH`. `check` and `report` accept `--format markdown` or `--format json`.
+
+### Scope and context are different
+
+`--scope` is repeatable and controls which files may change. Without it, scope is `**` and the receipt explicitly notes that paths are unrestricted. Globs are relative to the repository root and case-sensitive: `*` stays within one path segment; `**` crosses directories and may match zero segments. Negative patterns and absolute paths are not supported.
+
+`packet --include "docs/**"` adds read-only context without expanding the allowed edit scope. `--max-bytes` changes the packet budget; this is a byte limit, **not a model-specific token estimate**. Whole files that do not fit are omitted rather than silently cut in half. Inspect the packet before sharing it, especially outside your organization. Keep any redirected packet or receipt outside the repository being checked, otherwise that new output file can itself become a task change.
+
+### Checks are explicit programs, not shell snippets
+
+Repeat `--check` for multiple commands. Its quoting is POSIX-style on every platform; pipes, redirection, and standalone shell operators are rejected. For exact or Windows-specific arguments, use an argv array:
+
+```sh
+stewardcheck start "Fix parsing" --scope "src/**" \
+  --check-json '["python", "-m", "pytest", "-q"]'
+```
+
+Adapt outer quoting to your shell. Checks run from the repository root as your current user, inherit your environment, and are **not sandboxed**. They can execute project code, access credentials, change files, and use the network. Do not run untrusted checks. Do not put credentials in argv: the exact command contract is stored locally. On Windows, direct `.bat`/`.cmd` execution is refused; invoke a trusted interpreter and its script explicitly instead. For example, use `node` with the reviewed JavaScript test runner rather than `npm.cmd`.
+
+The default timeout is 120 seconds per command; set `--timeout` at task start. Command output is redacted heuristically and bounded; over-limit or timed-out commands cannot pass. A formatter or test that changes monitored content invalidates the checked state: review the change, then rerun.
+
+### Protection and task lifecycle
+
+Default protected paths include environment files, PEM/key files, SSH private-key filenames, `.netrc`, Git ignore/attribute rules, `.gitmodules`, and `.github/workflows/**`. A task needing to modify one of these requires an explicit policy choice. **Supplying `--protect` replaces the default protected list**; it is not additive. Review the complete replacement list carefully.
+
+`--max-files` defaults to 20. Snapshots hash at most 256 MiB by default (`--scan-mib`), with a hard 20,000-path ceiling. UTF-8 text scanning is limited to 256 KiB per file; changed binary, oversized, or linked content requires separate review. Exceeding a resource limit is an operational error, not a pass.
+
+There is one active task per Git working tree. Use `start ... --replace` only when deliberately discarding the previous baseline and receipt. There is no automatic task history or recovery copy. Normal and linked Git worktrees use their own Git metadata directory.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Passed: declared checks ran successfully, no blocking or review-level findings. |
+| `1` | Blocked: policy violation, failed check, or changed state during checks. |
+| `2` | Needs review: missing/unrun checks, heuristic warnings, stale evidence, or no task changes. |
+| `3` | Operational error: invalid task state, Git failure, or resource limit. |
+| `130` | Interrupted. Rerun before relying on a receipt. |
+
+Argument syntax errors are reported by Python's argument parser with exit code `2` and no receipt. Treat any nonzero exit as non-passing in automation.
+
+## Privacy and boundaries
+
+State lives in `<git-dir>/stewardcheck/active.json`. It contains task text, paths, content hashes, derived metrics, the exact declared argv, and bounded redacted check output—not copies of source files. POSIX state files are created with restrictive permissions. Git-based discovery respects ignored untracked paths; tracked files remain monitored even when matched by ignore rules, and known baseline paths are retained when ignore rules change.
+
+Ignored untracked files, nested repository/submodule interiors, Git-unlisted special files, external dependencies, and transient changes between snapshots are not comprehensively monitored. Static checks are heuristics: both false positives and false negatives are possible. Hashes detect accidental stale or damaged records, not tampering by another process with the same permissions. Built-in redaction does not replace a dedicated scanner such as [Gitleaks](https://github.com/gitleaks/gitleaks).
+
+See [SECURITY.md](SECURITY.md) for the threat model and platform limits, and [docs/architecture.md](docs/architecture.md) for data flow and receipt semantics.
+
+## Development and references
+
+Run `python -m unittest discover -s tests -v` from this package after installing it. Development details and the release checklist are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+The design survey covers Repomix, Gitingest, Aider, Cline, OpenHands, Gitleaks, pre-commit, and official Git/Python documentation. [Research and tradeoffs](docs/research.md) records sources, the observed popularity snapshot, design decisions, and evidence limits. [THIRD_PARTY.md](THIRD_PARTY.md) distinguishes conceptual references from dependencies and copied material. No upstream implementation or rule catalog is vendored.
+
+StewardCheck is licensed under [MIT](LICENSE). This license applies to this package directory, not unrelated material elsewhere in the parent repository.