@timurproko/a1 0.1.8-dev.182 → 0.1.8-dev.218

package/docs/architecture/code-documentation.md

@@ -0,0 +1,77 @@
+# Code documentation
+
+A1 treats source documentation as a contract, not as a coverage target. Names, types, and decomposition explain ordinary behavior. Comments remain only where removing them would hide a public responsibility, invariant, rationale, security property, platform constraint, compatibility boundary, protocol rule, concurrency rule, performance decision, or provenance fact.
+
+## Public class contracts
+
+Every first-party TypeScript class exposed through a production owner's public entry has exactly one JSDoc description at its declaration. The description states what the class owns and includes its material lifecycle or safety boundary when one exists.
+
+Do not add JSDoc solely because a function, type, constructor, property, or method is exported. Do not document a class by repeating its name or listing its methods. Private and protected members never use JSDoc.
+
+```ts
+/** Persists complete workspace views and recovery references through the control-store boundary. */
+export class WorkspaceStore {
+```
+
+## Implementation comments
+
+A retained implementation comment starts with the reason it exists:
+
+| Intent | Use |
+| --- | --- |
+| `Invariant:` | State or ordering that every implementation path must preserve |
+| `Rationale:` | A non-obvious choice among plausible alternatives |
+| `Security:` | Trust, ownership, cleanup, disclosure, or failure-safety boundary |
+| `Platform:` | Operating-system, terminal, filesystem, or toolchain behavior |
+| `Compatibility:` | Behavior intentionally matching or accepting another version or surface |
+| `Protocol:` | Wire, framing, input, encoding, or externally defined semantic rule |
+| `Concurrency:` | Race, serialization, cancellation, or event-loop ordering |
+| `Performance:` | Bounded work, caching, coalescing, or resource decision |
+| `Provenance:` | Source, generated authority, or adaptation origin |
+
+```ts
+// Security: an uncertain process identity never authorizes termination.
+// Platform: Windows Terminal encodes Ctrl+Backspace as a raw backspace byte.
+// Performance: finalized blocks cache by revision and width; live blocks always render.
+```
+
+A continuation line does not repeat the label. If no intent applies, remove the comment and make the code explain itself.
+
+## Forbidden forms
+
+The repository gate rejects:
+
+- missing or multiple contracts on owner-public first-party classes;
+- `<summary>` and `@summary` tags;
+- boilerplate class descriptions and method inventories;
+- JSDoc on private or protected members;
+- uncategorized implementation comments;
+- obvious commented-out code or control-flow narration;
+- `TODO` or `FIXME` without an issue number, issue URL, or tracker identifier;
+- `@ts-ignore` and suppression directives without a reason;
+- an unclassified tracked code path or synchronized source without provenance.
+
+Follow-up and suppression forms include their authority inline:
+
+```ts
+// TODO(#321): remove the compatibility path after the pinned upgrade.
+// @ts-expect-error -- the shipped JavaScript module has no declaration file
+```
+
+## Source roles
+
+The full style policy applies to first-party production TypeScript and to applicable comments in first-party tests, tooling, and native source. Native source does not receive TypeScript declaration requirements.
+
+Synchronized Pi source, native vendor trees, generated source, build output, and runtime artifacts are not rewritten to match first-party style. Their exclusion comes from the repository source-role classifier, not from a list of accepted violations. Synchronized source must remain covered by its source ledger or explicit provenance header.
+
+## Validation
+
+Run the focused check with:
+
+```sh
+npm run check:code-documentation
+```
+
+The check scans the complete tracked baseline and reports stable rule identifiers with path, line, column, and declaration symbol when available. It has no accepted-violation count or grandfather file. Fast pull-request validation runs the check, and full release validation inherits it through the fast tier.
+
+Focused governance tests use valid and invalid virtual sources to preserve each rule independently from the clean repository-baseline assertion. The gate validates deterministic structure and high-confidence anti-patterns; review remains responsible for the factual accuracy of retained prose.

package/docs/architecture/project-structure.md

