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

package/dist/ui/settings/session.js

@@ -1,9 +1,6 @@
+import { assertAgentSettingDescriptor } from "../../contracts/agent-engine/index.js";
 import { buildOwnedUiSettingsSections, findOwnedUiSettingsEntry, } from "./sections.js";
-/**
- * Holds the resolved settings for one owned UI session and routes every accepted
- * change to the backend that owns it: A1 settings to the A1 document, agent
- * settings to the engine settings port. Neither backend ever sees the other's value.
- */
+/** Routes every accepted setting change only to its owning backend. */
 export class OwnedUiSettingsSession {
     #store;
     #agent;
@@ -23,21 +20,18 @@ export class OwnedUiSettingsSession {
     get resolution() {
         return this.#resolution;
     }
-    /** Reads the engine's settings so the Agent section can be built. Never throws. */
     async load() {
         this.#resolution = this.#store.read();
-        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
+        const agent = this.#currentAgent();
         this.#agentSnapshot = agent === null ? null : await snapshotOf(agent, this.#hiddenAgentSettingIds);
         this.#notify();
     }
     sections() {
         return buildOwnedUiSettingsSections({ resolution: this.#resolution, agent: this.#agentSnapshot });
     }
-    /** Resolved value of an A1 setting, or null when it is not declared. */
     value(id) {
         return this.#resolution.settings.find(setting => setting.declaration.id === id)?.value ?? null;
     }
-    /** Value stored this session but not yet in effect, for a restart-required setting. */
     pendingValue(id) {
         return this.#pending.get(id) ?? null;
     }
@@ -45,35 +39,18 @@ export class OwnedUiSettingsSession {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
     }
-    /** Writes a structured value, which only an engine-backed setting can hold. */
     async changeStructured(backend, id, value) {
         if (backend !== "agent")
             return failed("only an agent setting holds a structured value");
-        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
-        if (agent === null)
-            return failed("no agent engine is attached");
-        if (!agent.capabilities.write || !agent.writeSetting) {
-            return failed("the agent engine does not support changing settings from this surface");
-        }
-        try {
-            await agent.writeSetting(id, value);
-            if (agent.capabilities.flush && agent.flush)
-                await agent.flush();
-        }
-        catch (error) {
-            return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
-        }
-        this.#agentSnapshot = await snapshotOf(agent, this.#hiddenAgentSettingIds);
-        this.#notify();
-        return { applied: true, pendingRestart: false, failure: null };
+        return await this.#changeAgentValue(id, value);
     }
     async change(backend, id, value) {
         const entry = findOwnedUiSettingsEntry(this.sections(), id, backend);
         if (entry === null)
             return failed(`unknown ${backend} setting: ${id}`);
         if (!entry.editable)
-            return failed(`${id} is not editable from this surface`);
-        return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgent(id, value);
+            return failed(entry.limitationReason ?? `${id} is not editable from this surface`);
+        return backend === "a1" ? this.#changeOwned(id, value) : await this.#changeAgentValue(id, value);
     }
     #changeOwned(id, value) {
         const outcome = this.#store.write(this.#resolution, id, value);
@@ -81,35 +58,39 @@ export class OwnedUiSettingsSession {
             return failed(outcome.failure ?? `${id} could not be stored`);
         const previous = this.#resolution;
         this.#resolution = this.#store.read();
-        const declaration = previous.settings.find(setting => setting.declaration.id === id)?.declaration;
-        if (declaration?.application === "restart") {
+        const previousSetting = previous.settings.find(setting => setting.declaration.id === id);
+        if (previousSetting?.declaration.application === "restart") {
             this.#pending.set(id, value);
             this.#resolution = previous;
             this.#notify();
-            return { applied: false, pendingRestart: true, failure: null };
+            return changed("deferred", "next-start", value, previousSetting.value);
         }
         this.#pending.delete(id);
         this.#notify();
-        return { applied: true, pendingRestart: false, failure: null };
+        return changed("applied", "live", value, value);
     }
-    async #changeAgent(id, value) {
-        const agent = this.#agentProvider === null ? this.#agent : this.#agentProvider();
+    async #changeAgentValue(id, value) {
+        const agent = this.#currentAgent();
         if (agent === null)
             return failed("no agent engine is attached");
         if (!agent.capabilities.write || !agent.writeSetting) {
             return failed("the agent engine does not support changing settings from this surface");
         }
+        let result;
         try {
-            await agent.writeSetting(id, value);
-            if (agent.capabilities.flush && agent.flush)
-                await agent.flush();
+            // The coordinator behind the port owns effect installation, persistence,
+            // flush, and rollback. A second surface-level flush would split authority.
+            result = await agent.writeSetting(id, value);
         }
         catch (error) {
             return failed(`${id} could not be written to the agent engine: ${describe(error)}`);
         }
         this.#agentSnapshot = await snapshotOf(agent, this.#hiddenAgentSettingIds);
         this.#notify();
-        return { applied: true, pendingRestart: false, failure: null };
+        return fromAgentOutcome(result);
+    }
+    #currentAgent() {
+        return this.#agentProvider === null ? this.#agent : this.#agentProvider();
     }
     #notify() {
         for (const listener of this.#listeners)
@@ -118,29 +99,55 @@ export class OwnedUiSettingsSession {
 }
 async function snapshotOf(agent, hidden) {
     try {
-        const descriptors = (await agent.listSettings()).filter(descriptor => !hidden.has(descriptor.key));
-        const values = {};
-        for (const descriptor of descriptors) {
-            try {
-                values[descriptor.key] = await agent.readSetting(descriptor.key) ?? null;
-            }
-            catch {
-                values[descriptor.key] = null;
-            }
-        }
+        const listed = await agent.listSettings();
+        for (const descriptor of listed)
+            assertAgentSettingDescriptor(descriptor);
+        const descriptors = listed.filter(descriptor => !hidden.has(descriptor.key));
         return {
             descriptors,
-            values,
             writeAdvertised: agent.capabilities.write && typeof agent.writeSetting === "function",
             failure: null,
         };
     }
     catch (error) {
-        return { descriptors: [], values: {}, writeAdvertised: false, failure: describe(error) };
+        return { descriptors: [], writeAdvertised: false, failure: describe(error) };
     }
 }
 function failed(failure) {
-    return { applied: false, pendingRestart: false, failure };
+    return {
+        status: "failed",
+        applied: false,
+        pendingRestart: false,
+        application: null,
+        storedValue: null,
+        effectiveValue: null,
+        limitationReason: null,
+        failure,
+    };
+}
+function changed(status, application, storedValue, effectiveValue) {
+    return {
+        status,
+        applied: status === "applied",
+        pendingRestart: status === "deferred" && application === "next-start",
+        application,
+        storedValue,
+        effectiveValue,
+        limitationReason: null,
+        failure: null,
+    };
+}
+function fromAgentOutcome(result) {
+    return {
+        status: result.status,
+        applied: result.status === "applied",
+        pendingRestart: result.status === "deferred" && result.application === "next-start",
+        application: result.application,
+        storedValue: result.storedValue,
+        effectiveValue: result.effectiveValue,
+        limitationReason: result.limitationReason,
+        failure: result.failure,
+    };
 }
 function describe(error) {
     return error instanceof Error ? error.message : String(error);

package/docs/architecture/project-structure.md

@@ -86,6 +86,20 @@ The repository has one root `package.json`, `package-lock.json`, TypeScript conf
 
 Build output mirrors the production namespaces directly under ignored `dist/`, without an intermediate `src/` directory; release and test evidence belongs in ignored `.artifacts/`; temporary agent work belongs in ignored `.worktrees/` and `.builds/`. Repository tooling is grouped under `scripts/governance`, `scripts/release`, `scripts/pi`, and `scripts/development`; the few root scripts are standalone maintenance or build commands. Package contents are selected by the root manifest. The Rust process guardian and console terminal-host proof live under `native/`; Cargo output is ignored. Third-party terminal parser sources are isolated under `native/terminal-host/vendor/` and are not owned application modules.
 
+## Development worktrees
+
+Every task worktree must be created at `{working-dir}/.worktrees/<task-id>`, where `{working-dir}` is the agent session's initial working directory. The `.worktrees` directory is inside that working directory, not beside it. For working directory `D:/Git/a1`, `D:/Git/a1/.worktrees/<task-id>` is correct and `D:/Git/a1-<task-id>` is forbidden.
+
+From the initial working directory, create and address a task worktree explicitly:
+
+```sh
+git fetch origin develop
+git worktree add --detach .worktrees/<task-id> origin/develop
+git -C .worktrees/<task-id> status
+```
+
+The primary worktree stays on `develop` for integration and must not be used for task edits. Do not edit, move, or remove another session's worktree.
+
 ## Documentation and comments
 
 - README explains installation, commands, and current limitations.

package/docs/ci-release-runbook.md

@@ -12,6 +12,33 @@ GitHub Actions is the only automation platform. Three refs are protected:
 channel. The workflow starts at `03:17 UTC` for nightly development verification,
 or by explicit dispatch from `npm run develop` or `npm run release`.
 
+`.github/workflows/documentation-auto-merge.yml` is the only pull-request
+auto-merge authority. It runs trusted policy from `develop`; it never checks out or
+executes a pull request's code with its write token.
+
+`.github/workflows/merged-branch-cleanup.yml` owns branch deletion after a human or
+external actor closes a pull request. On the close event it checks out trusted
+default-branch policy and installs no pull-request dependencies. GitHub does not
+emit a new workflow event for a merge authored with the workflow `GITHUB_TOKEN`, so
+Documentation auto-merge also performs the same shared reconciliation synchronously
+after its own validated integration. Both paths delete only an unprotected same-
+repository topic ref whose live object still equals the merged pull request head SHA.
+An absent ref is success; fork, unmerged, advanced, protected, default, release-owned,
+or malformed refs are preserved and reported.
+
+`config/github-repository-governance.json` is the reviewed policy for repository
+settings, Actions defaults, security capabilities, environments, complete rulesets,
+protected refs, and workflow authority. Inspection is read-only by default:
+
+```sh
+node scripts/governance/check-github-repository-governance.mjs --check
+```
+
+Applying reviewed mutable drift is a separate maintainer operation requiring
+`--apply --confirm apply-a1-github-governance` and a matching post-apply read.
+Secrets and external npm trusted-publisher configuration are capability checks, not
+serialized credentials.
+
 `develop` is where work lands. `master` records what npm `latest` serves and is an
 effect of stable publication, not a trigger.
 
@@ -19,12 +46,41 @@ effect of stable publication, not a trigger.
 
 | Trigger | Validation and outcome |
 | --- | --- |
-| Pull request into `develop` | Fast required validation; docs/spec-only changes use strict OpenSpec validation |
+| Pull request into `develop` | Fast required validation; docs-only changes use lightweight governance consistency and OpenSpec changes also use strict OpenSpec validation |
 | `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 |
 | `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 |
 
+## Pull request integration
+
+`Development validation required` remains the merge gate for every pull request.
+Documentation auto-merge reads the complete GitHub changed-file response and arms
+squash auto-merge for an eligible pull request while required validation is pending;
+branch protection prevents integration until `Development validation required`
+succeeds. If validation finishes before auto-merge can be armed and GitHub already
+reports the pull request clean, the reconciler squash-merges only the validated head
+SHA. Every current and renamed-from path must be under `openspec/**`, under
+`docs/**`, or exactly the root `README.md`. Eligible pull requests must use a
+non-draft branch in this repository and target `develop`.
+
+The exact allowlist covers maintained OpenSpec, architecture, feature, manual,
+runbook, and root README documentation. Other root Markdown files, `LICENSE`,
+`.gitignore`, source, tests, scripts, workflows, configuration, generated baselines,
+and mixed changes do not auto-merge. The guard also runs when a pull request changes
+or auto-merge is manually enabled; if any path is outside the allowlist, it disables
+auto-merge while leaving the pull request available for a later manual merge. Every
+docs-only change runs lightweight generated-governance consistency, so archiving an
+inventoried OpenSpec occurrence fails that pull request rather than a later code pull
+request. A legitimate generated baseline update remains outside the allowlist and
+follows the manually accepted mixed/code path.
+
+A specification request lands as an OpenSpec-only pull request. Implementation
+starts only after that specification merges and the maintainer explicitly requests
+it, in a fresh worktree and pull request based on updated `origin/develop`. Every
+code/operational pull request remains open after CI until the maintainer validates it
+locally and explicitly authorizes manual integration.
+
 ## Numbered development previews
 
 A merge or push to `develop` does not publish by itself. To request a deliberate
@@ -92,6 +148,13 @@ Rules that do not bend:
 ## When something fails
 
 - **PR validation fails:** fix the code and push; do not mark a failed tier optional.
+- **Documentation auto-merge fails:** leave the pull request open, inspect its exact
+  changed-file classification, docs-sensitive inventory, and workflow permissions,
+  and never broaden the allowlist to make one pull request pass.
+- **Merged-branch cleanup fails:** inspect the bounded PR/ref/SHA disposition. Never
+  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.
 - **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.
@@ -104,6 +167,8 @@ and resolved review threads, but zero approving reviews. `master` and release ta
 are written only after publication and are protected from force-push, movement, and
 deletion.
 
-Do not add direct-push bypasses. Ruleset mutation remains a separate administrative
-operation: inspect with `node scripts/governance/check-github-rulesets.mjs`, and apply only
-with explicit maintainer confirmation.
+Do not add direct-push bypasses. Approval count, strict-base validation, repository
+merge methods, Actions allowance/SHA enforcement, Dependabot, and npm environment
+protection remain explicit maintainer decisions; governance automation does not
+silently change them. Repository mutation remains a separate confirmed administrative
+operation through `check-github-repository-governance.mjs`.

package/docs/repository-governance-live-acceptance.md

@@ -0,0 +1,77 @@
+# Repository governance live acceptance
+
+## Implementation lifecycle
+
+- PR #165 was manually squash-merged by `timurproko` from validated head
+  `45aab61c5e4568d3d26dc970f76e9ec86918f323` to `develop` commit
+  `e4cdc67555e9f25d03f251be19baa8fc446ac313`.
+- Cleanup run `33185942656` used trusted `develop` policy with `contents: write` only
+  and reported `already-absent`; the implementation branch remained absent.
+- The read-only live governance report matched every declared field after merge.
+
+## Acceptance defect and correction
+
+- Initial OpenSpec probe PR #166 automatically squash-merged validated head
+  `c30c0a091a6a6a727057befcdd775422988be382` to
+  `f8d60080cfd9925b33a19a5d40c707637ac00b08`, but GitHub suppressed the recursive
+  close-event workflow because integration was authored with `GITHUB_TOKEN`.
+- Its exact unchanged branch remained, proving the first implementation incomplete.
+  The branch was manually deleted only after its expected SHA and lack of an open PR
+  were reverified.
+- Corrective PR #167 was manually squash-merged from validated head
+  `3a09042386df2501accc1eec3b424b94ae84daa4` to
+  `e8d639985a811f01cd5daeb027db5069d1724596`. Cleanup run `33188206793`
+  succeeded with `already-absent`.
+
+## Automatic OpenSpec acceptance
+
+- PR #168 contained only `openspec/**` paths.
+- Development validation run `33188285639` passed for exact head
+  `6678d9237ca7c4109beaed0d97d5fb1183fe5f97` without product tests.
+- `github-actions` automatically squash-merged it to
+  `c2fa730a4b070f9f6717329c24158def5c766f11`.
+- Trusted documentation reconciliation run `33188329123` reported `deleted` for the
+  same expected head SHA, and the remote branch was verified absent.
+
+## Automatic root README acceptance
+
+- PR #169 changed only root `README.md`.
+- Development validation run `33188400573` passed for exact head
+  `165c5159031d80059c4d93c36c6d10113ec7ba8e` without product tests.
+- `github-actions` automatically squash-merged it to
+  `0180088a42b7cdacaf84ec66ff5a87be1a697155`.
+- Trusted documentation reconciliation run `33188434277` reported `deleted` for the
+  same expected head SHA, and the remote branch was verified absent.
+
+## Mixed-path manual acceptance
+
+PR #170 combined this evidence file outside the exact automatic allowlist with an
+OpenSpec task update. Development validation run `33188542485` passed for exact head
+`b95bdbf08ad6db76c5fab2bfca254026a3c4bcc1` without product tests. Auto-merge
+remained disabled and the pull request remained open and mergeable until `timurproko`
+manually squash-merged it to `6ab1e4d29b9edec8501bac774bc755e66240ea40`.
+Close-event cleanup run `33188616709` reported `already-absent`, and the remote branch
+was verified absent after the explicit merge.
+
+## Automatic maintained-documentation acceptance
+
+- Implementation PR #180 was manually squash-merged after required validation from
+  head `8f40bfaaa5e8410e77b1c9cc0667c62bc4c62d4b` to
+  `45a59a7b696d537a4dc8fe62000a60c20e504ab2`.
+- PR #181 changes only this maintained `docs/**` file and is the live acceptance
+  probe for the expanded allowlist.
+- Acceptance requires current-head documentation validation, automatic squash
+  integration without maintainer merge action, and exact-head remote branch cleanup.
+  Exact run and merge evidence is recorded with the completed OpenSpec change.
+
+## Advanced-ref refusal and final policy state
+
+The isolated mocked-GitHub fixture executed the production shared reconciler with
+expected SHA `1111111111111111111111111111111111111111` and advanced live SHA
+`2222222222222222222222222222222222222222`. It returned `refused` with reason
+`live branch advanced after merge` and issued zero DELETE requests. The bounded
+record is archived as `evidence/advanced-ref-refusal.json`.
+
+The final read-only live report matched all declared repository settings, Actions
+policy, security capabilities, environments, protected refs, complete rulesets, and
+workflow inventory with zero differences. No policy apply was run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.157",
+  "version": "0.1.8-dev.182",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",
@@ -29,6 +29,8 @@
     "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: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",
+    "check:repository-governance": "node scripts/governance/check-github-repository-governance.mjs --check",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
     "check": "npm run test:fast",
     "develop": "node scripts/development/develop.mjs",
@@ -58,7 +60,8 @@
     "chalk": "5.6.2",
     "cross-spawn": "7.0.6",
     "grok-mermaid": "0.2.2",
-    "semver": "7.8.5"
+    "semver": "7.8.5",
+    "undici": "8.9.0"
   },
   "devDependencies": {
     "@types/cross-spawn": "6.0.6",