Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion ADOPTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,23 @@ check. Durable truth still starts only after the consumer commits and admits
## First Adoption Loop

Proofkit can reduce initial adoption glue, but it must not turn observation into
truth. The first loop is:
truth. Start with one explicit trust intent:

```bash
npm exec --offline -- agentic-proofkit adopt plan --mode fresh --repo-root .
npm exec --offline -- agentic-proofkit adopt plan --mode code-baseline --repo-root .
npm exec --offline -- agentic-proofkit adopt plan --mode audit-from-code --repo-root .
```

The command validates its arguments before filesystem access, scans only a
fixed catalog of recognized files at the selected root, and emits a
candidate-only task sequence plus a compact reference to the native-evidence
guidance owner. It does not parse those files, infer a stack, inspect arbitrary
source code, generate product requirements, write files, or run witnesses.
An optional `--stack <preset-id>` records a caller-selected suggestion and
cannot alter source trust or task semantics.

Continue the first loop as follows:

```text
caller-owned capability or test observations
Expand Down
2 changes: 2 additions & 0 deletions BACKLOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,3 +56,5 @@ records, generated release manifests, or the owning docs named above.
| BLOCKED | RELOCATION-01 | Add provenance-bounded witness relocation candidates without introducing a second binding path or trusting a caller-authored prior digest; detailed candidate contract is retained in [issue #66](https://github.com/research-engineering/agentic-proofkit/issues/66). | An owner-admitted content-addressed baseline binds witness id, prior path and digest, source revision, evidence class, authentication non-claims, and freshness non-claims; the scanner then proves the zero/one/many match partition while remaining non-current until fresh execution evidence exists. |
| BLOCKED | RELEASE-01 | Prove signed protected-tag release policy as provider-side release governance, not source-only intent. | Repository tag protection/ruleset and release workflow variables require signed annotated release tags; the next public release records provider-side evidence or the row is explicitly retired as an accepted non-claim. |
| BLOCKED | RELEASE-02 | Retire the inaccurate PyPI `0.1.159` wheel compatibility and license projection without mutating immutable release history. | After a public replacement release proves that each advertised macOS wheel minimum is no lower than its embedded Mach-O minimum, embedded MIT license identity, npm/PyPI/GitHub byte closure, and installed-package smoke, yank PyPI `0.1.159` with an exact compatibility-and-license reason and retain provider evidence of the yank. |
| DEFERRED | INSTALLED-CONSUMER-01 | Evaluate one carrier-neutral installed-contract and route-verification protocol without merging npm process transport with Python module transport. | Exact npm and wheel decision tables plus a shared mutant corpus first prove behavioral equivalence for contract admission, route/help identity, and byte-bound carrier checks; extract only the proven common protocol while retaining carrier-specific installation and execution owners, or retire the row if the common layer does not reduce semantic duplication. |
| DEFERRED | CLI-ARGS-01 | Evaluate one immutable typed parse result between descriptor admission and command execution instead of independently interpreting already-admitted command operands. | A reproducible descriptor-versus-handler drift falsifier establishes the defect class; a bounded prototype proves exact flag, multiplicity, value, help, input, and presentation parity across every affected command with no new ambient authority or generic option bag; otherwise retain the current bounded parsers and retire the row. |
27 changes: 19 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,30 +144,34 @@ truth unless the consumer explicitly admits them.

### Invariant Authoring Loop

For a repository with no specification, Proofkit can guide an agent through two
different starting modes:
For a repository with no specification, Proofkit can guide an agent through
three explicit starting modes:

```mermaid
flowchart TB
Start["Code, docs, tests, issues, and maintainer intent"] --> Mode["Choose trust mode"]
Mode --> Fresh["Fresh authoring mode"]
Mode --> Baseline["Code baseline mode"]
Mode --> Audit["Code audit mode"]
Fresh --> Contract["Owner-authored product contract"]
Baseline --> Observations["Caller-owned capability observations"]
Audit --> Observations
Observations --> Seeds["Candidate invariants and requirement seeds"]
Seeds --> Review["Owner review and promotion"]
Review --> Specs["Repo-owned requirements.v1.json"]
Contract --> Specs
Specs --> Obligations["Proof obligations"]
Obligations --> Evidence["Proof bindings and test inventory"]
Evidence --> Admission["Proofkit admission and coverage"]
```

| Mode | Use when | Result |
|---|---|---|
| Fresh authoring | No existing code or specification is accepted as product truth | Owner-authored behavior statements that remain candidates until admitted as repository requirements |
| Code baseline | Current behavior is accepted as the starting contract | Candidate requirements and bindings that preserve current behavior until owners review them |
| Code audit | Current behavior may be wrong or incomplete | Untrusted observations and questions that must be promoted by a repository owner before becoming requirements |

In both modes, generated records remain candidates until the consuming
In all three modes, generated records remain candidates until the consuming
repository admits them as repo-owned requirements, proof bindings, and witness
plans. Proofkit can structure and validate candidate packets, but it does not
extract complete behavior from arbitrary source code, invent product policy, or
Expand All @@ -179,7 +183,8 @@ Use the CLI help route before reading source:

```bash
npm exec --offline -- agentic-proofkit help
npm exec --offline -- agentic-proofkit init
npm exec --offline -- agentic-proofkit adopt plan --mode fresh --repo-root .
npm exec --offline -- agentic-proofkit help adopt plan
npm exec --offline -- agentic-proofkit help repo-profile-admission
npm exec --offline -- agentic-proofkit repo-profile-admission --help
```
Expand All @@ -189,12 +194,18 @@ does not read stdin. The full machine-readable command inventory remains
`proofkit/cli-contract.v2.json`; the human route map is
`docs/proofkit-contract-map.md`.

`adopt plan` is the read-only front door. It inventories only a fixed catalog
of recognized files at the explicit repository root, validates all arguments
before filesystem access, and returns candidate-authoring tasks. It does not
infer a stack, parse arbitrary source semantics, generate requirements, write
files, or execute evidence. `--stack` is an optional caller-selected hint and
cannot change the selected trust mode.

| Repository state | Minimal first route | Stop condition |
|---|---|---|
| Unknown starting point | `init` | Stop before reading repository files, writing files, or treating route guidance as proof |
| Fresh repository with no specs and no extracted observations | `init --preset fresh`, then `scaffold-project-structure` or `gradual-adoption-bootstrap` | Stop before writing files or inventing requirement meaning |
| Current code is trusted as the initial contract | `capability-map-admission` with `trustMode: "code_baseline"` | Stop before treating generated seeds as admitted requirements |
| Current code must be audited before it becomes a contract | `capability-map-admission` with `trustMode: "audit_from_code"` | Stop at owner questions and candidate-only records |
| Fresh repository with no specification | `adopt plan --mode fresh --repo-root .` | Stop before writing files or inventing requirement meaning |
| Current code is intentionally accepted as the initial baseline | `adopt plan --mode code-baseline --repo-root .` | The flag is a caller declaration, not evidence that the code is correct; stop before promoting candidate observations |
| Current code must be audited before it becomes a contract | `adopt plan --mode audit-from-code --repo-root .` | Stop at explicit observations, owner questions, and candidate-only records |
| Legacy repository has local proof infrastructure | `migration-parity-admission`, then `migration-plan` | Stop before deleting local proof owners without parity evidence |
| A change set needs bounded checks | `changed-path-set`, optional `impact`, then `selective-gate-plan` and `selective-gate-evidence` | Stop on unknown scope, missing routes, or stale receipts |
| An agent needs only one specification subtree | `requirement-context-compose --repo-root . --input context-catalog.json`, then `requirement-context-slice` | Stop before treating a bounded slice as complete repository truth |
Expand Down
Loading
Loading