@timurproko/a1 0.1.8-dev.322 → 0.1.8-dev.335

package/docs/architecture/toolchain.md

@@ -71,7 +71,7 @@ Presentation acceptance is the reader comparing `a1 pi` with pinned Pi. `node sc
 
 ## Publication
 
-One workflow publishes both channels: `.github/workflows/release.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` explicitly requests a numbered preview and `npm run release` explicitly requests stable publication after its version pull request merges. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack once and are validated on Windows, Linux, and macOS; a repeated nightly verifies the exact immutable registry tarball. All publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and the stable tag, GitHub Release, and `master` are written only after npm has the package. One global non-cancelling concurrency group serializes the final registry check.
+One workflow publishes both channels: `.github/workflows/release.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` explicitly requests a numbered preview and `npm run release -- patch` explicitly requests stable publication after its version pull request is manually merged; it promotes a development version to its stable core. The following development-version pull request also requires manual merge. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack once and are validated on Windows, Linux, and macOS; a repeated nightly verifies the exact immutable registry tarball. All publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and the stable tag, GitHub Release, and `master` are written only after npm has the package. One global non-cancelling concurrency group serializes the final registry check.
 
 `docs/ci-release-runbook.md` is the operational reference.
 

package/docs/ci-release-runbook.md

@@ -166,15 +166,40 @@ work.
 
 ## Cutting a stable release
 
-From a clean `develop` matching its remote:
+From the repository root on clean `develop` matching `origin/develop`:
 
 ```sh
