Skip to content

contract decompose: scope file to an unsigned proposal for merge - #48

Draft
mgillr wants to merge 1 commit into
mainfrom
decompose-generic
Draft

mgillr wants to merge 1 commit into
mainfrom
decompose-generic

Conversation

@mgillr

@mgillr mgillr commented Oct 27, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds proofline contract decompose <scope.json> [--out proposal.json] [--against a.json,b.json] [--check] [--lint-warn] and docs/DECOMPOSITION.md, so scoped work becomes contract tasks the same way in every repository.

A scope file (proofline-scope/1, JSON) holds an id prefix and tasks with their title, acceptance checks, requirement ids, dependencies and an owner placeholder. It can also hold shared defaults and criteria that go before or after each task's own. decompose turns it into an unsigned proposal that contract merge accepts.

  • The output is byte-stable: fixed key order, criterion ids <task>-AC01..., two-space JSON and a final newline. The command prints the sha256.
  • It refuses a duplicate id (in the scope, or in an --against contract), an unknown dependency, a cycle, and a task contract validate would refuse. Nothing is written in those cases. --lint-warn turns the validate findings into warnings, for a contract whose existing tasks already have that shape.
  • It never writes proofline.json, any file with that name, or a .sig.
  • --check exits 1 when the committed proposal is not the output of its scope file. This is for CI.

docs/DECOMPOSITION.md describes the process:

  1. Write the scope file.
  2. Run decompose.
  3. Run --check and coverage.
  4. Open a proposal PR that leaves proofline.json alone.
  5. Get the owner's go.
  6. Fold with contract merge on a sign branch.
  7. Run validate, sign and verify-sig.

It also covers amending existing tasks, lists the roles, and includes a CI job that checks proposals against their scopes, validates the contract and verifies its signature, with a variant for contracts in subdirectories.

Requirement IDs

None new. This builds on contract merge, coverage, validate, sign and verify-sig.

Scope and exclusions

  • New: src/decompose.mjs, test/contract_decompose.test.mjs, fixtures/decompose/ (a toy example-project scope, its golden proposal and a REQUIREMENTS.md), and docs/DECOMPOSITION.md.
  • Changed: bin/proofline.mjs (the subcommand, its flags and help text), test/cli_unknown_flags.test.mjs (the new subcommand is in the list), and the README, CHANGELOG and docs index.
  • proofline.json, proofline.json.sig and src/contract.mjs are unchanged.
  • Scope files are JSON only, so the CLI keeps zero runtime dependencies (no YAML parser).
  • merge still only appends. A proposal that changes existing tasks is folded with merge and a reviewed edit, as described in the doc.

Verification performed

Check Command / method Result Evidence
New tests node --test test/contract_decompose.test.mjs test/cli_unknown_flags.test.mjs 9/9 pass golden bytes, formatting-independent output, duplicate refusal (in the scope and --against), unknown dep and cycle, no write to proofline.json or .sig, --check drift, merge round-trip followed by validate and coverage
Full suite npm test (Node 22, clean global git config as in CI) 179/180 pass The one failure is the fixture pins the image digest and an isolated command records it. It needs a container runtime, which this machine lacks, and it fails the same way on main
Demo and example contract node examples/demo/demo.mjs --quiet; node bin/proofline.mjs --root examples/demo-contract contract validate exit 0; contract valid
Markdown lint npx markdownlint-cli2 with the repo config 147 findings before and after. docs/DECOMPOSITION.md is clean. The CHANGELOG gains one MD024 (a repeated ### Added), which is the file's existing convention
Determinism on real-size input several larger scope files, decomposed and diffed at the JSON level against hand-maintained contracts and proposals identical tasks. merge of the output into an emptied contract gives the original JSON back

Independent challenge

  • Requirements-to-change traceability reviewed
  • Regression and negative paths considered
  • Scope drift reviewed
  • Claims match evidence
  • Security / permission implications reviewed: the command only reads the scope and --against files, and refuses to write any contract or signature

Documentation and changelog

  • Updated docs / ADR if needed
  • Updated CHANGELOG.md if needed

I want one way to turn scoped work into contract tasks, the same in every
repository. `proofline contract decompose <scope.json> --out <proposal.json>`
reads a proofline-scope/1 file (an id prefix, tasks with title, acceptance
checks, requirement ids, dependencies and an owner placeholder, plus shared
defaults and criteria put before or after each task's own) and writes an
unsigned proposal that `contract merge` accepts.

- Byte-stable output: fixed key order, criterion ids <task>-AC01..., two-space
  JSON and a final newline; the command prints the sha256.
- Refuses a duplicate id (in the scope or in an --against contract), an
  unknown dependency, a cycle and a task `contract validate` would refuse;
  nothing is written then. --lint-warn reports the validate findings as
  warnings for contracts that already carry tasks of that shape.
- Never writes proofline.json or a .sig. --check exits 1 when the committed
  proposal is not the output of its scope file, for CI.

docs/DECOMPOSITION.md is the process: scope file, decompose, validate and
coverage, proposal PR that leaves proofline.json alone, the owner's go, fold
with `contract merge`, sign, verify-sig, with a CI job. Tests cover the golden
file, duplicate refusal, the merge round-trip with validate and coverage, and
the refusal to write a contract or signature, on a toy fixture.

Signed-off-by: mgillr <36207807+mgillr@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant