nawabari 0.2.0 → 0.3.0

package/README.md

@@ -64,6 +64,8 @@ The result schemas expose the following identities:
 | claims                 | `claim_id`, `session_id`, `resource`, `mode`                                     |
 | authorization          | `operation`, `allowed`, `code`, `claim_ids`                                      |
 | checkpoint evidence    | `head`, `changed`, `staged`, `unstaged`, `untracked`, `in_claim`, `out_of_claim` |
+| repository evidence    | `session_id`, `base_revision`, `head`, `clean`, `paths.stats`, `evidence_hash`   |
+| bounded diff           | `from_revision`, `to_revision`, `paths`, `stats`, `patch`, `evidence_hash`       |
 | commit/push            | `commit_sha`, `remote`, `branch`, `target`, `relation`                           |
 | reconciliation/cleanup | `clean`, `issues`, `candidates`, `cleaned`, `blocked`, `recovery_hints`          |
 
@@ -74,6 +76,35 @@ The local lifecycle requires Git and the repository-local registry/lock only;
 it does not require Mottainai, GitHub, `gh`, network access, an LLM, or a
 coding-agent runtime.
 
+## Read-only repository evidence
+
+The evidence family is session-addressed and has no task, Issue, semantic, or
+GitHub interpretation. It is the physical repository authority for one owned
+session:
+
+```bash
+git nawabari evidence snapshot --session "$NAWABARI_SESSION_ID" --json
+git nawabari diff --session "$NAWABARI_SESSION_ID" --path src/example.ts --json
+git nawabari diff --session "$NAWABARI_SESSION_ID" --path src/example.ts \
+  --patch --max-bytes 32768 --max-hunks 32 --json
+```
+
+`evidence snapshot` verifies the registry's repository/worktree/branch owner,
+then reuses checkpoint's exact NUL-safe Git observation for `changed`,
+`staged`, `unstaged`, and `untracked` paths. It also reports canonical per-path
+stats, `clean`, the current `head`, session state, and an `evidence_hash`.
+New sessions persist the exact creation/base revision as `base_revision`;
+legacy records that lack this field report `base_revision: null` and
+`base_revision_proven: false` rather than inferring it from a mutable ref.
+
+`diff` requires at least one explicit concrete path and never accepts a glob or
+an empty repository-wide selection. Stats are returned by default. Patch text
+requires `--patch` and is bounded to at most 64 paths, 64 KiB, and 128 hunks;
+the caller may request smaller limits. Unrepresentable Git observations fail
+with `GIT_STATE_AMBIGUOUS`; a requested path whose stat is not exposed by Git
+remains in the result with `available: false` and makes snapshot evidence
+`complete: false`, so no path silently disappears.
+
 ## Session lifecycle
 
 Session IDs are generated automatically as UUIDv7 values. They are immutable
@@ -91,6 +122,11 @@ git nawabari gc --dry-run --json
 git nawabari doctor --json
 ```
 
+`status --json` reports the resolved `managed_worktree_root` used when
+`session create` omits `--worktree`. `session create --help --json` describes
+all four create options as optional and reports defaults for branch, worktree,
+base (`HEAD`), and label.
+
 `session create` provisions a dedicated worktree and mutable branch atomically
 under the repository-scoped mutation lock. The default/integration worktree
 and its protected branch cannot be session resources. `session id` and the
@@ -108,6 +144,19 @@ every candidate that is not safe. Cleanup revalidates the physical worktree,
 branch, and `HEAD` observations immediately before each destructive Git
 operation.
 
+Routine `session list` and `status` output excludes `closed` history and is
+limited to 64 records. Use `--all` (or `--history`) for an explicit complete
+history view; closed records remain persisted and are never silently deleted
+by listing or cleanup.
+
+`gc` stale eligibility is separate from closed-history retention. Its default
+threshold is 24 hours (`86,400,000` ms), measured from persisted `updated_at`;
+records already in `stale` or `closing` state are eligible, and an otherwise
+live record is also eligible when Git reports its registered worktree as
+missing or prunable. Physical Git/worktree state is authoritative for that
+check. `gc --dry-run` and `gc --apply` do not treat a closed record as a stale
+cleanup candidate.
+
 `doctor` includes a non-destructive `reconciliation` check. It reports
 registry/Git ownership drift, including missing or prunable worktrees and
 unregistered physical worktrees, without repairing or deleting anything.
@@ -119,8 +168,10 @@ same repository registry and protected by the same mutation lock. They are
 caller declarations; Nawabari does not infer them from task text or source
 code. Claim JSON exposes `schema_version`, `claim_id`, `session_id`, the
 repository/worktree identities, canonical `resource`, `mode`, and timestamps.
-The initial claim schema version is `1` and supports `read`, `write`, and
-`exclusive-write`.
+The claim schema version is `2` and supports `read`, `write`, and
+`exclusive-write`. Schema v1 records use different overlap semantics and are
+not interpreted implicitly: an embedding caller must explicitly run
+`SessionRegistry.migrate()` before using them.
 
 ```bash
 git nawabari session claim --session "$NAWABARI_SESSION_ID" \
