@kontextmind/kxm 0.7.94 → 0.7.96

package/docs/assignment-runner.md

@@ -1,264 +0,0 @@
-# Assignment runner maintainer guide
-
-> **Status.** The assignment runner (`scripts/assignment-run.mjs`, `just assign`)
-> is the developer orchestration policy and verification runner for issue 127.
-> It manages native developer assignments, deterministic witness verification,
-> and multi-vendor dual-critic acceptance. It is not the runtime workflow
-> engine (`kxm run`), an agent RPC worker (`kxm agent worker`), or a Phase 11
-> dispatch adapter.
-
-This guide explains how maintainers run, verify, attribute, and accept
-assignments, as well as the safety invariants enforced by the developer roster
-policy.
-
----
-
-## 1. Overview and role rotation
-
-Developer orchestration on this runner uses a role-based rotation backed by
-trusted policy in [`.kxm/roster.yaml`](../.kxm/roster.yaml). Roles, harnesses,
-and models are admitted with strict permission and vendor boundaries:
-
-| Role | Admitted route | Vendor | Permission | Purpose |
-|---|---|---|---|---|
-| **`writer`** | `grok` / `grok-4.6`, `pi` / `openrouter/qwen/qwen3-coder-plus` | `xai`, `alibaba` | `edit` | Native code authoring. Grok is the default rotation; Qwen on Pi is admitted relief. |
-| **`planner`** | `claude` / `fable` | `anthropic` | `read-only` | Architectural planning and permission boundaries. |
-| **`reviewer-arch`** | `claude` / `fable` | `anthropic` | `read-only` | Architecture, permission, and safety review. |
-| **`reviewer-cli`** | `codex` / `gpt-5.6-sol` | `openai` | `read-only` | CLI surface, documentation, and interface review. |
-
-### Core principles
-
-- **Independent critics:** Acceptance requires independent review from
-  different providers. The writer and each critic must have distinct canonical
-  vendors (`xai` / `alibaba`, `anthropic`, `openai`).
-- **Fail-closed dispatch:** Route validation fails closed with `route_invalid` if
-  a requested harness/model is not in the admitted role lineup, or if permissions
-  exceed the admitted ceiling (e.g. attempting to give edit permissions to a
-  read-only reviewer).
-- **Trusted roster policy:** Dispatch (`assign` / `run`) and accept load
-  `.kxm/roster.yaml` through the trusted control Git loader
-  (`loadTrustedRosterPolicy`). Loader errors, missing/empty policy, and
-  malformed policy fail closed with `route_invalid`. There is no raw working-tree
-  JSON fallback and no null-policy acceptance. Tests may inject an explicit
-  policy object; that seam is not a CLI or environment bypass. The witness
-  verifies the bound candidate against the fixed gate (`npm run verify`) and
-  does not itself call the policy loader today. Unified YAML
-  role/project/workflow authority is still open and is not this runner's live
-  source. Passive `schemas/policy-draft` / `validatePolicyDraft` scaffolding is
-  not operator settings and is not admission.
-- **Deterministic witness beats extra models:** Implementers run `npm run verify`.
-  Root re-runs the fixed witness. Reviewers verify candidate trees; they do not
-  replace tests.
-- **Closed schemas:** `accepted.json` (`kxm.task-accepted.v1`) and
-  `completion.json` (`kxm.assignment-completion.v1`) schemas are closed. Do not
-  add ad-hoc properties.
-
----
-
-## 2. The developer loop
-
-> **Environment.** These recipes do **not** auto-load a `.env` from the working
-> directory, and neither the source text nor `just --dump` is allowed to enable it. An
-> untracked, gitignored file must not be able to set `NODE_OPTIONS`
-> and execute code before the runner validates anything — `just --dotenv-path /abs/.env assign …` is the explicit
-> opt-in (`--dotenv-path` both selects and locates the file in `just` 1.58). Arguments are passed
-> positionally and quoted, so a path is never re-read as shell source; the runner's
-> absolute-path requirement is a separate validation rule, not what makes quoting
-> safe. `accept` prints JSON by default but takes no `--json` flag, and its optional
-> `--observed-pr` / `--observed-ci` need the direct script form shown in Step 5.
-
-The standard progression follows a slim four-step lifecycle:
-
-```text
-plan-current ──> assign (writer) ──> witness ──> review (arch + cli) ──> accept
-```
-
-Do not run the 13-stage `/fix` workflow for daily developer tasks or docs.
-
-### Step 1: Current plan pointer
-
-Every assignment binds to an explicit plan reference. When working against the
-active plan, stamp or update the pointer:
-
-```bash
-just plan-current /abs/task-dir /abs/plan.md <sha256> <base-commit> <expected-generation>
-```
-
-The pointer is recorded as `plan-current.json` (`kxm.plan-pointer.v1`) in the
-task directory.
-
-### Step 2: Dispatch assignment
-
-Create an assignment manifest (`kxm.assignment.v1`) specifying the task id,
-assignment id, kind (`implement`, `review-arch`, `review-cli`), admitted route,
-clean or staged base commit, and deliverables contract.
-
-Dispatch using:
-
-```bash
-just assign /absolute/path/to/manifest.json
-```
-
-Under the hood:
-
-```bash
-node scripts/assignment-run.mjs run --manifest /absolute/path/to/manifest.json
-```
-
-- Manifest validation asserts worktree cleanliness and validates the route
-  against `.kxm/roster.yaml`.
-- Headless execution dispatches to the native harness (or OpenRouter via Pi for
-  admitted relief).
-- Successful runs write `completion.json`, candidate snapshot metadata, and
-  private sidecars under the assignment record directory.
-
-### Step 3: Run the verification witness
-
-After the writer completes code changes, execute the fixed verification
-witness:
-
-```bash
-just witness /absolute/path/to/record-dir
-```
-
-Under the hood:
-
-```bash
-node scripts/assignment-run.mjs witness --record-dir /absolute/path/to/record-dir
-```
-
-The witness executes the fixed gate (`npm run verify`) in the workspace, hashes
-the index and worktree states, and records `witness-receipt.json`
-(`kxm.assignment-witness.v1`). Acceptance requires a witness receipt with
-`result: "passed"`.
-
-### Step 4: Dispatch critics
-
-Dispatch both designated critics against the candidate index tree:
-
-1. **Architecture review (`review-arch`):** Claude Fable (`fable`, read-only).
-2. **CLI & docs review (`review-cli`):** Codex Sol (`gpt-5.6-sol`, read-only).
-
-Each review produces its own record directory containing `completion.json` with
-a structured critic verdict (`PASS` or `BLOCK`) bound to the reviewed tree.
-
-### Step 5: Acceptance
-
-Once the writer passes the witness, changes are committed to Git, and both
-critics have rendered `PASS` verdicts:
-
-```bash
-just accept /abs/task-dir <commit-sha> /abs/writer-record /abs/arch-review /abs/cli-review
-```
-
-Under the hood:
-
-```bash
-node scripts/assignment-run.mjs accept \
-  --task-dir /abs/task-dir \
-  --commit <commit-sha> \
-  --record-dir /abs/writer-record \
-  --critic /abs/arch-review \
-  --critic /abs/cli-review \
-  [--observed-pr <pr-id>] \
-  [--observed-ci <ci-id>]
-```
-
-`accept` validates all acceptance invariants:
-
-1. Trusted roster policy is loaded and valid **before** acceptance artifacts are
-   written. Failure to obtain required policy refuses acceptance.
-2. The commit exists and its tree matches the witness index tree.
-3. The writer record matches the latest passed witness.
-4. Both required critic roles (`review-arch` and `review-cli`) are present.
-5. Both critics judged the exact accepted tree and issued `PASS`.
-6. No unresolved `BLOCK` review exists for the tree in the task directory (unless
-   superseded by an unbroken `rework_of` lineage).
-7. The writer and all critics satisfy pairwise vendor independence.
-8. Writes `accepted.json` (`kxm.task-accepted.v1`) into the task directory.
-
----
-
-## 3. Attribution and cost tracking
-
-### Private attribution notes
-
-When friction, environment issues, or model regressions occur, record private
-handoff notes without altering closed completion schemas:
-
-```bash
-just attribute /abs/task-dir /abs/record-dir <class> /abs/note.txt
-```
-
-- Allowed classifications: `orchestration`, `model`, `environment`,
-  `unclassified`.
-- Appends an immutable attribution entry in the task's attribution history.
-
-### Historical cost observation
-
-For manual bootstrap runs or unmetered subscription sessions where native
-telemetry was not captured directly:
-
-```bash
-just observe-cost /abs/task-dir /abs/observation.json
-```
-
-Imports a `kxm.cost-observation.v1` record. Cost observations are strictly
-cost-only; they cannot authorize acceptance or mint witness proof.
-
-### Unified change report
-
-Generate a consolidated change and cost summary for a task:
-
-```bash
-just change-report /abs/task-dir
-```
-
-The change report cleanly separates:
-
-- Provider-reported metered spend vs list price estimates.
-- Unmetered subscriptions (e.g. Claude Code or Codex subscription) vs unknown.
-- Token counts, elapsed wall time, witness durations, and attempt counts.
-- Failed or interrupted attempts (never silently omitted or zeroed).
-
----
-
-## 4. Safety invariants and failure codes
-
-The runner fails closed with bounded error codes defined in `RUNNER_CODES`:
-
-| Code | Trigger condition | Remedy |
-|---|---|---|
-| `route_invalid` | Harness/model not admitted in lineup for the requested role, permission exceeds route ceiling, or trusted roster policy cannot be loaded/validated. | Use a trusted clean control checkout; do not dispatch from a dirty implementation branch. Check `.kxm/roster.yaml` lineup and permissions for the role. |
-| `critic_invalid` | Missing required critic role, duplicate roles, wrong model, or vendor collision between writer and critics. | Ensure independent critics (Fable + Sol) from distinct providers. |
-| `critic_block` | An unresolved `BLOCK` verdict exists for the target tree. | Rework the changes, address findings, and pass review with a `rework_of` link. |
-| `commit_tree_mismatch` | Git commit tree does not equal the witnessed tree. | Commit the exact candidate tree verified by the witness before running accept. |
-| `witness_failed` | Fixed gate (`npm run verify`) returned a non-zero exit code. | Fix code, typecheck, lint, or test failures and re-witness. |
-| `witness_binding_invalid` | Writer transport incomplete, wrong deliverables boundary, or writer route unadmitted. | Re-run writer assignment through admitted rotation route. |
-| `accepted_exists` | `accepted.json` is already present in the task directory. | Acceptance records are immutable; use a new task directory for new units. |
-
----
-
-## 5. File layout in task directories
-
-A completed task directory contains:
-
-```text
-<task-dir>/
-├── plan-current.json            # Active plan pointer (kxm.plan-pointer.v1)
-├── plan-current.md              # Current plan markdown
-├── accepted.json                # Final acceptance proof (kxm.task-accepted.v1)
-├── asg-writer-1/                # Writer assignment record directory
-│   ├── manifest.json            # Bound input manifest (kxm.assignment.v1)
-│   ├── prompt.txt               # Rendered assignment prompt
-│   ├── completion.json          # Completion record (kxm.assignment-completion.v1)
-│   ├── witness-receipt.json     # Deterministic gate witness receipt
-│   └── telemetry.jsonl          # Usage, latency, and cost telemetry
-├── asg-review-arch/             # Architecture critic record directory
-│   ├── manifest.json
-│   └── completion.json          # Contains critic PASS verdict
-├── asg-review-cli/              # CLI critic record directory
-│   ├── manifest.json
-│   └── completion.json          # Contains critic PASS verdict
-└── runner-errors.jsonl          # Diagnostic log of bounded failure codes
-```

