@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.35 → 0.1.46

package/packages/agent-hooks/src/rules/shell/protected-carriers.ts

@@ -10,9 +10,16 @@
  * `agent-tamper-protection.ts` imports it, rather than two copies that could
  * drift.
  *
- * Still hard-coded on purpose (not configurable): see
- * `impl/agent-tamper-protection.ts`'s header for why an `adl-config.toml`
- * allowlist for this rule would be the same "switch the gate off" hole it
+ * `adl-config.toml` is NOT in this set. It is a runtime configuration file
+ * the agent must be able to edit (Tarun, 2026-10-13: "adl-config.toml can be
+ * editted but not committed by the agents"). The COMMIT side is enforced by
+ * repo-controls' `integrity.ts` (`WIRING`, refuses a normal commit of
+ * `adl-config.toml`) and by `agent-hooks`' `git.protected-tree-commit` rule
+ * (Bug 373/PBI 679); both fire on the staged index, not on the working
+ * tree.
+ *
+ * Still hard-coded on purpose (not configurable): a per-repo allowlist in
+ * `adl-config.toml` would be the same "switch the gate off" hole this rule
  * exists to close.
  */
 
@@ -29,10 +36,6 @@ export const PROTECTED_CARRIER_PATHS: ReadonlySet<string> = new Set([
   '.claude/settings.json',
   '.claude/settings.local.json',
   '.codex/config.toml',
-  // `adl-config.toml` was the fourth entry until 2026-10-01 (Tarun: "nobody
-  // should stop editing adl-config.toml"). It stays human-landed at commit time
-  // (`git.protected-tree-commit`, repo-controls' integrity gate), but an agent
-  // can now write it, and every hook run re-reads it.
   '.codex/hooks.json',
   '.cursor/hooks.json',
   '.opencode/plugins/adl-repo.ts',

package/packages/agent-settings/assets/TARUN-GLOBAL-AGENTS-INSTRUCTIONS.md

@@ -6,8 +6,8 @@ Where a repository has its own AGENTS.md, that file and the files it links add t
 ## Communication
 - Address me as **Tarun**.
 - **Answer first.** No greeting, no "let me", no recap of what was just done, no closers.
-- One idea per sentence. Short beats polite. Articles can go; not, never, no, only never do. Numbers, paths, commands exact.
-- Bullet points over prose.
+- One idea per sentence. Short beats polite. Articles can go; not, never, no, only never do. Numbers, paths, commands exact. **Maximum 100 words** per response
+- **Bullet points over prose**.
 - **Open points:** one numbered list of open decisions per conversation. Show it only when it changes — item added or resolved. After a long gap or compaction, restate the full list. That is when it gets lost.
 - **Questions:** one at a time, one or two sentences. Options inline: `A) … B) …`. A long multi-part question means split the work, not more prose.
 - Full sentences for security warnings, irreversible actions, step-by-step orders, and when I'm confused. Then short resumes.

package/packages/agent-settings/package.json

@@ -6,7 +6,7 @@
   "description": "Machine-global agent surface tooling (sweep, global-agents, kimi-hooks, surface-policy) run by the fleet bin wrappers under bun; also holds GLOBAL-AGENTS.md, surface policy, and the protected list. Subagent definitions (Claude/Codex/Cursor/Kimi/OpenCode) are canonical in packages/agent-skills/extensions/adl-factory/agents/*.toml and projected per repo by that package's installer; this package does not generate or hold its own copy.",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "bun test --coverage",
+    "test": "bun test --isolate --coverage",
     "check": "bun run typecheck && bun run test --coverage"
   },
   "dependencies": {

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

@@ -25,6 +25,13 @@ export interface DeployAgentsOptions {
   readonly agents?: readonly AgentDef[];
   /** Computes the exact same written/unchanged/removed/conflicts result without writing anything (independent review, 2026-09-29, finding 6). */
   readonly dryRun?: boolean;
+  /**
+   * When set, deploy only the named surface (profile.agents.surfaces[].name) —
+   * the deploy half of the per-surface knob (az567). Other surfaces are
+   * left untouched: their files are not written, their conflicts are not
+   * reported, the lock is not rewritten for them.
+   */
+  readonly surfaceFilter?: string;
 }
 
 interface AgentConflict {
@@ -71,6 +78,10 @@ export function deployAgents(options: DeployAgentsOptions): DeployAgentsResult {
   let anyLegacyTakeover = false;
 
   for (const surface of profile.agents.surfaces) {
+    // az567 surfaceFilter: only iterate the named surface. Other
+    // surfaces' deploy paths, conflicts, and lock entries are out of
+    // scope and never appear in this result.
+    if (options.surfaceFilter !== undefined && surface.name !== options.surfaceFilter) continue;
     const ext = extensionFor(surface);
     const kept: string[] = [];
 
@@ -126,7 +137,14 @@ export function deployAgents(options: DeployAgentsOptions): DeployAgentsResult {
     newAgentEntries[surface.folder] = kept.sort();
   }
 
-  if (!dryRun) writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: newAgentEntries });
+  // az567 surfaceFilter: when only one surface is in scope, the
+  // `newAgentEntries` map only carries that surface. The lock write
+  // must keep every other surface's previous lock entry byte-identical
+  // so non-target surfaces are not "unwritten" by a per-surface deploy.
+  const lockAgents = options.surfaceFilter === undefined
+    ? newAgentEntries
+    : { ...lock.agents, ...newAgentEntries };
+  if (!dryRun) writeLock(targetRepo, { schema: 1, mcp: lock.mcp, agents: lockAgents });
 
   // Once anything was actually taken over, this package's own footprint in
   // the legacy lock's `files` section for these exact agent paths is stale:

package/packages/agent-settings/src/deploy/index.ts

@@ -1,6 +1,7 @@
 export { type DoctorResult } from "./doctor.js";
 export { listSettings } from "./list.js";
 export { deploySettings, doctorSettings, type DeploySettingsResult } from "./settings.js";
+export { deployAgents, type DeployAgentsResult } from "./agents-deploy.js";
 export { loadProfile } from "./profile.js";
 export { loadMcpSource, type McpServerSpec } from "./mcp-source.js";
 export { loadAgentSources, type AgentDef } from "./agent-toml.js";

package/packages/agent-skills/assets/agent-search-tool-audit/SKILL.md

@@ -26,8 +26,7 @@ and its evidence siblings.
 - The repo has no `.adl/logs/` (no agent-hooks hooks installed).
 - The question is about a non-search tool (use a different audit
   script).
-- The repo is not a git repo and the script's `git rev-parse
-  --show-toplevel` fallback cannot find the project root — pass
+- The repo has no project root the script can find — pass
   `--out <absolute-dir>` to write the report elsewhere.
 
 ## Process
@@ -42,8 +41,7 @@ After deploy, the script lives at:
 
 In dev (this repo's `packages/agent-skills/`), the equivalent path is
 `packages/agent-skills/assets/agent-search-tool-audit/scripts/audit.sh`.
-The script finds the project root via `git rev-parse --show-toplevel`,
-so it works in both layouts.
+The script locates the project root, so it works in both layouts.
 
 ### 2. Run with the desired window
 
@@ -133,8 +131,8 @@ Rationale moved out of `scripts/audit.sh` (REP-007: no multi-line comments).
   `hooks-deny.log` (read-only history, never migrated, deduped against the new ones);
   `.adl/logs/agents/tool-calls.log` (`adl run` lifecycle).
 - Path discovery: the script lives in the agent-skills asset tree (5 levels deep in dev, 4 once
-  deployed to `.agents/skills/`), so it uses `git rev-parse --show-toplevel` to work in both layouts
-  and falls back to the dev layout if git is missing.
+  deployed to `.agents/skills/`), so it locates the project root to work in both layouts
+  and falls back to the dev layout if it cannot.
 - Required tools: `jq`, `python3` and `rg`; each is checked up front and the script fails loud
   (exit 1) naming the missing one. `rg` is a protected bootstrap tool on every managed machine.
 - Cost: under 30 s on a typical 2-3 MB log set; no network.

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. The branch 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 the diff against `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 (Summary, Why, Changes, Test plan, Security impact considered), 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.