@@ -131,14 +182,23 @@ git nawabari session update --session "$NAWABARI_SESSION_ID" \
 git nawabari session release --session "$NAWABARI_SESSION_ID" --json
 ```
 
+The modes have these normative meanings:
+
+- `read`: a non-mutating access declaration. It is not a consistency lease,
+  so it may overlap an ordinary `write` claim.
+- `write`: ordinary source-modification authority. It may overlap `read`, but
+  not another writer or any `exclusive-write` claim.
+- `exclusive-write`: stronger ownership-sensitive mutation authority. It
+  excludes every overlapping claim, including `read`.
+
 Overlapping claims use this complete compatibility matrix; non-overlapping
 claims are compatible for every mode:
 
-| existing \/ requested | read       | write    | exclusive-write |
-| --------------------- | ---------- | -------- | --------------- |
-| read                  | compatible | conflict | conflict        |
-| write                 | conflict   | conflict | conflict        |
-| exclusive-write       | conflict   | conflict | conflict        |
+| existing \/ requested | read       | write      | exclusive-write |
+| --------------------- | ---------- | ---------- | --------------- |
+| read                  | compatible | compatible | conflict        |
+| write                 | compatible | conflict   | conflict        |
+| exclusive-write       | conflict   | conflict   | conflict        |
 
 Claims use canonical repository-relative POSIX paths. Literal path segments,
 `*`/`?` segment wildcards, and a complete `**` segment are supported. Empty,
@@ -149,6 +209,26 @@ garbage-collecting a session releases its claims; no separate claim registry
 or claim lock exists. Claims describe ownership state only and do not provide
 OS-level filesystem observation or a filesystem sandbox.
 
+An ordinary source change uses `write` and can proceed while another session
+holds a `read` declaration:
+
+```bash
+git nawabari session claim --session "$NAWABARI_SESSION_ID" \
+  --resource src/example.ts --mode write --json
+git nawabari authorize --session "$NAWABARI_SESSION_ID" \
+  --operation source-write --resource src/example.ts --json
+```
+
+A stronger ownership-sensitive operation uses `exclusive-write` and therefore
+requires no overlapping claim:
+
+```bash
+git nawabari session claim --session "$NAWABARI_SESSION_ID" \
+  --resource src/example.ts --mode exclusive-write --json
+git nawabari authorize --session "$NAWABARI_SESSION_ID" \
+  --operation commit --resource src/example.ts --json
+```
+
 ## Ownership guard
 
 `git nawabari guard` is a cheap, side-effect-free authorization decision for a
@@ -217,9 +297,15 @@ repository-relative resources. Nawabari independently verifies the current
 repository, owned worktree, branch, active session, and persisted claims;
 caller-supplied labels do not weaken that decision. The JSON result is the
 automation contract and reports stable allow/deny codes such as
-`MISSING_RESOURCE_CLAIM`, `RESOURCE_CLAIM_CONFLICT`, `INVALID_RESOURCE`, and
+`MISSING_RESOURCE_CLAIM`, `INSUFFICIENT_CLAIM_MODE`, `RESOURCE_CLAIM_CONFLICT`,
+`INVALID_RESOURCE`, and
 the existing ownership/physical-observation codes.
 
+`INSUFFICIENT_CLAIM_MODE` means a matching claim exists but its granted mode
+is weaker than the operation requires. Its bounded details identify the
+resource, required access, and matching granted mode names;
+`MISSING_RESOURCE_CLAIM` remains reserved for an absent matching claim.
+
 **`authorize` returns an authorization decision only; it does NOT execute the
 operation itself.** Governed commit and push execution use this same decision
 path before invoking bounded Git subprocesses.
@@ -234,17 +320,51 @@ repository-relative resources. Every resource must be covered by an active
 `exclusive-write` claim; all Git-visible changed/staged paths must be in the
 explicit list. JSON includes the resulting `commit_sha`.
 
+Commit evidence distinguishes three sets: the caller's **declared/authorized**
+resources (the explicit, claim-covered list a caller passed in), the
+**staged** set Git reports as staged immediately before the commit runs, and
+the **actual committed** set — read back from the resulting commit itself via
+a bounded, NUL-safe `git diff-tree` observation, not inferred from staging
+intent. The `resources` field in a successful `commit --json` result is
+always the actual committed set, proven equal to or a subset of the
+authorized resources; if Git staging/index drift between staging and the
+commit (a hook, a concurrent process) causes the actual commit to contain a
+path outside the authorized set, the result is not reported as an ordinary
+successful commit — it fails with `COMMIT_RESULT_DIVERGED`, which retains the
+resulting `commitSha` (the Git commit already happened) alongside the
+authorized, actual, and divergent path sets for recovery/reconciliation.
+
 ```bash
 git nawabari commit --session "$NAWABARI_SESSION_ID" \
   --message 'record the local change' --resource src/example.ts --json
 ```
 
+An optional `--message-pattern <regex>` validates the final message against a
+caller-declared rule before Git is invoked; Nawabari does not own or infer
+commit-message conventions (such as Conventional Commits) itself, so this
+check runs only when a caller explicitly supplies a pattern, and a mismatch
+fails with `INVALID_COMMIT_MESSAGE` before anything is staged. The pattern is
+bounded to 512 characters and is evaluated before the repository lock is
+acquired, so a pathological caller-supplied pattern cannot stall other
+sessions' governed operations. A repository's own `commit-msg` Git hook (if
+any) still runs normally, since governed commit invokes real `git commit`.
+
+```bash
+git nawabari commit --session "$NAWABARI_SESSION_ID" \
+  --message 'feat: record the local change' --resource src/example.ts \
+  --message-pattern '^(feat|fix|docs|refactor|test|chore): .+$' --json
+```
+
 Governed push requires explicit claim-covered resources and an explicit
 `--remote`/`--branch` target. Existing upstream and local/remote relation are
 inspected before mutation. A missing upstream requires `--create-upstream`;
-behind or diverged history requires explicit `--force`, which uses
-`--force-with-lease`. The JSON result identifies the pushed `target` and
-reports its relation.
+behind or diverged history requires explicit `--force`. Force pushes use an
+exact `--force-with-lease` bound to the observed remote branch SHA; non-force
+pushes rely on `--no-force` without any lease option. Nawabari fetches only
+the explicit remote branch into a disposable ref when local ancestry is
+missing; it does not update tracking refs or fetch unrelated branches/tags.
+The JSON result includes the immutable `source_sha`, explicit `target_ref`,
+observed `observed_remote_sha`, and relation.
 
 ```bash
 git nawabari push --session "$NAWABARI_SESSION_ID" \
