@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.34 → 0.1.37

package/packages/agent-settings/src/global-agents.ts

@@ -1,16 +1,16 @@
 /**
- * Deploy the canonical `packages/agent-settings/assets/GLOBAL-AGENTS.md` out
+ * Deploy the canonical `packages/agent-settings/assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md` out
  * to every AI-agent host's own global instruction file, so each host reads
  * the same content: `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`,
  * `~/.cursor/AGENTS.md`, `~/.kimi-code/AGENTS.md`,
  * `~/.config/opencode/AGENTS.md`.
  *
- * The canonical source is committed in this repo (`../assets/GLOBAL-AGENTS.md`
+ * The canonical source is committed in this repo (`../assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md`
  * relative to this file), not read from any other repo's checkout at
  * runtime — two different repos fighting over the same global target file is
  * exactly the collision this replaces.
  *
- * Ownership model: GLOBAL-AGENTS.md is the single source of truth for every
+ * Ownership model: TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md is the single source of truth for every
  * target. Deploy is always forced — there is no opt-out flag:
  *   - missing target        -> created from the source.
  *   - content === source    -> untouched (true no-op).
@@ -18,7 +18,7 @@
  *                              stale, both are drift). These exact files are
  *                              authoritative adl roots: replacement does
  *                              not retain a displaced copy.
- * Any change to a host's global instructions must go through GLOBAL-AGENTS.md.
+ * Any change to a host's global instructions must go through TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md.
  * Uninstall removes those same owned files regardless of their current bytes.
  */
 
@@ -31,6 +31,7 @@ import {
   rmSync,
   writeFileSync,
 } from 'node:fs'
+import { hostname as osHostname } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -47,7 +48,29 @@ export const AGENT_TARGETS: readonly AgentTarget[] = [
   { relativeDir: '.config/opencode', file: 'AGENTS.md' },
 ]
 
-export const DEFAULT_SOURCE_PATH = fileURLToPath(new URL('../assets/GLOBAL-AGENTS.md', import.meta.url))
+export const DEFAULT_SOURCE_PATH = fileURLToPath(new URL('../assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md', import.meta.url))
+
+export const DEFAULT_MANIFEST_PATH = fileURLToPath(new URL('../../fleet/manifest.json', import.meta.url))
+
+export type FleetScope = { readonly inFleet: true; readonly device: string } | { readonly inFleet: false; readonly note: string }
+
+export function deviceNameOf(hostname: string): string {
+  return hostname.split('.')[0] ?? hostname
+}
+
+// Fleet-only deploy rule and its rationale: README "Global agent instructions".
+export function resolveFleetScope(hostname: string, manifestPath: string): FleetScope {
+  let manifest: { mac?: { devices?: object }; linux?: { devices?: object } }
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch (cause) {
+    throw new Error(`cannot read fleet manifest ${manifestPath}: ${messageOf(cause)}`)
+  }
+  const device = deviceNameOf(hostname)
+  const names = [...Object.keys(manifest.mac?.devices ?? {}), ...Object.keys(manifest.linux?.devices ?? {})]
+  if (names.includes(device)) return { inFleet: true, device }
+  return { inFleet: false, note: `skipped: '${device}' is not a device in packages/fleet/manifest.json, so no global file is written` }
+}
 
 export type TargetState = 'missing' | 'matches' | 'drifted'
 
@@ -181,23 +204,35 @@ function readSource(sourcePath: string): string {
 }
 
 function usage(): never {
-  throw new Error('usage: global-agents --home ABSOLUTE_PATH --mode deploy|status|uninstall')
+  throw new Error('usage: global-agents --home ABSOLUTE_PATH --mode deploy|status|uninstall [--host NAME] [--manifest PATH]')
 }
 
-export function main(argv: readonly string[]): void {
+export function main(argv: readonly string[], hostname: string = osHostname()): void {
   let home = ''
   let mode = 'status'
+  let host = hostname
+  let manifest = DEFAULT_MANIFEST_PATH
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index]
     if (argument === '--home') home = argv[++index] ?? ''
     else if (argument === '--mode') mode = argv[++index] ?? ''
+    else if (argument === '--host') host = argv[++index] ?? ''
+    else if (argument === '--manifest') manifest = argv[++index] ?? ''
     else usage()
   }
