One Session, start to end

memprove begin                                   # continues this Workspace's Task; --new-task "<TITLE>" starts one
# ... edit, then check narrowly ...
git commit -am "parser: handle empty input"
memprove run --test-format cargo -- cargo test   # label r1 on the last line of standard error
memprove checkpoint create \
  --fact "the parser accepts empty input and reports an empty document" --evidence r1 \
  --open "the truncated-header error path is untested" \
  --next "write the truncated-header test and run cargo test"
memprove end --reason "empty input handled"

• begin resolves the Workspace, creates the Task with --new-task, starts a Session and writes this Workspace’s context (Project, Workspace, agent, Task, Session) under <config>/contexts. With a context it needs no option; --project <ID> --task <ID> names another Task. It refuses while the context names a Session that is still active (“A Session that was not ended”). It does not fall back to this directory’s context, its Project or its Task when MEMPROVE_CLIENT_SESSION names a client session that has none of its own.
• Commit before the run that is your Evidence: a fact is verified only while the repository is in the state its run observed, and an uncommitted edit after the run makes it stale (worktree_changed); a run on a dirty worktree is recorded with that state and is as good as any until the state moves.
• memprove run -- <PROGRAM> [<ARG>...] runs the command in your shell, with your environment (MEMPROVE_TOKEN taken out), records exit code, tail of output, duration and, with --test or --test-format cargo|pytest, the number of test cases, and seals a Snapshot. Its standard output is the command’s; when it is large, redirect it to a file outside the repository and read the result and the label on the last line of standard error. A test run records the format it was made with in the ledger as its test_format: cargo or pytest from –test-format, and cases for a –test-cases count without one; the Pack’s Last passed: line reads it to give the arguments that record the same run again.
• checkpoint create records what holds. Word a fact by what holds, not by the commit or the number of test cases (the case count is in the Evidence); put the conclusion in its first sentence. Each --evidence belongs to the closest --fact or --open before it; a fact needs at least one passed test run among what it cites. --next replaces the previous one as a whole; --open records what is left. An --open without --evidence cites no Evidence.
• end ends your Session and clears it from the context, which keeps the Project, the Workspace and the Task; --abandoned is for a Session someone else left (“A Session that was not ended”).

From docs/guide.md at 2625064cbf0a · Markdown