@@ -107,7 +107,7 @@ The primary worktree stays on `develop` for integration and must not be used for
 - `docs/features` explains maintained user-facing behavior.
 - Operational and manual procedures live in focused runbooks under `docs`.
 - OpenSpec and Git carry planning and implementation history.
-- Source comments explain only non-obvious rationale, safety/security invariants, platform constraints, or public semantic contracts. Names, types, and decomposition explain normal control flow.
+- Source documentation follows the focused [code-documentation policy](code-documentation.md): owner-public class contracts are consistent, retained implementation comments state their intent, and names, types, and decomposition explain ordinary control flow.
 
 ## Terminal capability boundary
 

package/docs/architecture/ui-reference-provenance.md

@@ -29,7 +29,7 @@ its own `core` facade layer; A1 is a product, so the port adapts imports and kee
 | `ui-components/list-block.ts` — sticky scroll | `settings/impl.ts` — `stickyHeaderGroup`, `topPaddingRows`, `visibleRowCountAt`, `clampScrollForView` | Same reservation arithmetic and two-pass reveal. |
 | `ui-components/mouse.ts` | `core/panes/sgr-mouse.ts` | Same SGR decoding and per-call regex reset; A1 emits its own event shape. |
 | `ui-components/mouse.ts` — tracking sequences | `core/host/pi/providers/host-bridge-surface.ts` | Mouse modes only. A1 does not take the alternate screen, because the Pi TUI owns the screen A1 renders through. |
-| `features/owned-ui/settings-app.ts` — layout | `settings/impl.ts` — `settingsValueColumn`, `renderFieldLine`, footer and search rendering | Setting discovery is A1's own section model; presentation follows the reference. |
+| `features/owned-ui/settings-app.ts` — section layout, pointer controls, and scrolling | `settings/impl.ts` — `settingsValueColumn`, block navigation, sticky sections, and pointer hit regions | Setting discovery is A1's own A1/Agent section model. Section navigation and pointer-only numeric controls follow the A1 reference; explicit `/` search, ruled shared input, shortcut-derived hints, hidden description rows, configured wheel cadence, and distinct floating scalar menus are reviewed owned interactions. |
 
 ## Ported from the pinned engine
 
@@ -37,16 +37,36 @@ its own `core` facade layer; A1 is a product, so the port adapts imports and kee
 | --- | --- | --- |
 | `pi-engine-adapter/settings-integration.ts` — `SETTING_LABELS` | pinned Pi settings selector | Labels and descriptions transcribed so an owned screen reads as the vanilla route words it. Ids are mapped from the selector kebab-case to the exposed camelCase keys. |
 | `pi-engine/session-integration.ts` and `pi-components/shell-footer-status.ts` — steering queue | pinned Pi interactive mode `onSubmit` and `updatePendingMessagesDisplay` | Steering/follow-up uses `prompt(..., { streamingBehavior })`, allowing Pi to emit the accepted user row, while remaining steering rows preserve Pi's opening spacer, dim `Steering:` labels, dequeue hint, and order before `Working`. |