package/docs/browser-automation.md

@@ -1,139 +0,0 @@
----
-schema: "kxm.doc.v1"
-id: "GUIDE-BROWSER-001"
-type: "guide"
-title: "KXM Browser Automation Guide"
-project: "kxm"
-status: "accepted"
-owner: "@operator"
-created: "2026-09-14"
-updated: "2026-09-15"
-authority: "instruction"
-confidence: "verified"
-summary: "Comprehensive guide to browser automation in KXM using self-hosted Steel on DOKS, agent-browser, Playwright, pass-cli, and human takeover."
-tags: ["browser", "automation", "steel", "playwright", "agent-browser", "doks"]
-related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/agent-skills.md"]
----
-
-# KXM Browser Automation Guide
-
-This guide describes how to use KXM's browser automation capability powered by self-hosted Steel on DigitalOcean Kubernetes (DOKS), `agent-browser` for exploratory inspection, `Playwright` for automated regression testing, and `pass-cli` for credential security.
-
----
-
-## 1. Architecture & Trust Boundaries
-
-```text
-Herdr / Pi / Agent Harness
-  │
-  ├──► KXM Browser Skills & Prompts (kxm-browser-*)
-  │
-  ├──► pass-cli (Authoritative Vault: "AI Provider Keys")
-  │
-  ├──► agent-browser (Exploratory CLI) ──┐
-  │                                      │ (CDP WebSocket)
-  ├──► Playwright (E2E Test Suites) ────┼──► DOKS Steel Browser Cluster
-  │                                      │   (https://steel.kontextmind.com)
-  └──► Human Operator (Takeover UI) ─────┘   (https://steel.kontextmind.com/ui)
-```
-
-### Key Components
-
-1. **Steel on DOKS (`https://steel.kontextmind.com`)**:
-   - Primary browser execution environment.
-   - Isolated Chromium containers with dedicated shared memory (`/dev/shm`).
-   - Exposed endpoints: REST API (port 443 / 3000), CDP WebSocket proxy (port 443 / 9223), Web UI (`/ui`), OpenAPI docs (`/documentation`).
-2. **`pass-cli`**:
-   - The authoritative store for all long-lived passwords, session tokens, and the `STEEL_API_KEY`.
-   - Never write credentials to tracked git files.
-3. **`agent-browser`**:
-   - Fast, token-efficient terminal CLI for accessibility snapshots, interactive navigation, and exploratory testing.
-4. **`Playwright`**:
-   - High-fidelity assertion engine for bug reproduction, visual proofs, and permanent regression suites.
-
----
-
-## 2. Getting Started: The First Browser Workflow
-
-### Step 1: Verify Prerequisites
-
-Check that `pass-cli` can access the Steel configuration:
-
-```bash
-pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)"
-```
-
-### Step 2: Launch a Steel Browser Session
-
-```bash
-STEEL_KEY=$(pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --field STEEL_API_KEY)
-
-# Create a 5-minute session
-SESSION_RESP=$(curl -s -X POST https://steel.kontextmind.com/v1/sessions \
-  -H "Content-Type: application/json" \
-  -H "x-steel-api-key: $STEEL_KEY" \
-  -d '{"timeout": 300000}')
-
-SESSION_ID=$(echo "$SESSION_RESP" | jq -r .id)
-echo "Session created: $SESSION_ID"
-```
-
-### Step 3: Run Exploratory Automation or Scrapes
-
-To run a fast scrape without managing sessions:
-
-```bash
-curl -s -X POST https://steel.kontextmind.com/v1/scrape \
-  -H "Content-Type: application/json" \
-  -H "x-steel-api-key: $STEEL_KEY" \
-  -d '{"url": "https://example.com"}'
-```
-
-### Step 4: Release the Session
-
-```bash
-curl -s -X POST https://steel.kontextmind.com/v1/sessions/$SESSION_ID/release \
-  -H "x-steel-api-key: $STEEL_KEY"
-```
-
----
-
-## 3. Human Takeover Protocol
-
-When authentication challenges (MFA, CAPTCHA, SSO) are encountered:
-
-1. **Agent Pauses**: The agent stops automated actions and sets state to `HUMAN_CONTROL`.
-2. **Emits Link**: Emits the protected URL: `https://steel.kontextmind.com/ui?sessionId=<SESSION_ID>`.
-3. **Human Interacts**: The operator opens the session viewer, completes the login/MFA action, and confirms in the terminal (`auth complete`).
-4. **Agent Verifies**: The agent inspects the resulting page, confirms dashboard/user state, refreshes DOM observations, and returns to `AGENT_CONTROL`.
-
----
-
-## 4. Resource Controls & Cost Safety
-
-- **Session Timeouts**: Default 300s (5m), max 1800s (30m). Sessions terminate automatically on expiry.
-- **Orphan Sweeping**: Periodically sweep untracked sessions via `GET /v1/sessions` and release idle processes.
-- **Memory Protection**: Kubernetes mounts a 2Gi `emptyDir` memory volume at `/dev/shm` to prevent Chromium tab crashes without exhausting node memory.
-
----
-
-## Knowledge base
-
-- [How are credentials retrieved without exposing them to the model?](kb/how-credentials-retrieved-safely.md)
-- [How do I capture a UI section and annotate changes for an agent?](kb/how-to-capture-and-annotate-section.md)
-- [How do I connect Playwright to the existing Steel session?](kb/how-to-connect-playwright-to-steel.md)
-- [How do I recover an expired session or remove an orphaned browser?](kb/how-to-recover-expired-session-or-orphan.md)
-- [How does an agent resume after MFA?](kb/how-to-resume-after-mfa.md)
-- [How do I take over a browser session to log in?](kb/how-to-take-over-session.md)
-- [Why did authentication disappear?](kb/why-authentication-disappeared.md)
-- [Why did automation open a different browser?](kb/why-automation-opened-different-browser.md)
-- [Why can I view a session but not control it?](kb/why-session-viewer-cannot-control.md)
-
-## Prompt templates
-
-- [Starting browser work](prompts/browser-start.md)
-- [Exploring an application](prompts/browser-explore.md)
-- [Requesting human takeover](prompts/browser-takeover.md)
-- [Diagnosing and recovering a failed session](prompts/browser-diagnose-recover.md)
-- [Reproducing a UI bug and writing a Playwright test](prompts/browser-repro-fix.md)
-- [Capturing UI section annotations](prompts/browser-annotate-feedback.md)