nawabari 0.1.0 → 0.3.0

package/README.md

@@ -24,6 +24,87 @@ git nawabari --help
 nawabari --version
 ```
 
+## Standalone machine contract
+
+The installed CLI/JSON surface is the integration boundary. An orchestrator
+must discover the contract before using the lifecycle:
+
+```bash
+nawabari capabilities --json
+nawabari --version --json
+```
+
+Both discovery commands work without a Git repository. A compatible
+installation reports `contract_id: "nawabari.standalone-execution.v1"` and
+`schema_version: 1`. The capability response lists the exact commands,
+result-schema versions, identity fields, and stable `failure_codes`. The
+package version is release metadata; it is not a substitute for the
+machine-contract identifier.
+
+The supported standalone sequence is:
+
+```text
+session create -> session claim(s) -> authorize/checkpoint
+-> commit/push -> doctor (reconciliation) -> session close/gc
+```
+
+The JSON envelope is one document on stdout. Success has `ok: true`, a
+`command`, and the command's versioned result fields. Failure has `ok: false`,
+the `command`, a stable `code`, a bounded human-readable `message`, and
+optional structured `details`; JSON mode writes no decorative stderr. Exit
+codes are `0` success, `2` usage, `3` rejected/unsafe operation, `4`
+unavailable capability, `5` failed doctor checks, and `70` unexpected internal
+failure. Consumers must use these fields and codes, never human presentation.
+
+The result schemas expose the following identities:
+
+| Surface                | Versioned identities                                                             |
+| ---------------------- | -------------------------------------------------------------------------------- |
+| session lifecycle      | `session_id`, `repository`, `worktree`, `branch`, `state`                        |
+| 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`          |
+
+Git subprocesses are bounded at 10 seconds and 64 KiB of output; checkpoint
+evidence is bounded to 4,096 paths. `GIT_SPAWN_FAILED`, `GIT_TIMEOUT`,
+`GIT_OUTPUT_LIMIT`, and `GIT_COMMAND_FAILED` remain distinct failure codes.
+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
@@ -41,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
@@ -52,7 +138,96 @@ state, and commits not proven reachable from the integration branch block
 destructive cleanup. A clean close releases only the owned worktree and
 branch, and repeating close is idempotent. `gc` detects stale or interrupted
 sessions; `--apply` uses the same close safety checks and reports blocked
-sessions instead of guessing.
+sessions instead of guessing. `gc --dry-run` performs the same non-mutating
+cleanup preflight and includes stable blocker codes and `recovery_hints` for
+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.
+
+## Session resource claims
+
+Resource claims are versioned, session-scoped ownership records stored in the
+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 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" \
+  --resource 'src/**/*.ts' --mode read --json
+git nawabari session claims --session "$NAWABARI_SESSION_ID" --json
+git nawabari session update --session "$NAWABARI_SESSION_ID" \
+  --resource 'src/**/*.ts' --mode write --json
+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 | 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,
+`.`/`..`, absolute, drive-relative, backslash, unsupported-glob, and
+symlink-escaping forms are rejected with stable machine-readable codes.
+Equivalent claim acquisition and release retries are idempotent. Closing or
+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
 