+| `ui-components/list-view.ts`, `dialog-panel.ts`, `value-menu.ts`, and `features/owned-ui/settings-app.ts` — setting presentation | pinned Pi `SettingsSelectorComponent`, Pi TUI `SettingsList`, `SelectList`, and `Input` at `0.84.2` | Cursor, selected label/value accents, unselected muted values, the 30-column label cap, dialog styling, notices, and narrow-width geometry retain pinned semantics. Scalar-menu placement and input remain shared, while A1/Agent grouping, pointer steppers, explicit `/` search, ruled shared input, shortcut-derived status hints, suppressed selected descriptions, `scrollbarSpeed`-driven wheel movement, and the dark floating menu with lighter active row and effective-value check mark are declared product-owned differences. Independent row evidence: `test/features/owned-ui/pinned-settings-presentation-parity.test.ts`; owned interaction evidence: `test/features/owned-ui/settings-app.test.ts`, `test/ui/components/value-menu.test.ts`, and `test/composition/settings-route-host.test.ts`. |
+| `features/owned-ui/project-trust-prompt.ts` — pre-resource selector | pinned Pi `cli/startup-ui.ts`, `cli/project-trust.ts`, and `core/project-trust.ts` at commit `914cf1472e715297caa30db4b9535d534a9eb718` | Uses a fixed, dependency-bounded A1 startup selector rather than importing private CLI modules. It preserves selected-option accent, navigation/accept/reject/cancel semantics, fail-closed behavior, raw-mode restoration, clearing, cursor restoration, and parent-screen restoration before diagnostics. |
+| `pi-session-ui/session-shell-root.ts` and `session-shell.ts` — fullscreen exit | pinned Pi `InteractiveMode.formatResumeCommand()` and shutdown output at commit `914cf1472e715297caa30db4b9535d534a9eb718` | Re-renders authoritative transcript components with semantic SGR intact, excludes inline-image control payloads and fullscreen-only chrome, restores the terminal first, then emits pinned dim `To resume this session:` wording with `a1`, compact session id, and conditional quoted `--session-dir`. |
+| `pi-tui-runtime/input-presentation-coordinator.ts` and custom-viewport dock reuse | pinned Pi TUI `TuiBase` input dispatch and immediate-render pending guard at `0.84.2` | Preserves each original terminal delivery and invokes the existing Pi handlers exactly once in order. Bare A1 alone drains finite-grammar text/edit/navigation bursts in one immediate event-loop opportunity so Pi's existing pending guard paints the newest state once; effectful, unknown, protocol, paste, and extension-owned input remains an immediate barrier. Geometry-stable dock frames reuse A1's established transcript viewport, while uncertain geometry and replacement-surface damage still fail closed. Independent evidence is under `test/support/input-responsiveness/`. |
+| `test/features/owned-ui/pi-raw-terminal-parity.ts` — parity normalization | pinned Pi public components/runtime at `0.84.2` | Only synchronized-output envelopes, absolute hyperlink targets, declared product/path substitutions, and nondeterministic timing may normalize. SGR roles/reset boundaries, rows, cursor operations, clearing, restoration, and write order remain authoritative; A1-generated JSON captures are diagnostics and cannot serve as pinned evidence. |
 
 ## Deliberate differences
 
-- **No alternate screen.** The reference owns its surface and can switch screens; A1 renders
-  through the pinned Pi TUI, so an owned screen is a full-viewport overlay instead.
+- **Owned in-session routes are overlays.** The A1 UI reference owns its surface and can switch screens; A1 renders in-session owned routes through the pinned Pi TUI as full-viewport overlays. The pre-resource trust selector is separate and uses a bounded alternate startup surface solely so every completion path can restore the untouched parent terminal before engine activation or a fail-closed diagnostic.
 - **Colour is a port, not an import.** The reference takes a Pi `Theme` directly. A1 defines
   `UiTheme` so the component layer never imports a Pi adapter and can be rendered plainly in
   tests.
 - **Settings content.** The reference aggregates per-extension settings files; A1 has one
   section for its own settings and one for the agent's, read through the engine settings port.
+- **Settings scalar-menu contrast.** The shared menu keeps reviewed placement, clipping, and
+  input behavior, but A1 uses its prior dark floating panel, lighter white-text active row,
+  and independent effective-value check mark because physical review rejected a menu that
+  blended into the settings rows.
+- **Spinner-backed progress punctuation.** Bare A1 resolves built-in and extension working
+  labels through `ui-components/progress-status.ts`, injected by
+  `pi-session-ui/session-shell-root.ts` into the shared `pi-components/shell-footer-status.ts`
+  spinner factory. The factory canonicalizes the visible progress marker once, to three ASCII
+  periods, without importing across the component-adapter boundary. Engine producers remain
+  semantic and the source-synchronized Pi status indicators, installed packages, `a1 pi`, and
+  vanilla Pi remain untouched.
+- **Keyboard presentation scheduling.** Pinned components, semantic key handling, and the
+  comparison profiles stay unchanged. Bare A1 adds one A1-owned event-loop-turn coordinator
+  before its fullscreen root and may omit only superseded visual states after every delivery
+  has already been applied in order. It does not debounce by wall clock, combine strings,
+  patch Pi TUI, or classify unknown extension/terminal data as safe.
 - **No viewport prototype or child-tree patches.** `ui/agent-view/user-prompt.ts` and the
   private-child traversal in `ui/agent-view/render.ts` were analyzed only for behavior. The
   destination renders source timestamps through an owned transcript adapter and derives sticky

