@timurproko/a1 0.1.8-dev.402 → 0.1.8-dev.407

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-09-14T18:48:36.221Z",
+  "builtAt": "2026-09-15T08:46:47.594Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "9db1726bbe3fc2e8292f2ead1e7e9d0fd4d7d0dc9217b372582bf354b0f565dc",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-14T18:48:19.618Z",
+  "builtAt": "2026-09-15T08:46:40.389Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "d8cda6b0c7cb36c0cc41e90802aceebf6c02eaebbc08a83d7d963d2e918dbd7a",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-14T18:49:01.865Z",
+  "builtAt": "2026-09-15T08:47:16.137Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "711c72395a5bd9efb4a302df595a7f38ed4cfafb8968426ebb2ed75a39cf1502",
+    "sha256": "3693ca18bc9008f730b7816c1a7854c24fc343511e1fd9f761a20afbfd6c9cfb",
     "size": 177664
   },
   "provenance": {

package/docs/local-worktree-cleanup.md

@@ -0,0 +1,128 @@
+# Local worktree cleanup after automatic archival
+
+Local cleanup completes the delivery order in [the archive runbook](openspec-archive-automation.md): implementation merge, verified manual acceptance-record **merge**, automatic OpenSpec archive **merge**, remote topic-ref deletion, then safe local cleanup. GitHub Actions never reaches into a developer machine. This command neither publishes archives nor merges PRs or deletes remote refs.
+
+The implementation is repository tooling, not part of the installed A1 product. It requires Node, Git, and GitHub read access. No product build, dependency installation, interactive UI, or OS-service provisioning is needed. It supports this repository's `origin` on github.com, via HTTPS or SSH.
+
+## Preview first
+
+From a checkout containing the reviewed tooling:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs preview --repo D:/Git/a1
+node scripts/governance/local-worktree-cleanup.mjs status --repo D:/Git/a1
+```
+
+`--repo` is the **primary** worktree, not a task worktree. Preview reads live evidence but changes no worktrees, refs, ownership state, or retry checkpoints. Status is local-only. Existing folders are reported `unmanaged` and are never adopted by their name, missing upstream, or ancestry. Neither command enables cleanup.
+
+Remote reads use `GH_TOKEN`/`GITHUB_TOKEN`, otherwise existing `gh auth token --hostname github.com` authentication. Do not put tokens in command arguments, source files, reports, or PR comments. Missing/expired private-repository authentication blocks evidence checks.
+
+## Explicit local enablement
+
+Only after the maintainer authorizes activation, use the reviewed tool in the primary/stable checkout outside `.worktrees/`:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs enable --repo D:/Git/a1
+node scripts/governance/local-worktree-cleanup.mjs once --repo D:/Git/a1
+```
+
+`enable` only records permission; it does not start a process or remove anything. `once` evaluates at most one bounded pass. Mutation commands `once` and `watch` refuse tooling loaded from inside the target repository's removable root. For pre-merge isolated tests, the test repository is a separate disposable temporary repository, not the working repository itself.
+
+For eventual cleanup after asynchronous archive integration, run watch mode in a separate terminal or an explicitly managed local process:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs watch --repo D:/Git/a1
+```
+
+It runs one immediate pass and retries at five-minute intervals, with rate-limit backoff and no overlapping mutations. Each pass is bounded to 100 registration evaluations, 500 remote requests, and 60 seconds; individual subprocess/remote calls have a 10-second deadline. Local content traversal is additionally bounded to 20,000 entries; insufficient inspection never grants deletion authority. Reports identify incomplete coverage. A durable round-robin cursor lets later pending candidates run on subsequent passes.
+
+When the process is stopped or the machine is offline, GitHub cannot remove local folders. The next enabled invocation rechecks the queue and live evidence. No implicit service, scheduled task, or A1/Pi startup hook is installed.
+
+## Register and release only work you own
+
+Keep an owner token private for the delivery session. For example, in Git Bash:
+
+```bash
+export LOCAL_CLEANUP_OWNER_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
+```
+
+Register after the draft PR number is known, using actual PR numbers and canonical paths. The following example deliberately requires replacing `123` and `example-task`:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs register --repo D:/Git/a1 --path D:/Git/a1/.worktrees/example-task --change example-change --source-pr 123 --candidate-pr 123 --role implementation
+```
+
+Registration binds the repository, exact directory/filesystem identity, candidate PR, HEAD/ref, role, and generation. It returns an ID and generation, not the owner token. The worktree stays `owned`: registration alone never authorizes removal. Supported roles:
+
+- `implementation`: exact merged implementation PR head; candidate PR equals source PR.
+- `acceptance`: exact verified implementation merge commit; candidate PR equals source PR.
+- `archive`: exact merged generated archive PR head; candidate PR is the archive PR and source PR is the implementation PR.
+
+A CI/base/older-ancestor checkout does not qualify automatically. No local archive checkout is required when the archive was generated entirely on GitHub. Legacy version-1 implementation linkage remains supported, but individually reviewing and registering a legacy checkout is explicit adoption, not a bulk sweep.
+
+The disposable ignored-path allowlist defaults to **empty**. Only append flags such as `--disposable node_modules --disposable dist` when those exact generated directories may be discarded. This is not permission to discard tracked, staged, or untracked changes. Unknown ignored data, nested repositories/submodules, links, and special files remain blockers. Declaring a generated directory does not bypass safety or traversal bounds.
+
+Before handing a completed checkout to cleanup, stop its development processes, leave its directory, and release it using the returned ID and current generation:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs release --repo D:/Git/a1 --id REGISTRATION_ID --generation CURRENT_GENERATION
+```
+
+Release verifies ownership and the original directory, records the owner's current final HEAD/ref, and returns a new generation. It does not declare acceptance or archival. The worker still verifies the actual merged implementation, exact legacy-comment or human-manually-merged acceptance receipt, automatic archive markers/merge/CI, current `develop` archive contents, and live absence of implementation, acceptance, and archive topic refs. An acceptance merge alone remains ineligible. A bot/automatic/merge-queue acceptance, stale record, missing acceptance-head CI, or unmatched archived receipt blocks cleanup. It will not remove an open or closed-unmerged PR's worktree.
+
+After release, request a pass from the stable checkout if cleanup is enabled. A running watcher will also pick it up. Never release another session's worktree or use a clean status/dead PID as a substitute for ownership.
+
+## Resume or recover ownership
+
+Before resuming a released worktree, acquire it:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs claim --repo D:/Git/a1 --id REGISTRATION_ID --generation CURRENT_GENERATION
+```
+
+Use a private token for the new session. Claim, release, and cleanup share a per-repository lock. A successful claim prevents deletion until the new owner releases it. A deleting or completed candidate cannot be claimed. A path reused after completed cleanup requires a new explicit `register` operation.
+
+A session crash does not release ownership. After separately confirming that the owner and all related processes have stopped, an explicit recovery claims it for review:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs recover --repo D:/Git/a1 --id REGISTRATION_ID --generation CURRENT_GENERATION --confirm-stopped
+```
+
+Recovery never releases or deletes. The generation must still match. A Git worktree lock remains a veto. A leftover `mutation.lock` from a crashed cleanup process also remains a veto: stop all cleanup/claim processes, inspect the lock and `state.json`, and obtain explicit approval before manually removing that identified lock. There is no automatic stale-lock eviction or PID-based deletion.
+
+## Outcomes and interruption handling
+
+State, journals, stop controls, and execution reports live in `<git-common-dir>/local-worktree-cleanup/`, outside removable checkouts. `status` omits owner-token hashes. Reports contain identities, local blockers, performed steps, and coverage, never file contents or credentials. Completed reports are retained for 30 days subject to a 10 MiB cap; unresolved queue/journal records are not evicted.
+
+- `eligible`: preview passed the gates; nothing was removed.
+- `pending`: archive/ref prerequisites have not finished.
+- `blocked`: ownership, content, path, provenance, authentication, or identity needs attention.
+- `unmanaged`: no local registration; no automatic adoption.
+- `removed`: worktree and eligible local-ref operations were verified.
+- `already-absent`: a completed journal's path/ref are still absent.
+- `partial`: a destructive step began but all cleanup could not be verified.
+- `deferred`: a bounded pass or concurrent mutation owner prevented evaluation.
+
+Non-force Git removal is the only worktree deletion operation. Local topic-ref deletion then compares the exact old SHA and refuses refs checked out elsewhere. `develop`, primary/current directories, changed heads, and active sessions are protected. Normal removal retires its own Git worktree registration; unrelated stale/missing registrations are never globally pruned.
+
+Windows file locks can leave a directory after Git removes part of a worktree. `partial` retains that residue and its journal; there is no `rm -rf`, force discard, or automatic directory-repair fallback. Stop the locking process and review the exact residual data before separately authorized manual repair. A recreated path is not the old checkout. If a prior run fully removed the worktree and only ref cleanup remains, a subsequent enabled pass rechecks evidence and safely resumes the branch-only step.
+
+Ownership is cooperative: managed sessions must claim before use. It cannot police arbitrary external editors. Remote ref checks and local deletion also are not one distributed transaction; refs are read immediately before destructive steps, and uncertain identities always block.
+
+## Disable and test
+
+Stop watch with Ctrl+C, or request immediate stop authority from another terminal:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs disable --repo D:/Git/a1
+```
+
+Disable writes a stop sentinel without waiting for a busy mutation lock. The worker checks it before each destructive step; an already executing Git operation cannot be undone. No later deletion starts while disabled. State and partial journals remain available for review and future explicit enablement.
+
+Dependency-free focused fixtures (temporary repositories only, no live PR mutation or watcher activation):
+
+```bash
+node --test test/repository-governance/local-cleanup.node.mjs test/repository-governance/local-cleanup-evidence.node.mjs test/repository-governance/local-cleanup-watch.node.mjs
+```
+
+The Vitest bridge includes these fixtures in ordinary fast CI, whose runner is Windows. On Windows the suite exercises an actual exclusive file handle and a junction; a non-Windows run explicitly skips the Windows-only handle case rather than claiming it passed. Required current-head CI and a separately authorized live archive lifecycle remain necessary before acceptance; fixtures and preview do not replace those gates.

package/docs/openspec-archive-automation.md

@@ -1,14 +1,27 @@
 # Automatic OpenSpec archival
 
-The archive workflow handles accepted implementation merges into `develop`, a daily 90-day catch-up, and targeted retries. It creates an OpenSpec-only PR; existing documentation auto-merge remains responsible for squash integration after real current-head CI. An archive PR being open is not a completed archive.
+The archive workflow handles merged OpenSpec implementations, visible acceptance review, a daily 90-day catch-up, and targeted retries. When acceptance is missing, it creates or reuses `Accept: <change> — implementation #<number>`; only an authorized maintainer's verified manual merge of that exact record grants PR-backed acceptance. It then creates an OpenSpec-only archive PR, which existing documentation automation squash-integrates after real current-head CI. An open acceptance or archive PR is not completed acceptance or archival.
 
 Documentation CI installs only the pinned OpenSpec archive tool into runner temporary storage, not the repository dependency tree. Candidate validation selects that installation with `--tool-root`; the override is unavailable to publication and audit modes. The documentation job has read-only contents, PR, and Actions permissions; the existing merge owner also declares Actions read access for checking source validation.
 
-## One draft PR from planning through implementation
+## One PR: specs, implementation, CI, validation, merge, archive, cleanup
 
 A new implementation-bound change starts as OpenSpec-only artifacts in one draft PR, not a plan merged ahead of its implementation. Planning requests authorize no code. The agent prepares the link below while opening that draft. After explicit plan approval and an implementation request, continue in the same worktree, branch, history, and PR; reconcile approved planning refinements before their code edits and include related product documentation there too.
 
-Keep the PR draft while incomplete, then make it ready for final review. Approval to implement is not final acceptance or merge authorization. The completed PR still requires required CI, actual final-head maintainer review, and explicit manual integration. The documentation merge owner holds implementation-associated PRs and new active changes even if marked ready or their marker is removed. PR body edits trigger reconciliation and disable an excluded armed merge. Ordinary docs, standalone revisions to existing merged plans, and verified archive moves remain automatic under the exact path allowlist.
+Use this delivery sequence:
+
+1. **Specs:** prepare and approve the plan in the draft PR. Planning does not authorize implementation by itself.
+2. **Implementation:** after explicit approval/request, implement in that same worktree, branch, history, and PR. Keep it draft while implementation is unfinished.
+3. **CI:** push the completed candidate and mark the PR **ready for review before running required CI**. Normal `ready_for_review`/`synchronize` events provide PR-visible test progress. Do not manually dispatch ordinary CI merely to keep the completed candidate draft and then run it again on readiness. Dedicated Full regression/native workflows remain separate required evidence where applicable.
+4. **Implementation review:** after applicable CI passes, obtain actual maintainer validation of the exact final head. Readiness, plan approval, and green CI are not acceptance or merge authorization. A changed candidate requires current-head CI and renewed review.
+5. **Implementation merge:** merge manually only after explicit authorization; implementation auto-merge stays disabled. This integrates code but does not invent post-merge archival acceptance.
+6. **Visible acceptance:** trusted automation creates or reuses one acceptance PR from exact source and CI evidence. Pending substantive tasks and unknown outcomes keep it draft/blocked. Reconcile only evidence-backed stale bookkeeping in that same PR. After its current-head CI passes, an authorized maintainer manually merges it; auto-merge is always forbidden. That merge records archival acceptance without a JSON comment or acceptance-of-acceptance PR.
+7. **Docs/specs auto-merge:** the verified acceptance merge resumes conservative synchronization and prepares the OpenSpec-only archive PR. Documentation automation merges that follow-up after its own required CI. Do not separately merge specs/docs or archive before implementation and acceptance integration.
+8. **Cleanup:** verify implementation, acceptance, and archive integration before removing retained local task/acceptance worktrees. Preserve ownership, clean-tree, and closed/unmerged safety checks. The owning agent performs eligible local cleanup or explicitly releases a registered checkout to the opt-in [local cleanup worker](local-worktree-cleanup.md); no always-running service is provisioned automatically. Hosted remote-branch cleanup remains independently gated on the corresponding PR's verified merge.
+
+When a PR check fails, repair routine failures in its existing worktree, branch, and PR and repush; a separate proposal or PR is not required solely for the repair, including a narrowly scoped inherited failure. Preserve the tested behavior, assertions, coverage, and required checks, record the cause and validation, and obtain fresh current-head CI and renewed implementation review; post-merge acceptance remains separately recorded. Substantive new scope still requires clarification. Reclaim a registered released checkout before resuming work; a repair grants no live cleanup or merge authority.
+
+The implementation, acceptance, and archive PRs each need their own CI because they carry different decisions and bytes. The redundant draft-dispatch-then-ready implementation run is what this sequence avoids. The documentation merge owner holds implementation-associated PRs, new active changes, and acceptance records/branches even if marked ready or their editable marker is removed. PR body edits trigger reconciliation and disable an excluded armed merge. Ordinary docs, standalone revisions to existing merged plans, and verified archive moves remain automatic under the exact path allowlist.
 
 ## Normal implementation handoff
 
@@ -33,29 +46,17 @@ The minimal link is `{ "version": 2, "change": "example-change" }`. Version 2 ve
 
 All implementation, tests, CI, and manual-review tasks must be completed separately before acceptance. Never combine physical review or merge authorization into these mechanical tasks. An old mixed task is a blocker, not permission to tick unperformed work.
 
-After the maintainer actually accepts the final candidate, record one authorized maintainer PR comment:
+After implementation merge, automation commits one version-1 JSON request at `openspec/acceptance/<change>/<source-head>.json` on `docs/accept-<change>-<source-pr>`. Its PR body shows the exact implementation head/merge, spec baseline, final-head source CI, recorded evidence, every original task and continuation line, unfinished work, known gaps, and this sentence: **Merging this PR records your acceptance.** It is a review record, not another proposal.
 
-````markdown
-```openspec-acceptance
-{
-  "version": 1,
-  "change": "example-change",
-  "headSha": "REPLACE_WITH_FINAL_REVIEWED_40_CHARACTER_SHA",
-  "specBaseSha": "REPLACE_WITH_REVIEWED_SPEC_BASELINE_40_CHARACTER_SHA",
-  "verdict": "accepted",
-  "implementationComplete": true,
-  "manualReview": "passed",
-  "specSyncReviewed": true,
-  "evidence": "Identify the exact candidate, applicable commands, scenarios reviewed, and actual outcomes."
-}
-```
-````
+A generated record expresses only the conditional decision `accept-on-manual-merge`; it never names a reviewer or claims the merge already occurred. Completed source tasks stay recorded. An unchecked substantive task remains pending until actual evidence is linked and its unchanged task identity is explicitly marked `evidenced`. Only the exact pure task `Record maintainer acceptance by manually merging the acceptance PR.` may use `signoff-on-merge`. Implementation, test, live/physical review, mixed, unknown, or known-gap work cannot use that shortcut. Archive-preparation tasks retain their existing mechanical handling.
+
+The acceptance PR starts draft whenever source CI or substantive evidence is incomplete. Edit the record on its existing bot-owned branch without unrelated files; automation preserves reviewer edits and makes a complete draft ready on a later synchronize/scheduled/targeted pass. Closing it without merging records no acceptance; replacement requires an authorized targeted retry. Never enable auto-merge. Reserved paths, branch identity, complete diff, both rename names, and authoritative base/head state preserve the manual hold even if title, label, or body metadata is removed.
 
-The placeholders intentionally fail validation. The agent fills actual identities and reports; it must never invent a positive review. The spec baseline is an ancestor commit containing the canonical requirements against which the maintainer reviewed the deltas. It is not automatically moved to a newer baseline to conceal conflicts.
+Candidate CI checks the exact single added record using trusted base policy and read-only permissions; it does not execute candidate scripts or wait for its own result. After manual merge, the reader separately verifies exact committed bytes, current-head CI including the acceptance check, source identities, develop ancestry, write/maintain/admin human merger, and absence of automatic/App/merge-queue provenance. Archive evidence retains acceptance PR/head/merge, record digest, author and reviewed task reconciliation. Acceptance integration alone never authorizes local deletion.
 
-The comment author needs repository write/maintain/admin authority. A newer head needs renewed acceptance; missing, edited, contradictory, revoked, stale, or known-gap records block the automatic route. Acceptance records remain version 1 and require one unambiguous current-head acceptance record. Earlier-head records are retained; same-head contradictions or a later conflicting record require explicit reconciliation before retrying. Source acceptance is copied into the archived `acceptance.md` with PR, head, merge, check-run, and comment provenance.
+Existing valid version-1 `openspec-acceptance` comments remain supported. Their author still needs repository write/maintain/admin authority, and edited, contradictory, revoked, stale, known-gap, or current-head conflicts fail closed. Automation never creates a synthetic comment or chooses between conflicting comment-backed and PR-backed authority.
 
-The code PR still requires explicit manual merge authorization. After that merge, no additional archive request is needed for an eligible change. Planning-only and archive PRs never count as implemented changes. Existing `acceptance.md` files require manual reconciliation rather than being silently overwritten.
+The code PR still requires explicit manual merge authorization. After a verified acceptance merge, no additional archive command is needed for an eligible change. Planning-only and archive PRs never count as implemented changes. Existing `acceptance.md` files require manual reconciliation rather than being silently overwritten.
 
 ## Rejection, standalone docs, and legacy migration
 
@@ -106,8 +107,11 @@ For authorized publication or retry, use the **OpenSpec archive** Actions dispat
 
 ## Outcomes and bounds
 
-- **eligible**: evidence and isolated staging passed; dry-run did not publish.
-- **blocked**: a named evidence/task/spec/setup/ownership problem requires attention.
+- **awaiting-evidence**: an acceptance PR exists but lists missing CI, substantive tasks, or actual outcomes; update that same request without fabricating results.
+- **awaiting-manual-acceptance-merge**: the validated acceptance request needs explicit maintainer review and manual merge.
+- **eligible**: accepted evidence and isolated archive staging passed; dry-run did not publish.
+- **accepted-archive-blocked**: acceptance is verified, but tasks, synchronization, archive CI, or publication still blocks archival.
+- **blocked**: a named evidence/task/spec/setup/ownership/conflict problem requires attention.
 - **pending**: archive PR exists; current-head CI and automatic merge are not yet complete.
 - **already-archived**: merged archive identity and retained evidence were verified.
 - **deferred**: the queue or scan budget prevented work this run.
@@ -117,8 +121,8 @@ Only one automatic archive PR is outstanding at a time. Runs never wait on CI. A
 
 Catch-up scans a fixed 90-day window, up to 500 PRs per pass, with a 10-minute workflow budget and one publication per run. A small versioned cursor resumes unfinished windows; reports and cursors are retained for 14 days. Missing/expired cursors restart a bounded scan, not an assumed complete audit. Older PRs remain targetable. Exceptionally dense search buckets or incomplete GitHub search results are explicit blockers rather than silent truncation.
 
-Known-gap archival remains a separately authorized manual path. The existing backlog is not bulk-approved when automation starts. Local worktree cleanup remains with the local agent after verified integration and a clean-tree check.
+Known-gap archival remains a separately authorized manual path. The existing backlog is not bulk-approved when automation starts. Local worktree cleanup remains local: the owning agent can release an explicitly registered checkout to the separately enabled [local reconciler](local-worktree-cleanup.md) after stopping its use. The reconciler waits for verified archive integration and remote-ref absence, checks ownership and all local content, and never force-discards dirty work. Unregistered or unreleased worktrees remain untouched.
 
 ## Disable or roll back
 
-Disable the **OpenSpec archive** workflow or revoke its App publication credentials. Preserve active changes and open archive PRs for review. Do not delete documents, undo synchronized specs, or modify repository rulesets merely to stop automation. Existing documentation auto-merge and remote branch cleanup remain independently governed.
+Disable the **OpenSpec archive** workflow or revoke its App publication credentials to stop new request/archive publication. Preserve authoritative acceptance records, their manual auto-merge hold, active changes, and open review/archive PRs. Do not delete receipts, undo synchronized specs, or modify repository rulesets merely to stop automation. Readers must remain compatible with existing PR-backed and legacy comment receipts or fail closed. Existing documentation auto-merge and remote branch cleanup remain independently governed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.402",
+  "version": "0.1.8-dev.407",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",