@timurproko/a1 0.2.7-dev.1244 → 0.2.7-dev.1249

package/docs/openspec-archive-automation.md

@@ -6,6 +6,14 @@ Unrelated standalone documentation remains separate: a non-draft unassociated PR
 
 Version-1 and version-2 deliveries and their existing comments, acceptance PRs, archive PRs, receipts, retries, and bounded catch-up remain supported under [Legacy delivery](#legacy-delivery). Do not silently convert an in-flight legacy delivery.
 
+## Worktree context across agent environments
+
+External agents use ordinary Git worktrees without an A1 installation, runtime, or session link. Follow the [development worktree protocol](architecture/project-structure.md#development-worktrees): keep primary on `develop`, run the cleanup sweep, inspect Git inventory, and verify the exact task root, common repository, branch, and state before edits. A fresh worktree created by the session establishes its provenance. An existing delivery needs continuing ownership or explicit handoff plus the exact branch, change, and PR; inventory and a clean checkout alone grant nothing.
+
+Use A1 inventory/linking only inside an active A1 shell-tool session, and Claude Code's established worktree hooks in that environment. Missing A1 integration alone does not block an external agent. A known live owner, Git lock, conflicting cleanup owner, or unverifiable handoff still blocks reuse. Claim any released cleanup registration through the [cleanup ownership protocol](local-worktree-cleanup.md#resume-or-recover-ownership) before editing. Neither a runtime link nor a cleanup claim proves the absence of arbitrary external editors; coordination remains cooperative.
+
+Repeat context and ownership verification on resume or stream changes, preserve the delivery's branch/history/PR, and keep every command explicitly scoped to its worktree. Handoffs name the absolute worktree path, branch, change, PR, and whether editing ownership is being handed over. An editing handoff does not register, release, or authorize cleanup and grants no integration authority. The lifecycle below applies equally to all agent environments.
+
 ## Version-3 lifecycle
 
 1. **Draft plan:** create one normally named branch/PR such as `feature/...`, `fix/...`, or `chore/...`. Start the body with `## Proposal`, use it for one or two sentences of intent, and follow it with one or more unchecked, outcome-sized task items under `## Implementation`, with no fixed maximum. Each item names a delivered code outcome. Omit generic process tasks; run, verify, validate, evidence, or manual-test items; quoted phase lines; and routine validation command lists, and keep machine linkage under final collapsed `Automation`. Keep it draft and include only planning artifacts until the maintainer approves the plan and explicitly requests implementation.
@@ -94,11 +102,11 @@ Keep acceptance absent during proposal review so unfinished intent is not mistak
 
 ## Agent scratch files
 
-When an agent chooses a path for a transient repository-delivery file—such as a PR/comment body, command payload, captured output, temporary patch/diff, or ad hoc log—it must use a purpose-specific descendant of the exact `.artifacts/` root in the worktree that owns the operation. A linked delivery uses its linked task worktree, not the primary checkout, another worktree, the operating-system temporary directory, home/desktop, or a sibling path. Address the worktree path explicitly because session linking does not change tool cwd.
+When an agent chooses a path for a transient repository-delivery file—such as a PR/comment body, command payload, captured output, temporary patch/diff, or ad hoc log—it must use a purpose-specific descendant of the exact `.artifacts/` root in the worktree that owns the operation. Use the verified task worktree, not the primary checkout, another worktree, the operating-system temporary directory, home/desktop, or a sibling path. Address the worktree path explicitly; context verification and optional runtime association do not change tool cwd.
 
 Keep these files ignored, unstaged, uncommitted, disposable, non-authoritative, and free of credentials or other prohibited sensitive data. Required durable evidence belongs in its declared tracked OpenSpec location. This rule governs paths selected by the agent; it does not relocate temporary storage internally selected by Git, GitHub CLI, OpenSpec, language/package tooling, product runtime code, test frameworks, or hermetic fixtures.
 
-For example, create `.artifacts/agent/pr-body.md` in the linked worktree before passing it to `gh pr create --body-file` or `gh pr edit --body-file`. The exact `.artifacts/` root remains subject to the existing guarded generated-content cleanup policy; this guidance does not authorize deletion outside that root or through unsafe filesystem boundaries.
+For example, create `.artifacts/agent/pr-body.md` in the verified task worktree before passing it to `gh pr create --body-file` or `gh pr edit --body-file`. The exact `.artifacts/` root remains subject to the existing guarded generated-content cleanup policy; this guidance does not authorize deletion outside that root or through unsafe filesystem boundaries.
 
 ## Version-3 implementation metadata
 
@@ -190,7 +198,7 @@ If an unassociated implementation has already integrated, do not edit its merged
 
 ## Finalization command
 
-The local command remains available for inspection or when a developer prefers to finalize before the automatic ready transition; the workflow then verifies the head and pushes nothing. It has inspection mode by default and an explicit `--write` mode. It never commits, pushes, edits GitHub, marks a PR ready, or merges. Run from the linked worktree and use an ignored artifact body file so the operation can update exact version-3 paths without mutating remote PR state:
+The local command remains available for inspection or when a developer prefers to finalize before the automatic ready transition; the workflow then verifies the head and pushes nothing. It has inspection mode by default and an explicit `--write` mode. It never commits, pushes, edits GitHub, marks a PR ready, or merges. Run from the verified task worktree and use an ignored artifact body file so the operation can update exact version-3 paths without mutating remote PR state:
 
 ```bash
 git fetch origin develop

package/docs/validation.md

@@ -52,7 +52,9 @@ node scripts/release/generate-validation-ownership-ledger.mjs --output .artifact
 
 Containment-selected modular jobs build and test the debug `process-guardian.node` addon for their exact platform, export `A1_PROCESS_GUARDIAN_PATH` to that file, and run the launch-owner integration fixtures as Node processes. The tests exercise the real addon-held Windows job or Unix process group, addon-backed identity and terminal operations, and the Node exit watcher; no fixture invokes a process-guardian executable. The Windows startup lane keeps Defender real-time protection enabled while packaged startup loads the release addon.
 
-The `terminal-host` owner is CI-only. A change under `native/terminal-host/` or to its run scripts selects, per platform (Windows x64, Linux x64, macOS arm64), one **Native terminal host** job and three **Native terminal host tests** partition jobs. The partition jobs each build the test profile and run one third of the serialized `role_integration` suite (`run-terminal-host-probe.mjs --partition <i>/3`, partitioned by sorted test name read from the suite's source); the feature-gated `role-host` binary stands in only for the fixed role grammar inside Rust integration tests and is never packaged. The build-and-probe job runs `npm run test:terminal-host` with the role suite skipped (`TERMINAL_HOST_PARTITION=none`), building `terminal-host.node` with Rust, Node-API 9, and Zig 0.15.2 for the lane's exact target and baseline CPU model. It loads the addon for its version and non-interactive probes, verifies the shared session-writer lock export, and uploads the debug addon and frozen protocol manifest; Linux also runs bounded decoder fuzzing.
+The `terminal-host` owner is CI-only. A change under `native/terminal-host/` or to its run scripts selects, per platform (Windows x64, Linux x64, macOS arm64), one **Native terminal host** job and three **Native terminal host tests** partition jobs. The partition jobs each build the test profile and run one third of the serialized `role_integration` suite (`run-terminal-host-probe.mjs --partition <i>/3`, partitioned by sorted test name read from the suite's source) and nothing else; the crate's unit tests run once, in the build-and-probe job, rather than once per partition. The feature-gated `role-host` binary stands in only for the fixed role grammar inside Rust integration tests and is never packaged. The build-and-probe job runs `npm run test:terminal-host` with the role suite skipped (`TERMINAL_HOST_PARTITION=none`), which runs the `--lib --bins` unit tests and the `release_isolation` integration test, building `terminal-host.node` with Rust, Node-API 9, and Zig 0.15.2 for the lane's exact target and baseline CPU model. It loads the addon for its version and non-interactive probes, verifies the shared session-writer lock export, and uploads the debug addon and frozen protocol manifest; Linux also runs bounded decoder fuzzing with a `cargo-fuzz` binary restored from an exact version-and-nightly cache when one exists.
+
+Candidate-packing lanes need the release terminal host but not its toolchain when an exact-input cache entry exists: they restore the addon, manifest, and notices, re-record the manifest's `host-entry.js` digest from the current build with `build-terminal-host.mjs --reuse`, and verify the result with `verify-native-artifacts.mjs --local` before recording the build receipt. See the Development cadence section of [`ci-release-runbook.md`](ci-release-runbook.md).
 
 The protected aggregate requires every partition of every selected platform, keyed by `partition` in the outcome authority and job envelope. Because the role suite no longer warms the resident launch paths in the build-and-probe job, its certification step runs one unmeasured `measure-resident-tabs.mjs` pass before the measured pass whose budgets are unchanged. Fidelity, latency, chaos, and certification start roles as `process.execPath dist/foundation/resident-tabs/host-entry.js` with `A1_TERMINAL_HOST_PATH` naming the addon. Windows cleanup identifies those Node-hosted residents by command line; it never kills every `node.exe` by image name. Locally, `npm run test:terminal-host` without a partition is unchanged and runs everything in one process. Local Windows builds fail in `build.rs` unless `TERMINAL_HOST_LOCAL_BUILD=1` is set, because Zig's package fetch unpacks test data that workstation antivirus quarantines. Native lanes also publish the terminal library they linked; a local build can link it instead of running Zig (see Local native iteration in [`architecture/resident-tabs.md`](architecture/resident-tabs.md)), which is development evidence only and never replaces selected CI. `TERMINAL_HOST_CONTRACTS_ONLY=1` is a library-only diagnostic and cannot substitute for selected CI. See [`native/terminal-host/README.md`](../native/terminal-host/README.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.2.7-dev.1244",
+  "version": "0.2.7-dev.1249",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -126,7 +126,7 @@
     "@mariozechner/clipboard": "^0.3.9"
   },
   "publication": {
-    "source": "111a66b7e3174dcf876416a0b35f09960526ee93",
-    "pullRequest": 868
+    "source": "fdbfddae64dfff5140ae471515eace2208be9246",
+    "pullRequest": 872
   }
 }