package/docs/ci-release-runbook.md

@@ -46,12 +46,56 @@ effect of stable publication, not a trigger.
 
 | Trigger | Validation and outcome |
 | --- | --- |
-| Pull request into `develop` | Fast required validation; docs-only changes use lightweight governance consistency and OpenSpec changes also use strict OpenSpec validation |
+| Pull request into `develop` | Modular fast validation; changed/new source documentation is checked once, and rendering runs as `none`, `smoke`, or `full` from the exact impact |
 | `npm run develop` | Preview package gates on Windows, Linux, and macOS; an existing numbered preview is an early successful no-op |
-| Nightly at `03:17 UTC` | Complete non-physical suite on Windows, Linux, and macOS, every night |
+| Nightly at `03:17 UTC` | One full documentation review plus the complete non-physical suite on Windows, Linux, and macOS, every night |
 | `npm run release -- ...` | Complete exact-byte stable gates, then npm `latest`, tag, GitHub Release, and `master` |
 | `.github/workflows/full-regression.yml` | Additional on-demand complete regression without publication authority |
 
+## Impact-aware development validation
+
+`scripts/release/select-validation-impact.mjs` is the single pull-request selector. It records the complete merge-base-to-head name-status diff, changed/new documentation inputs, rendering dependency reasons, conservative fallbacks, and the exact head SHA in a machine-readable artifact. Missing history, unresolved rendering dependencies, unknown relevant inputs, or classifier failure select full rendering rather than silently skipping it.
+
+Ordinary type, architecture, unit/contract, and dist checks always run for code changes. Changed-file documentation and rendering run as independent parallel jobs. Rendered shell/component changes select `smoke`; viewport, scheduler, terminal adapter, evidence harness, package identity, and selector changes select `full`; unrelated changes select `none`. The aggregate accepts a skipped modular job only when the current selector requested the skip.
+
+Inspect local committed and worktree impact without running tests:
+
+```sh
+npm run select:validation-impact -- --include-worktree
+```
+
+Check documentation only for modified, added, copied, and renamed-to policy files:
+
+```sh
+npm run check:code-documentation:changed
+```
+
+Run the explicit complete documentation review used by nightly and complete regression:
+
+```sh
+npm run check:code-documentation
+```
+
+Rendering evidence captures each selected producer/mode/workload matrix once and reuses it for semantic, paint, parity, and damage assertions. A deliberate second `streamed-prose` capture remains only for determinism. Workflow summaries separate repository-gate timing from runner setup; wall-clock values diagnose runner/cache variance, while selected scopes, matrix captures, producer launches, documentation file counts, and full-scan counts are structural gates.
+
+## Resource-sensitive fast validation
+
+The authoritative fast-tier declaration identifies tests that repeatedly create temporary repositories, launch child processes, mutate storage, or coordinate release cohorts. The planner removes those files from the parallel remainder and runs them exactly once as `vitest-fast-resource-sensitive` with file parallelism disabled. Pull-request, development-package, and complete release plans use the same partition on every platform.
+
+The partition retains Vitest's five-second default test timeout. It does not add a test, suite, platform, or workflow timeout, and a failure is not retried or converted to success. If a serialized test still approaches five seconds, use `scripts/release/report-resource-sensitive-validation.mjs` to record repeated per-file and test-body timing, then optimize repository setup, subprocess count, storage operations, or release fixtures. Do not increase a timeout to create margin.
+
+Inspect the partition without running tests:
+
+```sh
+node scripts/release/run-validation-tier.mjs fast --plan
+```
+
+Record three focused serialized executions without running the complete fast tier:
+
+```sh
+node scripts/release/report-resource-sensitive-validation.mjs --repeats 3 --output .artifacts/validation/resource-sensitive-focused.json
+```
+
 ## Pull request integration
 
 `Development validation required` remains the merge gate for every pull request.