@@ -259,6 +379,15 @@ filesystem activity that is reverted, ignored, or otherwise not observable in
 the Git checkpoint is outside Nawabari's guarantee; this feature is not an
 OS-level filesystem monitor.
 
+Checkpoint canonicalization fails closed: a Git-reported path that cannot be
+represented as a canonical repository resource (traversal, symlink escape, or
+syntax reserved for the claim/glob model) never disappears from evidence.
+Checkpoint fails the whole observation with `GIT_STATE_AMBIGUOUS` instead of
+silently omitting the path, so a caller can never mistake an unrepresentable
+observation for a clean one. This mirrors the strictness governed mutation
+already applies to the same Git-observed paths, so checkpoint evidence is
+never weaker than mutation authorization.
+
 ## Physical execution context
 
 Nawabari treats Git and the canonical filesystem as the authority for every
@@ -280,6 +409,11 @@ worktree paths, and existing local branches are rejected deterministically;
 the repository lock serializes Nawabari provisioning and Git's own ref checks
 remain the final collision authority.
 
+An explicit `--base` ref that is empty, malformed, or does not resolve to a
+commit fails with `INVALID_BASE_REF`. The bounded JSON details retain the
+rejected ref, identify `HEAD` as the default recovery base, and include the
+retry hint to omit `--base`; Nawabari does not enumerate or fuzzy-search refs.
+
 ## Repository state and concurrency
 
 The authoritative registry is stored in the repository-common Git directory at