@@ -70,10 +245,11 @@ decision=$(git nawabari guard --session "$NAWABARI_SESSION_ID" --json) || {
 
 An allowed decision has `allowed: true` and `code: "ALLOWED"`. A denied
 decision has `allowed: false`, a stable code such as
-`WORKTREE_OWNED_BY_OTHER_SESSION`, `PROTECTED_WORKTREE`, or
-`OWNERSHIP_MISMATCH`, and a non-zero exit status. Detached, corrupt, missing,
-or conflicting state fails closed. The guard does not install hooks and does
-not prevent direct filesystem writes outside Nawabari.
+`WORKTREE_OWNED_BY_OTHER_SESSION`, `PROTECTED_WORKTREE`, `DETACHED_HEAD`,
+`WORKTREE_MISMATCH`, or `OWNERSHIP_MISMATCH`, and a non-zero exit status.
+Detached, corrupt, missing, or conflicting state fails closed. The guard does
+not install hooks and does not prevent direct filesystem writes outside
+Nawabari.
 
 ## Orchestrator integration
 
@@ -95,6 +271,149 @@ The orchestrator owns scheduling, prompts, and worker lifetime; Nawabari owns
 only local session identity, worktree/branch ownership, and safe cleanup. No
 Mottainai, GitHub, `gh`, network, or agent-runtime dependency is required.
 
+Mottainai is one optional caller of this contract, not a runtime dependency.
+It may retain task semantics, scheduling, validation policy, Issue/PR
+governance, and worker lifetime. It must pass concrete local declarations to
+Nawabari and retain the returned JSON identities. Nawabari does not import or
+execute Mottainai/GitHub workflow code, infer claims from task text, or create
+a second registry/database.
+
+## Claim-aware operation authorization
+
+`authorize` is the single decision surface for a governed local operation. Its
+versioned vocabulary and required claim access are:
+
+| operation         | required access   |
+| ----------------- | ----------------- |
+| `source-write`    | `write`           |
+| `stage`           | `write`           |
+| `commit`          | `exclusive-write` |
+| `branch-mutation` | `exclusive-write` |
+| `push`            | `exclusive-write` |
+| `cleanup`         | `exclusive-write` |
+
+The request contains a session identity, an operation, and concrete
+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`, `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.
+
+```bash
+git nawabari authorize --session "$NAWABARI_SESSION_ID" \
+  --operation source-write --resource src/example.ts --json
+```
+
+Governed commit accepts only a caller-decided final message and explicit
+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`. 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" \
+  --remote origin --branch feature/example --resource src/example.ts --json
+```
+
+`checkpoint --json` captures bounded Git-observable `changed`, `staged`,
+`unstaged`, and `untracked` path sets, canonicalizes them through the same
+resource model, and reports `in_claim` and `out_of_claim` paths. Checkpoint
+evidence is limited to the state Git exposes at that instant. Direct
+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
+governed session context. It independently observes the repository common
+directory, worktree path, current branch, and current `HEAD`, then compares
+those observations with the session registry. Caller-supplied paths and branch
+labels are expectations only; they are never used to replace an observation
+Git can make.
+
+The shared verifier fails closed with stable registry reasons for detached
+`HEAD`, missing or prunable worktrees, repository/worktree/branch mismatches,
+stale or conflicting registry ownership, ambiguous Git state, and unavailable
+physical observations. Git process failures remain distinct and bounded:
+spawn failure, timeout, output-limit, and non-zero/unexpected exit.
+
+Provisioning canonicalizes the managed root and every existing path segment
+before invoking Git. Traversal, symlink/intermediate-segment escapes, existing
+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
@@ -110,6 +429,29 @@ owner is reclaimed only when the same host proves that exact process identity
 is dead. Invalid, remote, or otherwise unverifiable lock metadata is never
 stolen and fails closed so an operator can inspect or remove it deliberately.
 
+### Conformance and extraction boundary
+
+The packed-package suite exercises the complete standalone sequence, including
+cross-process claim conflicts, governed commit/push, reconciliation, retryable
+cleanup, and prunable worktree recovery. Native tests additionally cover
+process interruption/atomic-write recovery, partial staging or commit failure,
+stale physical state, cleanup races, bounded subprocess failures, and
+idempotency (`src/registry/store.test.ts`, `src/git-mutation.test.ts`,
+`src/cleanup-authority.test.ts`, `src/session-lifecycle.test.ts`, and
+`scripts/smoke-test.mjs`).
+
+The relevant Mottainai #28 execution cases are mapped as follows:
+
+- repository/worktree identity, provisioning path safety, branch collision,
+  symlink escape, local staging/commit/push safety, cleanup revalidation, and
+  reconciliation are Nawabari-native authority and tests;
+- task semantics, prompts, validation evidence policy, Conventional Commit and
+  PR/Issue governance, GitHub operations, and agent hooks remain optional
+  orchestrator-only semantics and must not move into Nawabari.
+
+Run `pnpm run test:package` to validate the exact packed tarball and its
+installed CLI, or `pnpm run verify` for the complete local conformance gate.
+
 ## Development
 
 ```bash