@@ -98,8 +142,7 @@ already exists it reports that version without dispatching package work. Otherwi
 it dispatches GitHub Actions, waits, and reports the published version. It never
 builds or uploads npm bytes from the workstation.
 
-Nightly resolves the same current `origin/develop` source. It always runs complete
-verification even if source has not changed. For a new number it packs once and
+Nightly resolves the same current `origin/develop` source. It runs one platform-independent full documentation review before the platform matrix, and the matrix records that prerequisite instead of repeating the scan four times. It always runs complete verification even if source has not changed. For a new number it packs once and
 runs the suite against that final-version tarball before publication. For an
 existing number it downloads the exact npm tarball and runs package/update gates
 against those registry bytes; publication is then a successful no-op.
@@ -155,6 +198,7 @@ Rules that do not bend:
   delete an advanced or protected ref merely because its name matches an old PR.
 - **Repository governance drifts:** run the read-only checker, review every reported
   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.

package/docs/manual-owned-ui-checkpoint.md

@@ -4,6 +4,8 @@ This checkpoint is user-controlled. Tests and coding agents must not launch or f
 
 ## Prepare an exact candidate
 
+For a checkout smoke test in Git Bash, build once and launch with `./scripts/dev` or `./scripts/dev pi`. Do not invoke `node scripts/development/dev-launch.mjs` or `node scripts/development/start-local.mjs` directly: that bypasses the color-preserving shell `exec` shape and can collapse the pinned 24-bit palette to Git Bash's 16 terminal colors. Run `node scripts/check-terminal-colour.mjs` first when color fidelity is in doubt; the first color block must differ from the terminal-palette cyan block.
+
 From the candidate checkout, pack once and install that tarball into a disposable prefix:
 
 ```powershell
@@ -46,6 +48,31 @@ Use the same terminal, working directory, dimensions, environment, and equivalen
 - [ ] Normal and error exits return a usable parent prompt.
 - [ ] Parent typing, cursor movement, Backspace, Delete, and submission work after exit.
 
-Report failures with bare-versus-comparison behavior, platform and terminal versions, exact command, reproducibility, and optional manually captured evidence.
+### Setting-controlled visual matrix
+
+Use equivalent values in bare A1 and the Pi comparison profile. Exercise both a wide frame and a narrow frame that forces wrapping/clipping.
+
+- [ ] `/settings`: selected cursor, label and value accent; unselected values muted; descriptions and hints dim; search uses `> ` with inverse cursor; scalar menus, numeric controls, warning-parts dialog, deferred notice, failed write, section spacing, clipping, and hidden-entry absence match their pinned semantic roles.
+- [ ] Transcript: toggle images and image width, thinking level/visibility, Mermaid mode, output padding, cache notices, warnings, auto-compaction, queue modes, command autocomplete, provider timeout/retry/error, and changelog collapse. Existing and streaming blocks must re-render without focus, selection, scroll, or queued-work loss.
+- [ ] Trust startup: from an undecided project, compare selected Trust/Do not trust rows, arrow navigation, Enter, Escape/Ctrl+C, clearing, cursor state, and restoration. No project extension/theme/prompt/skill may run before selection, and a fail-closed diagnostic must appear once on the restored parent rather than above a blank fullscreen frame.
+- [ ] Terminal lifecycle: toggle hardware cursor, clear-on-shrink, and terminal progress; resize smaller/larger; open/close selectors; select and copy transcript text; verify no duplicate rows, stale OSC progress, leaked mouse mode, misplaced cursor, or broken parent input.
+- [ ] Images: in Kitty or iTerm2 verify inline width and clipping; in Windows Terminal verify the textual fallback and absence of image protocol bytes without hiding `showImages`.
+- [ ] Fullscreen exit `transcript`: verify the parent is restored before styled user, assistant Markdown, thinking, tool, notice, warning, error, and spacing rows are printed. No overlay, draft, animation, scrollbar, or inline-image payload may appear.
+- [ ] Fullscreen exit `resume-hint`: verify only dim `To resume this session:` plus `a1 --session <compact-id>` is printed for the default directory. A custom directory must place quoted `--session-dir <dir>` before `--session`; the raw default `.jsonl` path must never print.
+
+Record acceptance with:
+
+```text
+A1 commit/tarball:
+Pi package: @earendil-works/pi-coding-agent 0.84.2
+OS/version:
+Terminal/version:
+Terminal dimensions (wide/narrow):
+Image protocol result:
+Settings values exercised:
+Outcome and any declared substitutions:
+```
+
+Report failures with bare-versus-comparison behavior, platform and terminal versions, exact command, dimensions, settings values, reproducibility, and optional manually captured evidence.
 
 For recovery, use `a1 pi`; do not use the removed `a1 ui` command. Manual acceptance can authorize an exact uncertified development preview after non-desktop gates pass. It does not certify stable presentation parity or platform support.

package/docs/manual-terminal-colour-check.md

@@ -29,9 +29,10 @@ leave the launch without a terminal on its input; the launcher says so and stops
 rather than opening a session that closes as it starts. Running `scripts/dev`
 from the shell is the direct path.
 
-A directly launched `node scripts/development/start-local.mjs` under Git Bash does not, and
-neither does a directly launched `node …/pi/dist/cli.js`: the collapse belongs to
-the launch, not to either application.
+A directly launched `node scripts/development/dev-launch.mjs` or
+`node scripts/development/start-local.mjs` under Git Bash does not, and neither
+does a directly launched `node …/pi/dist/cli.js`: the collapse belongs to the
+launch, not to either application.
 
 ## Checking a terminal
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.182",
+  "version": "0.1.8-dev.218",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",
@@ -27,6 +27,9 @@
     "build:process-guardian": "node scripts/development/build-process-guardian.mjs",
     "typecheck": "tsgo -p tsconfig.json --noEmit",
     "check:architecture": "node scripts/governance/check-architecture.mjs && node scripts/governance/product-identifier-policy.mjs --check && node scripts/governance/check-product-identity-boundaries.mjs && node scripts/governance/check-package-identity.mjs && node scripts/governance/check-pinned-pi-source-ledger.mjs && node scripts/governance/check-terminal-host-provenance.mjs",
+    "check:code-documentation": "node scripts/governance/check-code-documentation.mjs --mode full",
+    "check:code-documentation:changed": "node scripts/release/run-changed-documentation.mjs",
+    "select:validation-impact": "node scripts/release/select-validation-impact.mjs",
     "check:customization-ready": "node scripts/governance/check-owned-ui-customization-prerequisites.mjs",
     "check:deprecated": "node scripts/governance/check-deprecated-dependencies.mjs",
     "check:docs-governance": "node scripts/governance/check-docs-governance.mjs",
@@ -36,13 +39,15 @@
     "develop": "node scripts/development/develop.mjs",
     "release": "node scripts/release/release.mjs",
     "test": "npm run test:fast",
-    "test:fast": "node scripts/release/run-validation-tier.mjs typecheck fast",
+    "test:fast": "node scripts/release/run-validation-tier.mjs typecheck documentation-changed fast",
     "test:scope": "node scripts/release/run-validation-tier.mjs",
     "test:full": "node scripts/release/run-validation-tier.mjs full-release",
     "test:release": "node scripts/release/run-release-gates.mjs",
     "test:terminal-host": "node scripts/development/run-terminal-host-probe.mjs",
     "test:pi-engine-conformance": "vitest run test/integrations/pi/engine/conformance.test.ts test/integrations/pi/engine/runtime-integration.test.ts test/integrations/pi/engine/session-integration.test.ts",
     "report:pi-engine-conformance": "npm run build --silent && node scripts/pi/run-pi-engine-conformance.mjs",
+    "report:rendering-stability": "tsx scripts/pi/report-rendering-stability.ts",
+    "report:input-responsiveness": "tsx scripts/pi/report-input-responsiveness.ts",
     "sync:pi-ui": "npm run update:pi-component-parity && npm run update:pi-event-frame-parity && npm run update:pi-settings-metadata",
     "update:pi-component-parity": "tsx scripts/pi/update-pi-component-parity.ts",
     "update:pi-event-frame-parity": "tsx scripts/pi/update-pi-event-frame-parity.ts",