open-ready 0.1.0__py3-none-any.whl

open_ready-0.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: open-ready
+Version: 0.1.0
+Summary: Private-first project care and release-candidate preparation: inspect, prepare and verify a private Git repository for public release without shipping secrets or its development history.
+Author: Socraticblock
+License-Expression: MIT
+Project-URL: Homepage, https://socraticblock.com/work/open-ready/
+Project-URL: Repository, https://github.com/socraticblock/open-source-ready
+Project-URL: Issues, https://github.com/socraticblock/open-source-ready/issues
+Keywords: open source,release engineering,git history,secrets,privacy,ai agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Dynamic: license-file
+
+# Open-Ready
+
+**Private by default, and it refuses to publish your secrets.** Open-Ready keeps personal
+software projects private, tests and backs them up, and — only when you ask — prepares a
+release candidate that carries its own evidence and stays **unapproved** until you
+authorise one exact artifact.
+
+It is a working tool, not a manifesto. The interesting part is not what it does; it is what
+it *won't* do. There is no `publish` command, no code path that changes a repository's
+visibility, and no way for the agent using it to invent your approval. That absence is the
+product.
+
+**Who it's for.** People who let AI agents work inside their own private projects and want
+a real boundary around what can leave. You should be comfortable with a terminal, `git` and
+Python. It is opinionated — one owner, local-first, git-native — and it is not a hosted
+service.
+
+**Status:** v0.1.0-p0, early. Measured on Linux/WSL2 only, with a GitHub Actions workflow that
+runs the checks on every push and every pull request (observed passing: run `38579119769` in
+this repository — a contributor convenience, not a release gate). Read
+[Verified limitations](#verified-limitations--do-not-treat-these-as-solved) before relying
+on it.
+
+## Quickstart
+
+Requirements: Python 3.12+ and `git`. No install step, nothing to provision.
+
+```bash
+git clone https://github.com/socraticblock/open-source-ready && cd open-source-ready
+export PYTHONPATH="$PWD/src"
+
+# create a private project (scaffold, synthetic fixture, one local commit, no remote)
+python3 -m openready new --path ~/projects/example
+
+# what it found, and what it did not check
+python3 -m openready doctor --path ~/projects/example
+
+# prepare an UNAPPROVED release candidate, then verify it
+python3 -m openready candidate --path ~/projects/example --out /tmp/candidate
+python3 -m openready verify --candidate /tmp/candidate --packet /tmp/packet.json
+```
+
+Exit code `2` above is normal and correct: it means **a human decision is required**, not
+that something broke. A release packet is always `REVIEW_REQUIRED`.
+
+Two more worth knowing: `openready limits --path .` lists every control this build could
+*not* verify, with what would verify it — one command, and the honest answer to "is this
+thing actually safe?". And `openready precommit --path .` checks what a commit is about to
+add, so the cheap moment catches it rather than the expensive one.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `new --path P --project-id ID [--backup]` | **create a complete private project in one step**: scaffold, synthetic fixture, one local commit, private runtime data root outside the project, and a registration. Also installs an **advisory** commit-time control (`.githooks/pre-commit`) |
+| `init --path P --project-id ID [--git] [--adopt] [--register]` | the bare scaffolding step on its own; **refuses to create a project inside an enclosing git working tree**, and `--adopt` never commits inside an existing tree |
+| `doctor --path P [--json]` | findings, and what was not checked |
+| `fixture --path P` | write the deterministic synthetic corpus |
+| `ledger --path P [--write]` | dependency, asset and provenance inventory |
+| `candidate --path P --out D` | export an **UNAPPROVED** candidate without Git history. The history-carrying modes exist in the code but refuse from the public workflow: an artifact that carries history cannot show that an acknowledged finding was removed, because the same bytes travel either way |
+| `verify --candidate D [--packet FILE] [--no-build] [--expected-digest D]` | re-derive the digest; emit the release packet |
+| `backup --path P \| --project ID [--out F] [--verify]` | private backup, verified restore, migration drill |
+| `test --path P` | run the project's tests with a scrubbed environment |
+| `worth --path P` | private recommendation memo |
+| `update [--path P] --dry-run` | contract and policy drift; changes nothing |
+| `capabilities [--path P]` | host and fleet detection, with no network call |
+| `status [--path P \| --project ID]` | local metadata only; with neither, the **private project registry** |
+| `limits [--path P]` | the one-command honesty view: every unverified control, why, and what would verify it |
+| `precommit [--path P]` | check the **staged** content of a commit (the index blob, not the working file) and refuse a commit that would put a credential, host path, database or `.env` into history. **Advisory, not enforcement**: `git commit --no-verify` skips it |
+| `acknowledge --path P [--write --reason "…" --by "…"] [--include-tree] [--expires DATE]` | adopting a repository that already has history: **propose** one acknowledgement per **blob** that still holds a cleaned-up shape, and write nothing until asked. It proposes nothing for a finding in the working tree, because that file can be edited |
+
+### Adopting a repository that already exists
+
+Cleaning the working tree is not enough. The object store still holds what was cleaned, and
+the export refuses a candidate while any of it is unacknowledged. That is the first wall a
+real user meets, and it is invisible from this repository, which has always been clean.
+
+```
+openready init --path . --adopt --project-id <id>   # scaffold into the tree, overwriting nothing
+openready doctor --path .                            # what it found, and what it did not check
+#   fix what is in the working tree -- those files are editable and get no proposal
+openready acknowledge --path .                       # propose one entry per blob; writes nothing
+openready acknowledge --path . --write --reason "…" --by "…"
+openready candidate --path . --out ../candidate   # without history: the default, and the only public path
+openready verify --candidate ../candidate --packet packet.json
+```
+
+The export carries the file tree and nothing else. That is the only mode this workflow offers,
+and the acknowledgement above is what lets a first user reach it: the object store still holds
+what was cleaned out of the tree, and a candidate that carries no history does not need those
+bytes cleared -- it needs them not to travel, which is what excluding the history does.
+
+Two things this command will not do for you. An entry binds to the **blob** somebody looked
+at, so content committed at the same path later is still a finding — an exception is never
+allowed to grow wider than the reason for it. And the **reason** is yours: a placeholder is
+refused, because a tool cannot tell a fixture from a credential and must not pretend to.
+Measured on a real project (the engineering journal, 106 files, on a copy): 23 findings
+across 12 blobs, 14 entries, then a candidate of 115 files — byte-identical to the same
+operation with a hand-written acknowledgement file.
+
+The registry (`registry.py`) is a **metadata-only index** — project id, path, risk tier,
+creation date, whether a baseline commit exists — held in the private runtime data root,
+outside every project and outside any git working tree. It is an index, not an authority:
+the project's own contract wins, a disagreement is reported rather than resolved, and a
+registry that cannot be read is never overwritten.
+
+There is **no `publish` command**, and no code path that changes a repository's visibility.
+Publication is an owner decision bound to an exact artifact digest, made through a principal
+the builder cannot write to. To be straight about it: on a host where the agent's
+credentials could also publish, that separation is *reported* as `NOT_ENFORCED` rather than
+enforced — `docs/PUBLISHING-CREDENTIALS.md` is the recipe for making it real.
+
+Some source modules and documents here cite the specification this tool was built from —
+`docs/10-CLI-CONTRACT.md`, `02-ARCHITECTURE.md`, `06-ACCEPTANCE-TESTS.md`. Those belong to the
+original brief and are **not** in this repository, so a citation of one is a provenance note,
+not a link that resolves.
+
+## Exit codes
+
+`0` succeeded — *not* safe to publish. `1` a failure or `STOP`. `2` a required human
+decision. `3` a required check was unavailable, unenforceable or not run. `64` usage error.
+
+## Rules this build enforces in code rather than documenting
+
+- **Exit 0 never means safe.** A required check that could not run forces exit 3.
+- **A refused export writes nothing.** Every check whose failure severity is `STOP` blocks
+  the write; the destination is left untouched — a candidate that is written and then
+  criticised is a candidate that ships anyway. Included: an unreadable or only partly
+  scanned object store, an empty allowlist, a destination that already holds unrelated data,
+  and any unacknowledged history finding.
+- **"Not checked" never renders as "clean".** A scan that could not run, could not be read,
+  or hit its size bound is reported `NOT_RUN` and refuses the export, rather than reporting
+  that it found nothing.
+- **The digest covers content only.** `MANIFEST.json` and `CANDIDATE.json` describe the
+  candidate and are not part of its identity, so a stranger can recompute the digest from the
+  files alone. The two records must agree, and `verify` fails if they do not.
+- **Acknowledgements cannot be silent, and they name exact bytes.** Naming a false positive
+  requires a check id, an exact path, a real reason, who acknowledged it and when; entries
+  expire; and every applied entry is re-reported on every run. An entry binds to the content
+  id (git's blob id) of what was looked at, so it covers those bytes and nothing else — a
+  fixture's exception cannot hide a credential committed into the same file later.
+- **Rights are never reported as `PASS`.** Ownership cannot be established by a scan, so the
+  packet always carries `rights: NOT_RUN` rather than inventing a fact. The same applies to
+  dependency ecosystems this build does not parse: an unread `Cargo.toml` is `NOT_RUN`, never
+  "no dependencies".
+- **A dependency is a licence obligation.** Unknown licences and copyleft are human review
+  items, not conclusions. This tool does not provide legal advice and does not determine
+  compatibility.
+
+## Tests
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests          # 357 tests, stdlib only
+env -i PATH=/usr/bin:/bin HOME=$(mktemp -d) LANG=C.UTF-8 TMPDIR=$TMPDIR \
+    PYTHONPATH=src python3 -m unittest discover -s tests      # same suite, scrubbed
+```
+
+Both must pass. The second is not a formality: `verify` runs a candidate's tests in an
+environment with only `PATH`, a throwaway `HOME`, `LANG` and `TMPDIR`, and six tests in this
+repository used to pass only because the developer's `~/.gitconfig` supplied an author
+identity. A suite that needs the author's machine is not evidence about the tool.
+
+Also in the repo: `acceptance/` measures 33 end-to-end requirements (A01–A33) by driving the
+CLI as a subprocess, and `acceptance/gates.py` regenerates `docs/P0-GATE.md` …
+`docs/P4-GATE.md` from real runs.
+
+## Verified limitations — do not treat these as solved
+
+- Every scanner here is a **deny-list**. It can prove it found something, never that nothing
+  exists.
+- Arbitrary private **prose** is undetectable by pattern scanning; that check is `NOT_RUN`
+  forever.
+- **Network egress is not contained.** A restricted build passing here is not evidence it
+  works offline.
+- **Publisher separation is `NOT_ENFORCED`** on a host where the builder's credential can
+  also publish, so a release packet is always `REVIEW_REQUIRED`. See
+  `docs/PUBLISHING-CREDENTIALS.md`.
+- No secret-scanner binary is installed, so the deny-list is the whole check. It is a set of
+  patterns: a credential in a shape none of them describes is not detected.
+- **History scanning is bounded** at 4 MiB per object. Objects above the bound are not read,
+  and the tool refuses to export rather than reporting a clean scan over them. It enumerates
+  every ref in the object store, so a fetched branch counts.
+- `doctor` makes no network call and therefore cannot tell you whether a remote repository is
+  public.
+- One operating system has been measured (linux-x86_64). No cross-platform claim is made.
+
+## Design decisions
+
+`docs/adr/` records them, each with its reason and its consequences — including the three
+from the last pass: an acknowledgement binds to an object, the acceptance record redacts
+itself and is not written if it cannot pass, and detectable test fixtures are assembled at
+run time so the repository can pass the very gate it ships.
+
+## Licence
+
+MIT — see `LICENSE`.
+
+Maintained by **Jeff Vandervelde** · [socraticblock.com](https://socraticblock.com) · also
+known as `socraticblock`.

open_ready-0.1.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+open_ready-0.1.0.dist-info/licenses/LICENSE,sha256=wbtSyemPsX9eThpSg8Z8HQ7A_Ja7bcxnVDJKA-97JwI,1089
+openready/__init__.py,sha256=Wf9S9ezrp0TZ50h7iJKn5bPtWmPmbX3lm3eWqNkyS6Q,692
+openready/__main__.py,sha256=KTrSspqg95pipAD93bTWZhu8l9ni9rJ1USb_1hI-_hQ,124
+openready/acknowledge.py,sha256=C-28i2O404jev_Kj6qTMkgv22z30gR_PjJYVzdfgIdI,13357
+openready/advisory.py,sha256=2lQClhTgXR6ScHD-NooiTfO9AjJA6zEJehukdkZGkQQ,8842
+openready/audit.py,sha256=LpqUldhcEsRtIkP3sW8_G6UG2MPZ_Es-oqrsAmSgz2E,22624
+openready/backup.py,sha256=9mc03aM0cCvztgtwiIp7yu9dNb9DIy357eRMbAtP7j0,24443
+openready/candidate.py,sha256=4hRP75C4ToiiovrbxmeY7Lyd3YCDavl3ZuvjPb-OaCE,43918
+openready/capabilities.py,sha256=AMuNnPKn9yode_yrzT3iLCdqUdmNHQG2yHjkssDDcxA,13459
+openready/cli.py,sha256=HYBAY2-smGg7kmM0rDurx_xzJBq0fQ56qw51y-AHqg0,37030
+openready/contracts.py,sha256=d-z_GI-hAmJ0ZR5VAV57WRHNgMydIk6u8V1jrvPWdNs,7507
+openready/doctor.py,sha256=hRyW3ilZww9inQOVqr3y2-SJD8DpbhL7AEJDYGlICzM,15056
+openready/external.py,sha256=gXL8HHUfUqYe60vL9lv0to_g96yuNShxDtZQsQ-4K9k,5957
+openready/feature.py,sha256=zsV5l6BzfXw7zLh3py1MSciTblXh1GbelxMvGhtv56o,13065
+openready/history.py,sha256=7SFxjKl1mhWIxTsPoP5nBCqcSNp1mlFTKR8h4uE1tJk,14893
+openready/intake.py,sha256=yZaL7JxPvC76yKpZATmc9NlKPlv0nlUSWndua4Eho-I,10910
+openready/ledger.py,sha256=FbGVRHo9vIVkd0nA2MsC9brBcY7xf1QeDmOWNFY7nvM,26210
+openready/limits.py,sha256=FJgHvxlZjTcZPiyqipkEqFqZhQe9R5p2mP_H3slm-eU,38890
+openready/migrate.py,sha256=fenHTDsnwKNoyiK8NikAd5qdQhAmaE7-QTK2ymzzBVs,7598
+openready/overrides.py,sha256=Hc3-epIItA1CF3a9Akws3mNpp2V8ba8fllCSpLRPz4o,12018
+openready/policy.py,sha256=FQB3Wv2dADh8-qJmYQsUFCGAuFDThDdsWkJVN1JZk8U,31152
+openready/private.py,sha256=mfMfuArEIrcUxS10BedUSY_3__B_QAT9XyywSZT4Fe4,8948
+openready/project.py,sha256=QN4ZRud60lWyaFI1qQL1Q7yVkZGRd9KuUImZpFLqAYk,27336
+openready/promote.py,sha256=AEb-mka7lPWIIGMz2JNUu2_6Cm_0jiD1lBXjZfq6928,13543
+openready/providers.py,sha256=lifopqqXJeTtIROqNp1-I4hDi2xw1QFHi5x2fsOGKRc,11319
+openready/publisher.py,sha256=stjvq0W8XytTlddfoa8OjBy23G7MJHGMex8A7biyD2g,29687
+openready/registry.py,sha256=4fPv7XoEz0kwWDNV6GtQv369V0GchSVvPcPoccwtOtU,8847
+openready/scan.py,sha256=LYpjvI3B56gsRBIGqd2GgFUx7alGjP-6RCecg6RrrI8,28548
+openready/staged.py,sha256=jgtFwAM8Dpt35tNjShwjx91IwWIilS_f5ukIXmcDYvs,9966
+openready/status.py,sha256=JTXM7vyTYhN2hEkplqXZF2Awf_xQF_JRwnKuv_-6ZOA,5078
+openready/templates.py,sha256=nmhiaofPY7QTehQCXFhLwF_hDTHMGRnluehxO7Ec8po,25301
+openready/verify.py,sha256=dBVrEKX7SDfaOS9gYAueEd9LINX50JYDSWCC7KiGSvw,32391
+openready/contracts/project.schema.json,sha256=vrpPddsd6cmTb3NNGYx5KcV77g3-pInX_8uYc-B5qo4,1539
+openready/contracts/release-packet.schema.json,sha256=rqFgi5kb9t3noKcA0aLIC8gP2Ry0swo8XXCV6aAj750,3507
+openready/contracts/result.schema.json,sha256=5fUzFnWPIPD28SJ38dM0X8zIw1slDAjsPIBpMFgdWZ4,1440
+open_ready-0.1.0.dist-info/METADATA,sha256=8QDMfgqubEC2D_U1bz-xx-Ya8t9H4xAYnyswsFNvJ_Y,13677
+open_ready-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+open_ready-0.1.0.dist-info/entry_points.txt,sha256=o_5S43XiBhRc2cke1qKzIJthOYwuXNjsRF4Egl7dOPM,49
+open_ready-0.1.0.dist-info/top_level.txt,sha256=Uilap_ULK8-jSipOPRlDE0CJu_UGHp1Y4FHKPWMm_7s,10
+open_ready-0.1.0.dist-info/RECORD,,

open_ready-0.1.0.dist-info/WHEEL

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

open_ready-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openready = openready.cli:main

open_ready-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Vandervelde (socraticblock)
+
+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.

open_ready-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openready

openready/__init__.py

@@ -0,0 +1,15 @@
+"""Open-Ready -- private-first project care and release-candidate preparation.
+
+Specification: "Open-Ready definitive agent handoff v1.0". This package implements
+the P0 foundation: versioned contracts, honest capability detection, private
+project initialisation, and a ``doctor`` that reports what it did not check.
+
+Governing rule, stated once here and enforced in code: a run that contains a
+required unrun, unenforced or untested check is **never** reported as green.
+"""
+
+__version__ = "0.1.0-p0"
+POLICY_VERSION = "1.0"
+
+# The wording every surface must use. There is no safe-to-publish state.
+PUBLICATION_STATUS = "NOT APPROVED -- requires separate owner review of the exact candidate"

openready/__main__.py

@@ -0,0 +1,6 @@
+"""``python3 -m openready`` entry point."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

openready/acknowledge.py

@@ -0,0 +1,318 @@
+"""The adoption path for a repository that already exists.
+
+A repository that has been carrying code for a while cannot produce a candidate even
+after its working tree is clean, because its **history** still holds what was cleaned.
+Every blob that ever contained the shape is still in the object store, and the export
+refuses to write a candidate while an unacknowledged hit is there. This is the first
+wall a real user meets, and it is invisible from this tool's own repository, which has
+always been clean.
+
+Two different problems, and the tool must not answer them the same way:
+
+* A finding in the **working tree** is fixable by editing the file. Acknowledging it
+  would be an exception *wider than the reason for it* -- one path, every shape at that
+  path, until it expires -- and an unnecessary one. So this command names those findings
+  and proposes nothing for them. ``--include-tree`` exists for the case where the shape
+  genuinely has to stay, and it says in the entry's own limitations that the exception is
+  the wide kind.
+* A finding in the **object store** cannot be fixed without rewriting history, which is
+  the owner's decision and not this tool's. So one entry per **blob**: the exact bytes
+  somebody looked at, not that path forever. Content committed at the same path later is
+  still a finding.
+
+Writing is a separate, explicit act (``--write --reason ... --by ...``). The tool cannot
+know that a shape is a fixture; only a human can say so, so it will not say it for them.
+Without ``--write`` this command prints what it would record and changes nothing.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from . import __version__
+from .candidate import inspect as inspect_tree, plan as plan_candidate
+from .history import (
+    findings as history_findings,
+    is_repository,
+    scan as history_scan,
+    scanned_completely,
+)
+from .overrides import (
+    ALLOW_NAME,
+    MIN_REASON_CHARS,
+    OVERRIDABLE_CHECK_IDS,
+    PLACEHOLDER_REASONS,
+    apply as apply_overrides,
+    load as load_allow,
+)
+from .status import (
+    FAIL,
+    INFO,
+    NEEDS_HUMAN,
+    NOT_RUN,
+    PASS,
+    REVIEW,
+    Result,
+)
+
+def _environment_label() -> str:
+    import os
+    return f"{os.uname().sysname.lower()}-{os.uname().machine}"
+
+
+def _result(check_id: str, status: str, message: str, *, severity: str = REVIEW,
+            required: bool = False, limitations: Optional[List[str]] = None) -> Result:
+    return Result(check_id, status, severity, message, __version__, _environment_label(),
+                  required=required, limitations=limitations or [])
+
+
+def _default_by() -> str:
+    """Who is acknowledging, for the entry to carry as evidence.
+
+    Built from ``os`` and ``getpass`` only. The standard-library calls that look this host
+    up are tokens A01 scans this tool's own source for, and a label is not worth a hole in
+    a check about not reaching the network -- the name comes from the uname structure.
+    """
+    import getpass
+    import os
+    try:
+        who = getpass.getuser()
+    except Exception:  # pragma: no cover - no passwd entry
+        who = "unknown"
+    host = (os.uname().nodename or "unknown-host").split(".")[0]
+    return f"{who}@{host}"
+
+
+def reason_errors(reason: str) -> List[str]:
+    """Whether a reason is usable as somebody's statement about their own project."""
+    text = str(reason or "").strip()
+    if text.lower() in PLACEHOLDER_REASONS:
+        return ["a reason is required: it is the operator's statement, not the tool's"]
+    if len(text) < MIN_REASON_CHARS:
+        return [f"the reason must be at least {MIN_REASON_CHARS} characters"]
+    return []
+
+
+def residue(root: Path) -> Tuple[List, Optional[str]]:
+    """Unacknowledged object-store findings, or why they could not be judged.
+
+    The second element is set when the scan did not complete: a partial scan must never
+    be turned into "nothing to acknowledge", because that would acknowledge an
+    unexamined history by omission.
+    """
+    root = Path(root)
+    if not is_repository(root):
+        return [], ""
+    report = history_scan(root)
+    complete, why = scanned_completely(report)
+    if not complete:
+        return [], why
+    hits = history_findings(report)
+    if not hits:
+        return [], ""
+    # Already-acknowledged blobs are not residue. Without this the command proposed an
+    # entry for every hit it found, including the ones an earlier run had already
+    # recorded, and re-running it grew the file with duplicates of its own output.
+    remaining, _ = apply_overrides(root, hits)
+    return remaining, ""
+
+
+def tree_findings(root: Path) -> List:
+    """Unacknowledged findings in the working tree, which the operator can just fix."""
+    plan = plan_candidate(Path(root))
+    paths = list(plan.get("included", [])) + list(plan.get("untracked", []))
+    if not paths:
+        return []
+    remaining, _ = apply_overrides(Path(root), inspect_tree(Path(root), paths))
+    return [item for item in remaining
+            if getattr(item, "check_id", "") in OVERRIDABLE_CHECK_IDS]
+
+
+def proposal(findings: Sequence, reason: str, by: str, expires: str = "",
+             bind_objects: bool = True) -> List[Dict[str, Any]]:
+    """One entry per finding, object-bound when the finding came from the object store."""
+    seen: Dict[Tuple[str, str, str], Dict[str, Any]] = {}
+    for finding in findings:
+        check_id = str(getattr(finding, "check_id", ""))
+        path = str(getattr(finding, "path", ""))
+        if check_id not in OVERRIDABLE_CHECK_IDS or not path:
+            continue
+        obj = str(getattr(finding, "object_id", "") or "") if bind_objects else ""
+        entry: Dict[str, Any] = {
+            "check_id": check_id,
+            "path": path,
+            "reason": reason,
+            "acknowledged_by": by,
+            "acknowledged_at": date.today().isoformat(),
+        }
+        if obj:
+            entry["object"] = obj
+        if expires:
+            entry["expires"] = expires
+        seen[(check_id, path, obj)] = entry
+    return [seen[key] for key in sorted(seen)]
+
+
+def existing_entries(root: Path) -> List[Dict[str, Any]]:
+    document, _ = load_allow(Path(root))
+    entries = (document or {}).get("entries", []) if document else []
+    return [entry for entry in entries or [] if isinstance(entry, dict)]
+
+
+def write(root: Path, entries: Sequence[Dict[str, Any]]) -> Path:
+    """Merge entries into the acknowledgement file, keeping the existing ones.
+
+    Rewriting the file from the proposal alone would silently delete every earlier
+    acknowledgement, which is the sort of quiet data loss an evidence tool cannot afford.
+    """
+    import json
+    root = Path(root)
+    path = root / ALLOW_NAME
+    document, _ = load_allow(root)
+    document = document or {}
+    kept = [entry for entry in document.get("entries", []) or [] if isinstance(entry, dict)]
+    keyed = {(str(e.get("check_id", "")), str(e.get("path", "")), str(e.get("object", "") or "")): e
+             for e in kept}
+    for entry in entries:
+        keyed[(str(entry["check_id"]), str(entry["path"]), str(entry.get("object", "") or ""))] = entry
+    merged = [keyed[key] for key in sorted(keyed)]
+    document["entries"] = merged
+    path.write_text(json.dumps(document, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+    return path
+
+
+def run(root: Path, *, reason: str = "", by: str = "", expires: str = "", write_it: bool = False,
+        include_tree: bool = False) -> Tuple[List[Result], Dict[str, Any]]:
+    """Propose, or record, the acknowledgements that adoption needs."""
+    root = Path(root)
+    results: List[Result] = []
+    payload: Dict[str, Any] = {}
+
+    stored, why = residue(root)
+    tree = tree_findings(root) if include_tree else []
+    fixable = [] if include_tree else tree_findings(root)
+
+    payload["object_residue"] = len(stored)
+    payload["tree_findings"] = len(fixable) + len(tree)
+
+    if why:
+        results.append(_result(
+            "acknowledge.scan-incomplete", NOT_RUN,
+            f"the object store could not be scanned completely, so no acknowledgement is "
+            f"proposed: {why}",
+            severity=REVIEW, required=True,
+            limitations=[
+                "A partial scan is not a clean one. Acknowledging here would exempt the "
+                "part that was never read.",
+                "Raise the blob limit or run the scan where the object store is fully "
+                "readable, then propose again.",
+            ],
+        ))
+        return results, payload
+
+    if not stored and not tree:
+        results.append(_result(
+            "acknowledge.nothing", PASS,
+            "nothing to acknowledge: no unacknowledged finding in the object store or the "
+            "working tree is of an overridable kind",
+            severity=INFO,
+            limitations=[
+                "This says nothing about findings that are not overridable. Those are "
+                "reported by doctor and candidate and need a human decision, not an "
+                "acknowledgement.",
+            ],
+        ))
+        return results, payload
+
+    proposed = proposal(stored, reason or "<your reason here>", by or _default_by(), expires)
+    if tree:
+        proposed += proposal(tree, reason or "<your reason here>", by or _default_by(), expires,
+                             bind_objects=False)
+
+    objects = {str(getattr(item, "object_id", "") or "") for item in stored}
+    objects.discard("")
+    payload["proposal"] = proposed
+    payload["would_write"] = ALLOW_NAME
+
+    if stored:
+        results.append(_result(
+            "acknowledge.object-residue", NEEDS_HUMAN,
+            f"{len(stored)} unacknowledged finding(s) in {len(objects)} object(s) in the "
+            f"store, from commits that predate this cleanup -- your history, not your "
+            f"working tree",
+            severity=REVIEW, required=True,
+            limitations=[
+                "One entry per blob covers the exact bytes somebody looked at. Content "
+                "committed at the same path later is still reported.",
+                "These are in history. Fixing them means rewriting history, which is the "
+                "owner's decision, not this tool's.",
+            ],
+        ))
+    if fixable:
+        results.append(_result(
+            "acknowledge.tree-findings", NEEDS_HUMAN,
+            f"{len(fixable)} finding(s) are in the working tree, where you can fix them: "
+            + "; ".join(sorted({f"{item.path} ({item.check_id})" for item in fixable})[:6]),
+            severity=REVIEW, required=True,
+            limitations=[
+                "No acknowledgement is proposed for these. An exception at a path is "
+                "wider than the reason for it, and editing the file costs less.",
+                "Pass --include-tree to acknowledge them anyway, if the shape has to stay.",
+            ],
+        ))
+    if tree and include_tree:
+        results.append(_result(
+            "acknowledge.tree-acknowledged", NEEDS_HUMAN,
+            f"{len(tree)} working-tree finding(s) are included in the proposal as "
+            f"path-bound entries",
+            severity=REVIEW, required=True,
+            limitations=[
+                "A path-bound entry covers every shape at that path until it expires, "
+                "including a real credential committed there later.",
+            ],
+        ))
+
+    if not write_it:
+        results.append(_result(
+            "acknowledge.nothing-written", PASS,
+            "nothing was written. This command proposes; recording is a separate act "
+            "(add --write --reason \"...\" --by \"...\")",
+            severity=INFO, required=False,
+        ))
+        return results, payload
+
+    problems = reason_errors(reason)
+    if not proposed:
+        problems.append("no entry was proposed to write")
+    if problems:
+        results.append(_result(
+            "acknowledge.refused", FAIL,
+            "nothing was written: " + "; ".join(problems),
+            severity="STOP", required=True,
+            limitations=[
+                "The reason is the operator's own statement about their project. The tool "
+                "cannot tell a fixture from a credential, so it will not write one for you.",
+            ],
+        ))
+        return results, payload
+
+    path = write(root, proposed)
+    # The residue result described the state *before* the write. Leaving it in place made
+    # a successful run report the findings it had just acknowledged as unacknowledged.
+    results = [item for item in results if item.check_id != "acknowledge.object-residue"]
+    results.append(_result(
+        "acknowledge.written", PASS,
+        f"recorded {len(proposed)} entr(y/ies) in {path.name}, covering {len(stored)} "
+        f"finding(s) in {len(objects)} object(s); the findings they name are now "
+        f"acknowledged, and nothing else is",
+        severity=INFO,
+        limitations=[
+            "An acknowledgement says 'I know about this one'. It says nothing about "
+            "whether this project may be published.",
+            f"Entries that name a blob cover that blob. Re-run candidate with "
+            f"--history squash to export a tree that carries none of it.",
+        ],
+    ))
+    return results, payload