-  if (home.length === 0 || !['deploy', 'status', 'uninstall'].includes(mode)) usage()
+  if (home.length === 0 || host.length === 0 || manifest.length === 0 || !['deploy', 'status', 'uninstall'].includes(mode)) usage()
 
   const sourceContent = readSource(DEFAULT_SOURCE_PATH)
 
+  if (mode !== 'uninstall') {
+    const scope = resolveFleetScope(host, manifest)
+    if (!scope.inFleet) {
+      console.log(`global-agents: ${scope.note}`)
+      return
+    }
+  }
+
   if (mode === 'status') {
     const statuses = inspectGlobalAgents(home, sourceContent)
     for (const status of statuses) console.log(`${status.state}: ${status.path}`)

package/packages/agent-skills/assets/adl-mechanics/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: adl-mechanics
+description: How agents reach Azure DevOps in an adl-controlled repository — agent identity, the git front controller, the adl MCP tools and their CLI fallback, repository-control hooks, and when `adl run` may start a sub-agent.
+---
+
+# adl mechanics
+
+How adl behaves on every machine and in every repository it controls.
+
+## Use When
+
+- You are about to run a git network command, open or update a PR, read or write a work item, or start a build.
+- A command is refused for identity, credentials or hooks, and you need to know why.
+- The operator asks you to start a sub-agent session with `adl run`.
+
+## Agent identity
+
+- Every Azure DevOps access (git, PRs, work items, builds, reads included) runs as an agent identity, never as the human. The default is the machine's default agent, set by fleet reconcile; it can always be overridden.
+- **Override:** prefix a command with `ADL_AGENT_ID_AGENT=<agent-id>`. An MCP tool call can't carry a prefix, so it uses the session environment or the machine default; the CLI fallback (`adl mcp cli <command>`) takes the prefix like any command.
+- Never read vault files. Never pass a token.
+- **Never set `ADL_HUMAN_AZDO`.** It is the owner's human-terminal marker for `git-ado`'s and `adl id whoami`'s fail-closed human pass-through (stdin is a TTY and `ADL_HUMAN_AZDO=1`, exactly). An agent carrying it would let a child process forge that pass-through.
+
+## Git and Azure DevOps operations
+
+- Use ordinary `git` for every Git operation. The managed `/usr/local/bin/git` front controller hands local and non-Azure DevOps work to the system Git, and routes HTTPS Azure DevOps network commands through `adl-agent-id exec --agent "$ADL_AGENT_ID_AGENT"`. `git-ado` handles the credential boundary; there is no second account or secret location.
+- PRs, work items and builds go through the `adl` MCP server (`adl mcp serve`): `pr_list_or_get`, `pr_create_or_update`, `pr_review`, `build_list_or_get`, `build_run`, `workitem_list_or_get`, `workitem_create_or_update`. If the server is not working, fall back to `adl mcp cli <command>`.
+
+## Repository controls
+
+- Run via `adl repo controls`. Git hooks run pre-commit (local checks) and pre-push (Azure DevOps governance).
+- Each repository is reconciled on its own, with its `.agents/`, `.claude/`, `.codex/`, `.cursor/`, `.kimi-code/` and `.opencode/` projections.
+
+## Sub-agent sessions (`adl run`)
+
+- Only on the operator's explicit request; an agent never starts one on its own. It is not an identity route and not a fallback for anything.
+- **Headless:** `adl run <surface> --headless "<prompt>"`, surface one of `claude`, `codex`, `opencode`, `kimi`, `cursor`.
+- **Identity:** add `--as <agent>`.
+- **Model:** add `--model <model>`. adl passes each surface's own flag (claude and cursor `--model`; codex, opencode and kimi `-m`); a surface without one refuses it (exit 2). `--model` cannot be combined with `adl run -- <cmd>`.

package/packages/agent-skills/assets/agent-search-tool-audit/scripts/audit.sh

@@ -92,7 +92,7 @@ run_ts = sys.argv[2]
 today = sys.argv[3]
 log_files = sys.argv[4:]
 
-cutoff = datetime.datetime.fromisoformat(today + "T00:00:00Z") - datetime.timedelta(days=days-1)
+cutoff = datetime.datetime.fromisoformat(today + "T00:00:00+00:00") - datetime.timedelta(days=days-1)
 
 # Per (host, day), tally. Dedupe by (ts, command, rule) within each log.
 per_host_day = collections.defaultdict(lambda: collections.Counter())

package/packages/agent-skills/assets/code-review/SKILL.md

@@ -1,100 +1,118 @@
 ---
 name: code-review
-description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
-disable-model-invocation: false
+description: Run a comprehensive code review
 ---
 
-# Code Review
-Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+# Code Review Task Card
 
-- **Standards** — does the code conform to this repo's documented coding standards?
-- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+Use this explicit opt-in for a merge-readiness review. Shared operating invariants
+live in `templates/AGENTS.md`; this card only defines review-specific behavior.
 
-Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+## When to use
 
-## Use When
+- The user asks for a code review or quality/security assessment.
+- A change is ready for review before merge, or a major feature needs an independent review.
+- Do not activate this card for implementation, broad planning, or automatic cleanup.
 
-- The user wants to review a branch, a PR, or work-in-progress changes against a fixed point.
-- The user asks to "review since X" (a commit, branch, tag, or merge-base).
+## Inputs
 
-## Do Not Use When
+- Scope: the requested files, commit, PR, or whole diff.
+- Requirements/specification, acceptance criteria, and relevant test/CI evidence.
+- Existing review artifacts and known risks, if any.
+- If the user says `continue`, advance the current verified review step rather than restarting discovery.
 
-- There is no fixed point to diff against and the user won't supply one (pin one first, see Process step 1), or the work isn't implemented yet so there's no diff to review — use `implement` first.
+Start by recording the scope:
 
-The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+```sh
+git status --short
+git diff --stat
+git diff -- <scope>
+```
 
-## Process
+## Execution
 
-### 1. Pin the fixed point
+1. Identify changed files and review boundaries; do not silently widen the scope.
+2. Launch the `code-reviewer` and `architect` agents in parallel. Both lanes run in parallel on a clean context with explicit scope and artifacts. If either lane cannot be launched or does not return evidence, report `independent review unavailable`; do **not** substitute the current/authoring lane, and do **not** approve or mark the review merge-ready.
+3. Respect the user's current model and reasoning/effort selection. Do not pass `model` or `reasoning_effort` overrides in review-lane calls.
 
-Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+```text
+task(
+  agent_type="code-reviewer",
+  prompt="CODE REVIEW TASK
 
-Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+Review the supplied scope for spec compliance, security, quality, performance, and maintainability.
+Return files reviewed, severity-rated findings with file:line evidence and concrete fixes,
+and a recommendation: APPROVE / REQUEST CHANGES / COMMENT. Do not review architecture.
+Scope: [scope and artifacts]"
+)
 
-Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+task(
+  agent_type="architect",
+  prompt="ARCHITECTURE / DEVIL'S-ADVOCATE REVIEW TASK
 
-### 2. Identify the spec source
+Review the same scope for boundaries, interfaces, hidden coupling, long-term tradeoffs,
+and the strongest counterargument against approval. Return file:line evidence,
+recommendations, and Architectural Status: CLEAR / WATCH / BLOCK.
+Scope: [scope and artifacts]"
+)
+```
 
-Look for the originating spec, in this order:
+## Review taxonomy
 
-1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
-2. A path the user passed as an argument.
-3. A PRD/spec file under `docs/`, `specs/`, or `.adl/` matching the branch name or feature.
-4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+- `code-reviewer` checks **Security**, **Code Quality**, **Performance**, **Best Practices**, and **Maintainability**.
+- Rate each finding: **CRITICAL** (security or data-loss blocker), **HIGH** (bug/major smell), **MEDIUM** (important improvement), or **LOW** (style/suggestion).
+- `architect` checks explicit boundaries/interfaces, hidden coupling, long-horizon tradeoffs, and devil's-advocate concerns. Status is **CLEAR**, **WATCH** (non-blocking concern), or **BLOCK** (merge blocker).
+- Every finding names `file:line`, issue, risk, and a concrete fix; distinguish facts from suggestions.
 
-### 3. Identify the standards sources
+## State/HUD Phase Contract
 
-Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+- Standalone `$code-review` relies on hook-owned `skill-active-state.json` (`skill:"code-review"`, `phase:"planning"`); do not create `code-review-state.json`.
+- Inside Autopilot, keep `mode:"autopilot"` active with `current_phase:"code-review"` / skill-active `phase:"code-review"`; do not activate a peer workflow.
+- On clean review, persist the artifact under Autopilot `handoff_artifacts.code_review` before moving to `ultraqa`. On non-clean review, persist findings and use `rework` or `ralplan` as appropriate.
 
-On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+```sh
+adw state write --input '{"mode":"autopilot","active":true,"current_phase":"code-review"}' --json
+```
 
-- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
-- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+## Final Synthesis and gate
 
-Each smell reads *what it is* → *how to fix*; match it against the diff:
+### Architectural Status Contract
 
-- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
-- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
-- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
-- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
-- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
-- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
-- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
-- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
-- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
-- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
-- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
-- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+Combine the `code-reviewer` recommendation and architect status. Approval requires explicit evidence from both independent lanes; missing or failed delegation is a blocking unavailable-review state, not an approval fallback. The final report must make architect blockers impossible to miss.
 
-### 4. Spawn both sub-agents in parallel
+- If architect status is **BLOCK**, final recommendation is **REQUEST CHANGES**.
+- Else if `code-reviewer` recommendation is **REQUEST CHANGES**, final recommendation is **REQUEST CHANGES**.
+- Else if architect status is **WATCH**, final recommendation is **COMMENT**.
+- Else final recommendation follows the `code-reviewer` lane.
 
-Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+Approval criteria: **APPROVE** only when `code-reviewer` returns APPROVE, architect status is `CLEAR`, and both independent lanes returned evidence. **REQUEST CHANGES** for a blocker, unresolved high/critical finding, or unavailable lane. **COMMENT** may record non-blocking findings.
 
-**Standards sub-agent prompt** — include:
+Do not self-review as a fallback. If the `code-reviewer` or `architect` path is missing, unavailable, skipped, or fails, block approval until independent lane evidence exists. Plain `code-review` itself remains read-only and does **not** promise auto-fix.
 
-- The full diff command and commit list.
-- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
-- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+## Evidence/output contract
 
-**Spec sub-agent prompt** — include:
+Return a concise report containing:
 
-- The diff command and commit list.
-- The path or fetched contents of the spec.
-- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+```text
+CODE REVIEW REPORT
+Files Reviewed: <count>
+Total Issues: 0
+Architectural Status: CLEAR | WATCH | BLOCK
+CRITICAL (0) | HIGH (0) | MEDIUM (0) | LOW (0)
+Findings: file:line -> issue, risk, concrete fix (or none)
+ARCHITECTURE WATCHLIST: concern, status, recommendation (or none)
+- code-reviewer recommendation: COMMENT
+- architect status: WATCH
+- final recommendation: COMMENT
+RECOMMENDATION: COMMENT
+```
 
-If the spec is missing, skip the Spec sub-agent and note this in the final report.
+Replace the illustrative counts and verdict with observed values. Include scope,
+lane evidence/artifact references, unresolved risks, and validation gaps.
 
-### 5. Aggregate
+## Exit condition
 
-Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
-
-End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
-
-## Why two axes
-
-A change can pass one axis and fail the other:
-
-- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
-- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
-
-Reporting them separately stops one axis from masking the other.
+Stop when the scoped diff has two independent lane results and a deterministic final
+recommendation. Report `APPROVE` only under the approval criteria; otherwise leave a
+bounded `REQUEST CHANGES`, `COMMENT`, or unavailable-review result. Never claim
+merge-ready without the required evidence.

package/packages/agent-skills/assets/diagnosing-bugs/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: diagnosing-bugs
-description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", reports something broken/throwing/failing/slow, or asks to trace a crash or root cause through the call chain.
+keywords: trace crash root cause call chain execution flow callers callees failing throwing regression diagnose debug
 disable-model-invocation: false
 ---
 
@@ -53,6 +54,24 @@ Once it's red, shrink the repro to the **smallest scenario that still goes red**
 
 Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green. Do not proceed until you have reproduced **and** minimised.
 
+## Trace with the knowledge graph
+
+When the symptom names a code area, or a recent change is the suspect, trace
+the call structure with the knowledge graph instead of reading file by file —
+this is how Phase 3 hypotheses get built fast:
+
+1. Run `crg search "<query>"` to find code related to the issue.
+2. Run `crg query callers_of <target>` and `crg query callees_of <target>` to trace call chains.
+3. Run `crg flow --name <n>` to see full execution paths through suspected areas.
+4. Run `crg detect-changes --base <ref>` to check if recent changes caused the issue.
+5. Run `crg impact --files <f…>` on suspected files to see what else is affected.
+
+- Check both callers and callees to understand the full context.
+- Look at affected flows to find the entry point that triggers the bug.
+- Recent changes are the most common source of new issues.
+- Trace efficiently: capped output (`--limit`, `--brief`), a handful of commands,
+  then verify the suspected cause against real source before proposing a fix.
+
 ## Phase 3 — Hypothesise
 
 Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
@@ -99,10 +118,12 @@ Required before declaring done:
 
 **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
 
-## HITL loop script
+## HITL loop script — live sessions only
 
 `scripts/hitl-loop.template.sh` is the human-in-the-loop reproduction loop (usage notes moved out of the script so the deployed copy has no multi-line comment run).
 
+**Live sessions only** — a session where the human is present (`write-feature`-style live work, or this skill invoked interactively). Never inside a dispatched run: No block forbids waiting on a person, and run evidence must be machine-checkable. In a dispatched run a human-only repro is automated instead (Playwright drives the clicks — tactic 4) or, if that genuinely fails, the lead posts the attempt as a finding and parks the item with proof. In a live session the captured `KEY=VALUE` pairs are the human's testimony, and the regression test built from them still lands before the fix.
+
 - Copy the file, edit the steps in it, and run it. The agent runs the script; the user follows prompts in their terminal.
 - Usage: `bash hitl-loop.template.sh`
 - Two helpers: `step "<instruction>"` shows the instruction and waits for Enter; `capture VAR "<question>"` shows the question and reads the response into `VAR`.

package/packages/agent-skills/assets/diagnosing-bugs/references/FEEDBACK-LOOP-TACTICS.md

@@ -11,7 +11,7 @@
 7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
 8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
 9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+10. **HITL bash script.** If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. **Live sessions only** — never inside a dispatched run (No block: never wait on a person; run evidence must be machine-checkable). In a run, automate the human instead (Playwright, tactic 4); if that genuinely fails, the lead parks the item with proof. Captured output feeds back to you.
 
 Build the right feedback loop, and the bug is 90% fixed.
 

package/packages/agent-skills/assets/explore-codebase/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: explore-codebase
 description: Navigate and understand codebase structure using the knowledge graph
+keywords: navigate orient structure understand unfamiliar get oriented modules
 disable-model-invocation: false
 ---
 
@@ -16,8 +17,8 @@ relationships before making a change, or locating where a concept lives.
 ## Do Not Use When
 
 You already know where the problem is and need to trace a bug — use
-`debug-issue`. You are about to refactor a known target — use
-`refactor-safely`. You are reviewing a pending diff — use `review-changes`.
+`diagnosing-bugs`. You are about to refactor a known target — use
+`refactor-safely`. You are reviewing a pending diff — use `code-review`.
 
 ## Steps
 

package/packages/agent-skills/assets/finalize-feature/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: finalize-feature
+description: Assemble the content for the one Feature implementation PR without pushing - the five-section PR body and the implementation report for all items - and check that the design's docs impact is in the diff. Returns text to the lead. Use when the implementation lead spawns writer after the Feature-final check passed at the final head.
+metadata:
+  step: "finalize"
+  role: "writer"
+  states: "Updating Docs"
+---
+
+# Finalize Feature (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`). Evidence assembly only. Docs were written in `implement-item` and reviewed with the code; you make **no pushes, commits, file edits or board writes**, because any push voids the Feature-final evidence. The lead raises the PR; `pr_create_or_update` links the items, moves them and attaches the report **[pending P1/P2/P4]**. You supply content only.
+
+## When to use
+
+- The lead holds a Feature-final verify `PASS` and both review lanes passing at the final head `H`, and items are code-complete (Updating Docs or about to be).
+- Also on a CI round: the lead asks you to append that round to the report.
+- Not for writing docs, fixing code or resolving conflicts.
+
+## Inputs (from the brief)
+
+- Final head `H`, `base_sha`, all per-item sub-agent reports (implement, verify, review) and their finding resolutions, the Feature-final reports, design-update commits, CI rounds so far.
+- Plan folder: `requirements.md`, `design.md` (`## Docs impact`), item files.
+
+## Preconditions
+
+1. `git rev-parse HEAD` equals `H` and the worktree is clean; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+2. The Feature-final verify is `PASS` and code is `APPROVE` and architecture `CLEAR`/`WATCH`, all at `H`; else return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Procedure
+
+1. **Docs check.** For each entry in `design.md` `## Docs impact` (per-Bug run: the docs the fix touches), find the matching path in `git diff --name-only origin/integration...H` and read the hunk, not just the filename. "No docs impact" counts as covered. Any missing entry: verdict `REWORK`, finding `docs-missing` (`where`: doc path or section; `fix`: what to write). Stop.
+2. **PR body.** The five non-empty sections in [ado-and-git.md](../workitems-process/references/ado-and-git.md#7-git), filled as below. Every claim links to evidence (a report, a commit, a run); no unverified statements.
+   - `## Summary`: what the Feature delivers, by item (id, title).
+   - `## Why`: from `intent.md` and `requirements.md`, in the plan's words, not new claims.
+   - `## Changes`: per item, the files and behaviour changed; design updates made during the run; docs touched.
+   - `## Test plan`: per `AC-n`, the test and its result; Feature-final verify run at `H`; CI status as known.
+   - `## Security impact considered`: what the code reviewer examined and found; "none" only with the reviewer's report as the source.
+   The title is `<type>(<scope>): <lowercase subject>`.
+3. **Implementation report** (becomes `impl-report-pr<id>.md`). Per item: changes, tests (`AC-n` → test, red then green), review findings (id, severity, resolution or accepted WATCH), rounds used. Then: design updates, Feature-final heads and results, CI rounds. Facts only, from the reports.
+4. **Return** `lane: finalize`, `head_sha` = `H`, `verdict`, and in the reply the PR body, the report text and the docs-impact table (entry → doc path), each in its own fenced block. Write them nowhere.
+
+## Verdicts
+
+| Verdict | When | Lead does |
+|---|---|---|
+| `DONE` | Docs covered; body and report complete | Pushes and raises the PR |
+| `REWORK` + `docs-missing` | Docs impact not in the diff | Executor writes it; Feature-final repeats |
+
+## Stop rules
+
+- One pass, against the `head_sha` recorded at start. If HEAD moves while you work, finish against that `head_sha` and say so; never restart. The lead re-runs you at the new head ([Evidence and reports](../workitems-process/SKILL.md#evidence-and-reports), the head rule).
+
+## Never
+
+- Never push, commit, rebase or edit files. Never write the body or report to disk.
+- Never call `pr_create_or_update` or any board tool; never link items, set auto-complete, vote or merge.
+- Never include a claim without a source, or a PR link that does not resolve.
+- Never write the docs yourself.
+
+## Parked
+
+`prepare-promotion` (integration to main, G2) is parked: no target fires it. It stays with `writer`, for later.

package/packages/agent-skills/assets/fix-ci/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: fix-ci
+description: Make the smallest fix for a red CI run on the run's implementation PR (a Feature's, or a Fixes Bug's) - read the failing job, reproduce it locally, fix at the cause, commit on the run's branch, no skips and no masking. Use when the implementation lead spawns executor for the CI stage after the PR checks went red.
+metadata:
+  step: "fix-ci"
+  role: "executor"
+  states: "CI stage"
+---
+
+# Fix CI (sub-agent skill)
+
+Load `workitems-process` first. You are a leaf sub-agent of `lead` (`implement-feature`), the fix lane of the CI stage (ADR-019). CI is the last gate before the implementation PR (the Feature's, or the Fixes Bug's) merges to `integration`. A hard cut: the fix is the smallest change that makes the real check pass.
+
+## When to use
+
+- The PR's required check failed at head `H`. The lead names the PR id, the failed build and job ids, and the related item.
+- A merge-conflict round is not yours; the lead sends an executor with `implement-item`.
+
+## Inputs (from the brief)
+
+- PR id, build id, failed job(s), head SHA, related item id (the item whose commits touch the failing paths; else the lowest-id item; in a per-Bug run, the Bug), plan folder (in a per-Bug run, the Bug's item file).
+
+## Preconditions
+
+1. Worktree toplevel and HEAD equal the brief's; tree is clean; branch is the run's branch (the Feature branch, or `fix/az<bug id>-<slug>` in a per-Bug run).
+2. The failing job log is readable (`build_list_or_get --build-id <id>`, with `--tail`). Unreadable: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Procedure
+
+1. **Read the log.** Find the first failing step, its command and its error. Quote the failing line.
+2. **Classify.**
+   - Code or test failure: continue.
+   - Infrastructure failure (agent lost, cancelled, network, queue timeout) with log proof and no code cause: return `INFRA` with the proof. The lead may re-queue the PR's own validation (pending H1). Do not change code.
+3. **Reproduce locally** with the same command. A failure you cannot reproduce is reported with both outputs, not "fixed" by guessing.
+4. **Fix at the cause.** Test first when the failure exposes a missing test. Smallest change; no unrelated cleanup; no new abstraction.
+5. **Checks.** Run the failing command and the repo's lint, typecheck, build and the relevant tests locally. Green.
+6. **Commit** on the run's branch: `fix(ci): <lowercase subject>`, `AB#<item id>` in the body (the Bug's id in a per-Bug run), naming the build and job. Do not push.
+7. **Return the report**: `lane: fix-ci`, `head_sha` = your commit, `verdict`, `findings` (the cause: `where`, `what`, `fix`), `artifacts` = failing log line, local red and green runs, commit SHA.
+
+## Verdicts
+
+| Verdict | When |
+|---|---|
+| `FIXED` | Reproduced, fixed at the cause, local checks green, committed |
+| `INFRA` | Not a code failure; log proof included; nothing changed |
+
+The lead then has `verifier` and `code-reviewer` re-check the delta at the new head. A fix is not done until they pass.
+
+## Stop rules
+
+- The same check fails after three distinct fixes: return it to the lead as a finding and stop ([No block](../workitems-process/SKILL.md#no-block)).
+
+## Never
+
+- Never skip, disable, quarantine or loosen a test or check. Never `|| true`. Never `--no-verify`. Never delete a failing test.
+- Never re-run until green and call it fixed; a flaky result is reported with both runs.
+- Never push, force-push, re-queue a build, move an item or touch the PR.
+- Never edit `requirements.md` or `design.md`.

package/packages/agent-skills/assets/handoff/SKILL.md

@@ -21,7 +21,7 @@ Write a handoff document summarising the current conversation so a fresh agent c
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
 
-Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+Do not duplicate content already captured in other artifacts (docs, plans, ADRs, commits, diffs). Reference them by path or URL instead.
 
 Redact any sensitive information, such as API keys, passwords, or personally identifiable information.