-npm run release -- patch     # or minor, major, or an exact x.y.z
+npm run release -- patch     # 0.1.8-dev -> 0.1.8; already-stable 0.1.8 -> 0.1.9
+npm run release -- minor     # 0.1.8-dev -> 0.2.0
+npm run release -- major     # 0.1.8-dev -> 1.0.0
+npm run release -- 0.4.0     # exact stable target
 ```
 
-The command lands `x.y.z` through its version pull request, explicitly dispatches
-stable publication for that exact current `origin/develop` commit, and waits. Only
-after success does it land `x.y.(z+1)-dev`.
+A target is required: `npm run release` alone is a mutation-free usage error.
+`patch` preserves prerelease-aware semantics, including `0.1.8-dev.123 -> 0.1.8`.
+The command reports its source, stable target, and prospective reopening before
+preparing anything.
+
+1. The stable-version edit is committed in an owned detached worktree beneath
+   `.worktrees/`. Only this package's manifest and root lockfile version change.
+2. Follow the printed PR URL, wait for required CI, perform local validation, and
+   **merge manually after acceptance**. The helper does not merge PRs or enable
+   auto-merge. It polls for actual merge with a bounded 30-minute wait.
+3. The helper verifies the merged version and source SHA against authoritative
+   develop, then explicitly dispatches stable publication for that exact source.
+   A changed source is an error, not permission to substitute a newer commit.
+4. Only after verified publication of `0.1.8` does it prepare a separate PR for
+   `0.1.9-dev`. Validate and manually merge that PR as well. Until then the helper
+   reports development reopening as incomplete.
+
+Closed PRs, timeout, cancellation, and query failures retain identifiable phase
+work for inspection. Conflicting existing branches/PRs are not overwritten;
+matching pending PRs can be observed again without replacing them. Worktrees
+retained by an earlier attempt are not removed by a later invocation. Cleanup
+only removes clean, owned, confirmed-merged phase worktrees and unchanged remote
+phase branches. The caller is never hard-reset: a final fast-forward is attempted
+only when its branch, original HEAD, and cleanliness remain unchanged. Otherwise
+preserve local work and synchronize manually with the reported remote state.
 
 Stable publication builds the process guardian on all supported platforms, packs
 once, runs the complete suite against those exact bytes on Windows, Linux, and
@@ -200,8 +225,21 @@ Rules that do not bend:
   path, and use the confirmed apply mode only for an accepted mutable policy change.
 - **Nightly documentation review fails:** inspect the reported paths and rules, identify the introducing merge from the nightly interval, and repair the invariant before unrelated work proceeds.
 - **Development publication fails:** fix the cause and rerun `npm run develop`; an npm version that already exists is never overwritten.
-- **Stable publication fails before npm accepts bytes:** no tag, release, or moved branch exists. Fix the cause and release the next version.
-- **Stable publication is uncertain after npm accepted bytes:** stop and inspect registry version, digest, tag, and release. Never republish immutable bytes.
+- **Stable preparation stops before dispatch:** inspect the reported version PR/worktree. After preserving work, an exact matching pending PR can be observed again. If develop already declares the prepared stable version, use its exact target (for example `npm run release -- 0.1.8`) only after verifying that source's merged PR and confirming the registry/tag guards still permit it. Do not use `patch` from stable develop to retry the same version: that deliberately selects the next patch.
+- **Stable publication fails or is uncertain:** inspect the workflow, registry version/digest, tag, and release before choosing recovery. No reopening PR is prepared. Never republish immutable bytes or move a release tag.
+- **Stable publication succeeded but reopening stops:** the stable version is already published. Inspect and finish the reported next-development PR manually; do not repeat stable publication. If no reopening PR was created, prepare the next-development version through a separately validated manual PR after inspecting remote state.
+
+## Safe release-command validation
+
+Use the isolated harness rather than a live release to validate changes to this command:
+
+```sh
+npm exec --no -- vitest run test/repository-governance/release-target.test.ts test/repository-governance/release-command.test.ts --maxWorkers=1 --minWorkers=1
+```
+
+It uses disposable local Git repositories and fake GitHub, registry, and publication
+services. It does not publish a package or create production version PRs. A real
+release remains a separate deliberate operation.
 
 ## Branch protection rationale
 

package/docs/manual-code-streaming-cleanup.md

@@ -0,0 +1,88 @@
+# Bounded code-streaming and hyperlink cleanup review
+
+This candidate finishes the hyperlink portion of `eliminate-code-block-streaming-flicker`
+(specification PR #318), following the partial implementation in #321. It is a prerequisite
+for `keep-streaming-ui-responsive-during-selection` (#325), not that larger change's completed
+selection/wheel performance fix.
+
+## What changed
+
+- Candidate-looking text (paths, dotted identifiers) no longer vetoes a proven followed shift.
+  Real OSC 8 links, unsafe escapes, images, overlays, and selections retain their conservative
+  movement rules.
+- Ordinary streamed text changes no longer request hyperlink cleanup.
+- Pointer transitions identify the former hovered row. Editor link deletion and discarded
+  presentation state retain explicit cleanup requests, including when replacement content
+  has no links. Unscoped cleanup considers every previously linked row; a missing pointer
+  report is not treated as proof that no host decoration exists.
+- Cleanup paints affected and changed rows without manufacturing an erase-display. After
+  unknown paint or lost geometry, it waits for a complete safe frame instead of guessing.
+- Same-geometry forced frames preserve current cells without repainting unchanged rows.
+  Structural entry, resize, and unsafe-protocol fallbacks are still conservative.
+
+## Automated evidence
+
+`test/fixtures/rendering/baseline-code-streaming.json` is the pre-production-change capture
+from `6c5af810`, repeated twice with no production diff. Its synthetic content and cell hashes
+contain no private session input. The fixture predates the added dual-synchronization summary
+field; it remains a historical baseline rather than a regenerated candidate result.
+
+| Bare-A1 fullscreen workload | Baseline post-startup clears | Candidate post-startup clears |
+| --- | ---: | ---: |
+| Streamed fenced code | 3 | 0 |
+| Path-bearing prose | 3 | 0 |
+| Tall live tail | 0 | 0 |
+
+The deterministic producers use a shared scripted clock so cold imports do not advance spinner
+or presentation timers unpredictably. Independent comparison processes remain outside the owned
+damage adapter. Current budgets also fail candidate-only fallback, repaint of settled rows,
+stale final content, or divergent final cells with synchronization honored versus ignored.
+The dual-model replay reuses producer bytes rather than launching duplicate producers.
+
+Generate current evidence (non-interactive; writes only the named report):
+
+```sh
+cd D:/Git/a1/.worktrees/finish-bounded-link-cleanup && node --import tsx scripts/pi/report-code-streaming.ts --phase current --repeat 2 --output .artifacts/rendering/code-streaming-current.json
+```
+
+The baseline mode rejects dirty production sources. Do not replace the committed baseline with
+post-fix results. Repeated reports compare cells, row damage, decisions, and budgets, not elapsed
+machine timings. This is a paint regression check, not a CPU or input-latency benchmark.
+
+## Physical Windows Terminal review
+
+Use the candidate branch `fix/bounded-hyperlink-cleanup` and record its exact `git rev-parse HEAD`.
+Build and start the owned UI through the color-preserving shell entry:
+
+```sh
+cd D:/Git/a1/.worktrees/finish-bounded-link-cleanup && npm run build && ./scripts/dev
+```
+
+1. Ask the agent, without writing files, to produce a long fenced TypeScript example containing
+   `obj.method`, `package.json`, and `./src/index.ts`, followed by a short explanation and a real
+   Markdown hyperlink. Check that ordinary code/path streaming no longer blanks the screen.
+2. Hover a real hyperlink, then scroll it away without moving the pointer. Repeat with a
+   terminal-detected URL and file-like text inside code. Try both short and wrapped links,
+   duplicate targets, blank rows replacing links, and a smaller terminal.
+3. Move off a hovered link, select linked text, wheel/auto-scroll during selection, release,
+   and copy. Check exact copied text, normal link colors/activation, and no leftover solid
+   underlines on unrelated text, padding, or controls.
+4. Paste a URL chip into the editor and delete it. Open and close a covering overlay, and resize
+   while a link is visible. Check that obsolete targets/underlines are removed and restored
+   links have their correct targets.
+5. Verify that the dock stays intact and terminal mouse/cursor behavior is restored on exit.
+
+Use the same geometry for the independent comparison profile:
+
+```sh
+cd D:/Git/a1/.worktrees/finish-bounded-link-cleanup && npm run build && ./scripts/dev pi
+```
+
+Record terminal/version, geometry, synchronized-update support, explicit versus auto-detected
+link case, commit, and pass/fail. Test both before and after any pointer report: lack of a report
+must not be interpreted as evidence of an absent pointer.
+
+**Known gaps:** native Windows Terminal hover rasterization cannot be certified by headless cell
+replay. Visual acceptance and merge authorization are pending. The broader selection/wheel
+scheduling and collapsed-tool preparation optimizations have not been implemented in this PR.
+Do not merge on automated results alone; a ghost-underline or flicker regression blocks acceptance.

package/package.json

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