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

package/packages/agent-skills/assets/workitems-process/references/evidence.md

@@ -0,0 +1,74 @@
+# Run reports and evidence
+
+Part of [`workitems-process`](../SKILL.md). Tags: **[pending X]** = change row `X`, not built.
+
+## Principle
+
+- **The dispatcher parses nothing and writes nothing.** Whether a target is done is decided from the board and the PR (the target's done proof), not from a comment.
+- Evidence is for humans, for the next sub-agent, and for a resumed run. It binds to what it ran against: the head SHA, or plan revision N. A later commit voids earlier test and review evidence for what it touches; the Feature-final check at the final head is what the merge relies on.
+- **Evidence is the item comment plus the PR.** The run-level report is the run's last comment: on the Feature for a planning or implementation run, on the Bug for a per-Bug run, never on a PBI. Its first line is one machine line, `adl-evidence v1 <run> <verdict> <head_sha>` (e.g. `adl-evidence v1 implementation MERGED 3f9c2ab`), then the report.
+
+## Where evidence lives
+
+| Record | Written by | Where |
+|---|---|---|
+| Sub-agent report | the sub-agent returns it; the **lead** posts it | item comment (Feature comment for the Feature-final and finalize lanes) |
+| Run report, planning and implementation | the lead (`planner`, `lead`) | one comment as its last action: on the Feature, or on the Bug in a per-Bug run |
+| Run report, `workitem-triage` | `triager` | the activity log (`adl activity add`) plus one comment on each touched item |
+| PR body | the lead; on an implementation PR the text comes from `writer` | the PR |
+| Plan snapshot, implementation report | content from the lead; attached by `pr_create_or_update` | Feature attachments ([`ado-and-git.md` § Plan files](ado-and-git.md#4-plan-files)) |
+| Review findings | review sub-agents via the lead | item comments and the implementation report; never PR threads or votes |
+
+- Reading earlier comments needs **T1 (pending)**. A resumed run that cannot read them works from the board states and the PR, and re-runs any verify or review whose head is not the current head.
+- Evidence never holds secrets: links, repo-relative paths, commands with exit codes, run ids, SHAs.
+
+## Sub-agent report (the common shape)
+
+````yaml
+lane: validate | design-update | implement | fix-ci | verify | verify-final | review-code | review-architecture | finalize | review-plan-architect | review-plan-critic
+target: <item id | feature id>
+base_sha: <integration base sha>
+head_sha: <worktree HEAD the report applies to; plan reviews name revision N>
+verdict: <set per lane, below>
+findings:                    # required for every non-pass verdict
+  - id: F1
+    severity: critical | high | medium | low
+    where: path:line
+    what: "<issue and risk>"
+    fix: "<concrete change>"
+artifacts:                   # files reviewed, commands with exit codes, run ids, AC-n -> test map, commit SHAs
+  - ...
+````
+
+A negative verdict with empty `findings`, or a finding without `where` and `fix`, is invalid. `REQUEST_CHANGES` and `BLOCK` send the item back into the loop; `WATCH` and medium or low findings are recorded, not blocking. The Critic's verdict for revision N counts only after the Architect's review of the same revision.
+
+## Verdicts by lane and by run
+
+| Lane or run | Verdicts |
+|---|---|
+| plan review, architect and critic | `APPROVE` · `ITERATE` · `REJECT` |
+| validate (`design.md` and its `file-map-reference.md`) | `FRESH` · `DRIFT` (exact delta) |
+| design update (planner sub-agent) | `UPDATED` |
+| implement | `DONE` · `DRIFT` · `PARK` |
+| verify, verify-final | `PASS` · `FAIL` |
+| review, code | `APPROVE` · `REQUEST_CHANGES` |
+| review, architecture | `CLEAR` · `WATCH` · `BLOCK` |
+| finalize | `DONE` · `REWORK` (finding `docs-missing`) |
+| fix-ci | `FIXED` · `INFRA` |
+| run: workitem-triage | `TRIAGED` |
+| run: planning | `DONE` (every in-scope item at Awaiting Approval and the planning PR raised; the report names the critic outcome, `APPROVE` or the cap) · `PARK` (the work is obsolete: the planner moved the in-scope items to Parked for Removal, each with a reason comment; G3 decides) |
+| run: implementation | `MERGED` · `PR_OPEN` (CI unfinished at session end; the next dispatch resumes) |
+
+No lane or run has a `BLOCKED` verdict. A failed precondition, a tool refusal or a cap follows its path in [No block](../SKILL.md#no-block).
+
+## Run report content
+
+Posted by the lead as its last action, then the one-line handoff `<target> <verdict> <key kind> <id> @ <sha>`.
+
+| Target | The report holds |
+|---|---|
+| workitem-triage | per swept item: applied, proposed (comment posted, item unchanged) or unchanged, with reasoning and evidence (`file:line`, commit, test output); split-off ids; rolled-up Feature ids; Bugs filed through `report-bug`; Features at New with no plan yet (informational); base SHA |
+| planning | revision N, baseline SHA, plan hash, review rounds, critic outcome, open findings, planning PR URL, allocated item ids |
+| implementation | per item: final state, commits (`AB#` ids), sub-agent verdicts and head SHAs; design updates; Feature-final result at the final head; CI rounds; PR link; verdict |
+
+Every negative result names `where` and `fix`.

package/packages/agent-skills/assets/workitems-process/references/workitem-states.md

@@ -0,0 +1,92 @@
+# Work item states, moves and links
+
+Part of [`workitems-process`](../SKILL.md). Tags: **[live]** = enforced today; **[pending X]** = change row `X`, not built. Never act as if a pending change is live.
+
+## 1. PBI states
+
+| State | Owner | Entered when | Exit |
+|---|---|---|---|
+| New | planning run | the item is allocated under its Feature | → In Planning |
+| In Planning | planning run | the planner moves it, after allocating any new PBIs and before writing the files | → Awaiting Approval |
+| Awaiting Approval | Tarun (**G1**) | the planning PR is raised | → Approved, In Planning (rework) or New (requeue) |
+| Approved | implementation run | Tarun approves the plan revision | → Design Validation |
+| Design Validation | implementation run | the lead's first act; re-entered from In Implementation on drift | → In Implementation |
+| In Implementation, In Testing, In Review | implementation run | the loop | the loop |
+| Updating Docs | implementation run | the loop; the implementation PR is raised | the loop, or → Done |
+| Done | — | the Feature's implementation PR, linked to the item, merges into `integration` | terminal |
+| Parked for Removal | Tarun (**G3**) | a lead parks the item with a reason | → Removed, or → New (revive) |
+| Removed | — | Tarun confirms the removal | terminal |
+
+- Up to Design Validation the order is strict.
+- **The loop is non-linear.** After Design Validation, In Implementation, In Testing, In Review and Updating Docs are free moves in either direction, per PBI. The usual order is In Testing before In Review, so a reviewer sees green code; a default, not a rule.
+- **Fence today [live]:** among the loop states the fence allows only In Review → In Implementation (`workflow-rules.ts:81`). Every other loop move (In Testing → In Implementation, Updating Docs → In Implementation or In Review, the skips) is **[pending F1]**, as is the drift loop-back In Implementation → Design Validation (ADO allows it, the fence does not yet). On a refusal: post the exact text as an item comment and take the path the refusal names; do not work around it.
+- **Drift loops back; it never leaves the run.** In Implementation → Design Validation; the lead re-validates `design.md`; a drifted `design.md` is fixed in the run by a planner sub-agent. Items never go to New or In Planning for drift. Drift that would need an approved `AC-n` changed follows [No block](../SKILL.md#no-block).
+- Later commits void earlier test and review evidence, so the Feature-final check at the final head is what the merge relies on.
+
+## 2. Who moves what
+
+| Move | Who | Status |
+|---|---|---|
+| New → In Planning | planning lead: after allocating any new PBIs, it moves every in-scope PBI (existing and new), then writes the files; all are at In Planning before the planning PR is raised | live |
+| In Planning → Awaiting Approval | `pr_create_or_update`, when it raises the planning PR | pending P2 |
+| Awaiting Approval → Approved / In Planning (rework) / New (requeue) | Tarun (G1) | live |
+| Approved → Design Validation | implementation lead, first act | live |
+| Design Validation → In Implementation | implementation lead, when an item's build starts | live |
+| Free moves among the four loop states | implementation lead | pending F1 |
+| In Implementation → Design Validation | implementation lead, on mid-loop drift | pending F1 |
+| Loop → Updating Docs | `pr_create_or_update`, when it raises the implementation PR | pending P2 |
+| Updating Docs → Done | ADO completion of the linked implementation PR (`transitionWorkItems`) | pending P1, P2, V2 |
+| Any non-terminal → Parked for Removal | any lead, with a reason | live |
+| Parked for Removal → Removed | Tarun (G3) | live |
+| Parked for Removal → New (revive) | Tarun | human-only; the fence lets agents make it today, and agents never do |
+
+- Both G1 rejection paths force a new G1 pass.
+- **Agents never set Done, Approved or Removed.** Done follows the merge of the implementation PR, which `pr_create_or_update` links to the items ([`ado-and-git.md` § PR wiring](ado-and-git.md#6-pr-wiring)). A planning PR's merge never moves items.
+- **Agents pass nothing for the PR-time moves** and make none of them.
+- Feature roll-ups are `workitem-triage`'s (§3).
+
+## 3. Feature states
+
+`New → In Progress → Awaiting Release → Done`, plus `Removed`. Linear, one step at a time, never backward; Done only from Awaiting Release **[pending F3, F4]**.
+
+| State | Entered when | Moved by |
+|---|---|---|
+| New | the Feature is created, only at New | — |
+| In Progress | at least one child has left New | `workitem-triage` roll-up |
+| Awaiting Release | every child is Done or Removed (its implementation PR merged into `integration`) | `workitem-triage` roll-up |
+| Done | the `integration → main` PR carrying the children is merged (G2) | `workitem-triage` roll-up |
+| Removed | Tarun removes the Feature | Tarun, human-only |
+
+- **"Closed" = Awaiting Release or later.** No child may be added to a closed Feature **[pending L1]**; work found later goes into a new Feature or a Fixes Bug.
+- **`Fixes to closed Features`** (one per Epic, 548–554) stays **In Progress** permanently; agents may not move it **[pending F5]**. It is exempt from the predecessor rule and the roll-ups.
+
+## 4. Links
+
+- **Parent:** a PBI or Bug's parent is its Feature; a Feature's parent is an Epic. In an item file, `feature:` is the Feature's full board URL.
+- **Predecessors live on Features only:** at least 1, except the very first Feature. Soft warning first, hard refusal later **[pending L2]**. A Feature is **ready** when every predecessor is at Awaiting Release or Done.
+- **PBIs carry no predecessors** **[pending L3]**; item order inside a Feature is the implementation lead's choice.
+- **Fixes Bugs are the one exception:** a Bug under `Fixes to closed Features` has a predecessor (another Bug there) and a **Related** link to the Responsible Feature, in any state (a red pipeline's Responsible Feature can be open) **[pending L4]**. The first Bug in a Fixes Feature has no predecessor, and none is accepted; every later Bug needs one.
+- **Findings go through `report-bug`:** a defect in an open Feature (before Awaiting Release) updates that Feature's PBIs and creates no Bug; a defect in a closed Feature creates a Bug under that Epic's `Fixes to closed Features`.
+
+## 5. Bug states
+
+Every Bug is a Fixes Bug under a `Fixes to closed Features` Feature. **Never planned:** no In Planning, Awaiting Approval or Design Validation, no plan hash, no `requirements.md`, `design.md` or `file-map-reference.md`.
+
+`New → Approved → In Reproduction → In Fixing ↔ In Testing ↔ In Review ↔ Updating Docs → Done`, plus `Parked for Removal → Removed` and `Parked for Removal → New`.
+
+| Move | Who |
+|---|---|
+| created at New | `report-bug`, on the board only; its Description holds the bugfix shape ([`ado-and-git.md` § Item files](ado-and-git.md#5-item-files)) |
+| New → Approved | Tarun (**G1**), approving that Description; human-only |
+| Approved → In Reproduction | implementation lead, first act of the per-Bug run **[pending L5, X2]** |
+| In Reproduction → In Fixing | implementation lead, once the executor (reproduce mode) has committed the item file and the regression test marked as an expected failure (the framework's xfail or `test.fails` form), with its unmarked run red on the base posted on the Bug as evidence; the reproduce commit stays green, and the fix commit removes the mark |
+| Free moves among In Fixing, In Testing, In Review, Updating Docs | implementation lead (the PBI loop with In Fixing in place of In Implementation) |
+| Loop → Updating Docs | `pr_create_or_update`, when it raises the Bug's implementation PR |
+| Updating Docs → Done | ADO completion of the linked implementation PR; agents never move to Done |
+| In Reproduction → Parked for Removal | implementation lead, when the Bug won't reproduce: it posts what was tried as a comment on the Bug |
+| Any non-terminal → Parked for Removal | any lead, with a reason (New and Approved included, to park a duplicate) |
+| Parked for Removal → Removed | Tarun (**G3**), human-only |
+| Parked for Removal → New (revive) | Tarun, human-only |
+
+- **Per-Bug run:** branch `fix/az<bug id>-<slug>`. The executor's first commit is the Bug's item file (the Description's sections plus `## Predecessors` mirroring the board link), with its LEDGER row `az<id>-bug`; then the regression test. **The reproduce commit stays green.** The executor runs the regression test unmarked on the base and proves it red; that run output goes into a comment on the Bug as evidence (the executor returns it, the lead posts it). It commits the test marked as an expected failure (the framework's xfail or `test.fails` form), so lint, typecheck, build and the suite pass. The fix commit removes the expected-failure mark, so the same test now passes normally. Every commit stays independently green, with no exception. The lead writes no files.
+- Every other Bug move is refused. The fence's Bug table is **[pending F9]**.

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

@@ -0,0 +1,94 @@
+---
+name: write-feature
+description: Live, human-attended session that creates a Feature on the ADO board, parent Epic chosen by the human and at least one predecessor Feature unless it is the very first, and writes its intent.md in the human's own words, then lands it through a docs branch and PR. Use when Tarun asks to start, create or write up a new Feature or its intent. Never dispatched.
+metadata:
+  step: "live"
+  role: "session agent with the human"
+  states: "Feature:New"
+---
+
+# Write Feature (live session)
+
+Load `workitems-process` first. This card adds only what the live Feature session does.
+
+## When to use
+
+- The human starts a new Feature in a session they attend. This is stage 1 of the Feature flow.
+- **Never dispatched.** No dispatch record, no worktree from the dispatcher, no run report. If you were started by the dispatcher, stop: this skill is wrong for the run.
+- Not for planning (`plan-feature`) and not for a Bug (`report-bug`).
+
+## Inputs (all from the human)
+
+| Input | Rule |
+|---|---|
+| The Feature in their words | Why, Outcome, Constraints, Non-goals; Open questions optional |
+| Parent Epic | **The human chooses.** Never guess, never create |
+| Predecessor Features | At least 1, unless the human says this is the very first Feature |
+| Title and slug | Human confirms both |
+
+## Preconditions
+
+1. You are in a checkout of the repo that will hold the plan, the integration base is current, clean tree.
+2. The human gave an Epic id. Confirm it parents a Feature: a wrong-typed parent is refused by name at create. Do not read or edit the Epic.
+
+## Procedure
+
+Ask **one question at a time**. Lead with what you already know.
+
+1. **Listen.** Take the human's words. Do not rewrite, extend or "improve" them. Do not add a solution.
+2. **Fill gaps, not prose.** For each required section the human left empty (`## Why`, `## Outcome`, `## Constraints`, `## Non-goals`), ask for it. `## Open questions` is optional; add it only if the human has some.
+3. **Predecessors.** List candidate Features (`workitem_list_or_get --type Feature`) and let the human pick. A Feature needs at least 1 predecessor Feature; only the very first has none. The human says which case applies; you do not infer it. Enforcement is soft then hard: pending L2 in adl-agent-control.
+4. **Allocate the Feature on the board first.** `workitem_create_or_update_feature --title "<title>" --parent-id <epic> --predecessors <ids> --description "<Why, Outcome, Constraints, Non-goals>" --priority <1|2|3|4>`. State stays New (the tool refuses any other create state: pending F3). Mandatory at create: `title`, `parentId` (Epic), `description` (must carry the four intent.md headings `## Why` / `## Outcome` / `## Constraints` / `## Non-goals`), and `priority` ∈ `{1, 2, 3, 4}` (1=Very High, 2=High, 3=Medium, 4=Low). State-conditional gate — when moving off `New` (e.g. to `In Progress`), the call also requires `acceptanceCriteria` plus the three plan fields (`--plan-revision`, `--plan-hash`, `--baseline-sha`); create at `New` does not. Read it back: type Feature, state New, parent = the Epic, predecessors present. A refusal is the answer: report the exact text, stop, create nothing.
+   - **Description = copy of `intent.md`.** Pass the human's own `## Why`, `## Outcome`, `## Constraints`, `## Non-goals` text, verbatim and identical to what step 5 writes, as `--description` at create. Written once, here. Agents never edit it afterwards, the same as `intent.md`. The approved plan lives in the `plan-r<N>-<sha7>.md` attachment, not in the Description.
+   - Do not touch Features 548-554 ("Fixes to closed Features"); their description is already set.
+   - Never create an Epic. Never set `epic:` from tool output; it is the human's value.
+5. **Write `plans/features/az<id>-<slug>/intent.md`.** The id is allocated before the file exists. Layout below. No other file in the folder.
+6. **Read it back to the human.** Commit only after an explicit yes. After that, agents never edit `intent.md`; only the human does.
+7. **Land it.** An ordinary docs change. You create the intent branch from the integration base: the one exception to "agents never create a branch." Add the `plans/LEDGER.md` row `az<id>-intent`. Commit `docs(plans): add intent for az<id> <slug>`. Push. Open the PR with `pr_create_or_update`, with the five PR body sections (Summary, Why, Changes, Test plan, Security impact considered); `## Test plan` and `## Security impact considered` say "none (docs-only)". The branch is not the planning branch and the Feature has no item at Approved or later (PBIs the human already made sit at New), so this is an ordinary PR: the tool links nothing, moves nothing, attaches nothing, and it needs no implementation report. Never rebase or force-push. No reviewer, no vote ([Human gates](../workitems-process/SKILL.md#human-gates)).
+8. **Stop.** Report: Feature URL, branch, PR URL. Say the Feature is at New and the planning trigger ([Targets and triggers](../workitems-process/SKILL.md#targets-and-triggers)) fires on it once the PR has merged. Do not start planning.
+
+## `intent.md` layout
+
+```markdown
+---
+type: intent
+title: <Feature title>
+status: New
+work_item: https://dev.azure.com/<org>/<project>/_workitems/edit/<feature id>
+last_update: <YYYY-MM-DDTHH:MM:SSZ>
+---
+
+## Why
+- <the human's words>
+
+## Outcome
+- <what is true when it is done>
+
+## Constraints
+- <...>
+
+## Non-goals
+- <...>
+
+## Open questions
+- <optional; omit the section if empty>
+```
+
+- Required sections: Why, Outcome, Constraints, Non-goals. Short bullets, the human's own wording.
+- `status` mirrors the Feature's board state (New). `work_item` URL id equals the folder id. Optional `sources:` only if the human names documents.
+- The check for these sections is pending R4; the Feature-state `status` values are pending R1.
+- Owner of the layout: [ado-and-git.md](../workitems-process/references/ado-and-git.md#4-plan-files).
+
+## Stop rules
+
+- Epic not given, or the human cannot say whether a predecessor exists → stop and ask; never default.
+- A refused create or a failed read-back → stop with the exact error; no file before the id.
+- Same command fails twice for the same reason → stop and report.
+
+## Never
+
+- Never write, extend or paraphrase the human's intent for them.
+- Never choose the Epic or a predecessor.
+- Never create PBIs here; planning creates them. PBIs the human already made stay at New and planning reads them.
+- Never move a state, never plan, never post a run report.
+- Never edit `intent.md` after the human approved it.

package/packages/agent-skills/dist/deploy.d.ts

@@ -6,6 +6,16 @@ export interface DeploySkillsOptions {
     readonly profile?: DeployProfile;
     /** Computes the exact same written/unchanged/removed/conflicts/retiredRemovals result without writing anything (independent review, 2026-09-29, finding 6). */
     readonly dryRun?: boolean;
+    /**
+     * When set, deploy only the named surface (profile.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, their retired-folder cleanup does not run. The deploy
+     * profile's `retired` list is the closed set of "skill folders no
+     * surface reads any more"; for surface-prepare this list is also
+     * filtered to the active surfaces.
+     */
+    readonly surfaceFilter?: string;
 }
 export interface SkillConflict {
     readonly folder: string;
@@ -27,5 +37,47 @@ export interface DeploySkillsResult {
      */
     readonly retiredRemovals: readonly string[];
 }
+/**
+ * True when `skillDirAbs` holds exactly the asset skill's files — same
+ * relative paths, same bytes, nothing extra. Such a folder carries no user
+ * content, so deploy may adopt it (Tarun, 2026-10-01).
+ */
+export declare function folderIdenticalToAsset(skillDirAbs: string, assetDirAbs: string, sourceFiles: readonly string[]): boolean;
+export declare function removeEmptyParents(root: string, dir: string): void;
+export interface SkillRefusal {
+    readonly folder: string;
+    readonly skill: string;
+    /** Repo-relative posix path to the entry the primitive refused to remove. */
+    readonly path: string;
+    /** Human-readable reason the entry was refused. */
+    readonly reason: string;
+}
+export interface RemoveDeployedSkillFoldersOptions {
+    readonly assetsDir: string;
+    readonly targetRepo: string;
+    /** Defaults to loadProfile() (the package's own deploy-profile.json) — pass explicitly when the caller has already resolved real on-disk paths (see profile.ts's header). */
+    readonly profile?: DeployProfile;
+    /** When set, only the skill folders for this surface (profile.surfaces[].name) are in scope. */
+    readonly surfaceFilter?: string;
+    /** When set, only this skill id (assets/ skill folder name) is in scope. */
+    readonly skillFilter?: string;
+    /** Computes the exact same removed/absent/refused result without unlinking anything. */
+    readonly dryRun?: boolean;
+}
+export interface RemoveDeployedSkillFoldersResult {
+    /** Repo-relative posix paths the primitive actually removed (or would have, in --dry-run). Sorted, deduplicated. */
+    readonly removed: readonly string[];
+    /** (surface, skill) pairs the deploy profile resolves to that are in scope but were already absent on disk. Sorted, deduplicated, "<folder>/<skill>". */
+    readonly absent: readonly string[];
+    /** Entries the manifest did not record but which live inside a managed skill dir or surface folder — never removed, always reported. */
+    readonly refused: readonly SkillRefusal[];
+}
+/**
+ * The deployed-skill removal primitive (az696). Removes every file the
+ * deploy manifest records, restricted by `surfaceFilter`/`skillFilter`
+ * (intersection) and the repo's `[assets.skills]` subset. Idempotent: a
+ * second call with the same arguments reports every target in `absent`.
+ */
+export declare function removeDeployedSkillFolders(options: RemoveDeployedSkillFoldersOptions): RemoveDeployedSkillFoldersResult;
 export declare function deploySkills(options: DeploySkillsOptions): DeploySkillsResult;
 //# sourceMappingURL=deploy.d.ts.map

package/packages/agent-skills/dist/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../src/deploy.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,KAAK,aAAa,EAA+B,MAAM,cAAc,CAAC;AAI/E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6KAA6K;IAC7K,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,+JAA+J;IAC/J,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,8JAA8J;IAC9J,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AA+BD,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAiK7E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../src/deploy.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAE,KAAK,aAAa,EAA+B,MAAM,cAAc,CAAC;AAI/E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6KAA6K;IAC7K,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,+JAA+J;IAC/J,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,8JAA8J;IAC9J,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CASxH;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAWlE;AA0BD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,6KAA6K;IAC7K,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,gGAAgG;IAChG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,gCAAgC;IAC/C,oHAAoH;IACpH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,yJAAyJ;IACzJ,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,wIAAwI;IACxI,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,iCAAiC,GAAG,gCAAgC,CAoIvH;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CA4O7E"}

package/packages/agent-skills/dist/deploy.js

@@ -17,7 +17,9 @@
  * When `profile.legacyLock` names a lock the OLD repo-controls engine
  * left behind, a same-name folder it fully wrote (per legacy-lock.ts) is
  * taken over on sight rather than reported as a conflict — see
- * legacy-lock.ts for the exact ownership rule and lock rewrite.
+ * legacy-lock.ts for the exact ownership rule and lock rewrite. A legacy
+ * folder whose skill retired from assets/ is removed under the same
+ * ownership rule (never a hand-modified folder).
  *
  * Fails loud: assets/target validation, an invalid deploy profile, an
  * invalid adl-config.toml subset, or an unwritable target all throw. There
@@ -37,7 +39,7 @@ import { listSourceSkillNames } from "./skill-meta.js";
  * relative paths, same bytes, nothing extra. Such a folder carries no user
  * content, so deploy may adopt it (Tarun, 2026-10-01).
  */
-function folderIdenticalToAsset(skillDirAbs, assetDirAbs, sourceFiles) {
+export function folderIdenticalToAsset(skillDirAbs, assetDirAbs, sourceFiles) {
     let targetFiles;
     try {
         targetFiles = walkFiles(skillDirAbs);
@@ -49,7 +51,7 @@ function folderIdenticalToAsset(skillDirAbs, assetDirAbs, sourceFiles) {
         return false;
     return sourceFiles.every((file) => Buffer.compare(readFileSync(join(skillDirAbs, file)), readFileSync(join(assetDirAbs, file))) === 0);
 }
-function removeEmptyParents(root, dir) {
+export function removeEmptyParents(root, dir) {
     let current = dir;
     while (current !== root && current.startsWith(root)) {
         if (!existsSync(current)) {
@@ -62,6 +64,136 @@ function removeEmptyParents(root, dir) {
         current = dirname(current);
     }
 }
+/**
+ * The deployed-skill removal primitive (az696). Removes every file the
+ * deploy manifest records, restricted by `surfaceFilter`/`skillFilter`
+ * (intersection) and the repo's `[assets.skills]` subset. Idempotent: a
+ * second call with the same arguments reports every target in `absent`.
+ */
+export function removeDeployedSkillFolders(options) {
+    const { assetsDir, targetRepo } = options;
+    const dryRun = options.dryRun === true;
+    if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
+        throw new Error(`agent-skills assets directory not found: ${assetsDir}`);
+    }
+    if (!existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
+        throw new Error(`uninstall target is not a directory: ${targetRepo}`);
+    }
+    const profile = options.profile ?? loadProfile();
+    const availableSkills = listSourceSkillNames(assetsDir);
+    const selection = resolveSkillSelection(targetRepo, availableSkills);
+    if (!selection.ok)
+        throw new Error(selection.error);
+    const selectedSkills = [...new Set(selection.skills)].sort();
+    const manifest = readManifest(targetRepo);
+    // Build the in-scope (surface, skill) set, applying both filters as
+    // intersection. An unknown surfaceFilter or skillFilter is silently
+    // out-of-scope — the caller (the CLI) validates the names first and
+    // the primitive trusts its inputs.
+    const inScopeSurfaces = profile.surfaces.filter((surface) => options.surfaceFilter === undefined || surface.name === options.surfaceFilter);
+    const inScopeSkills = selectedSkills.filter((skill) => options.skillFilter === undefined || skill === options.skillFilter);
+    // Build the manifest-ownership set restricted to the in-scope
+    // (surface, skill) pairs. Everything the manifest records under those
+    // pairs is removable; everything else is not in scope.
+    const ownedPaths = new Set();
+    for (const surface of inScopeSurfaces) {
+        for (const skill of inScopeSkills) {
+            const prefix = `${surface.folder}/${skill}/`;
+            for (const file of manifest.files) {
+                if (file.startsWith(prefix))
+                    ownedPaths.add(file);
+            }
+        }
+    }
+    const removed = [];
+    for (const relPath of [...ownedPaths].sort()) {
+        const absolute = join(targetRepo, relPath);
+        if (existsSync(absolute)) {
+            if (!dryRun) {
+                unlinkSync(absolute);
+                removeEmptyParents(targetRepo, dirname(absolute));
+            }
+        }
+        removed.push(relPath);
+    }
+    // Safety check: every path inside a managed skill dir or surface
+    // folder that is NOT in the manifest is reported as a refusal. The
+    // surface folder itself (e.g. `.claude/skills`) is reported when it
+    // exists and is not under any managed skill dir — the agent never
+    // removes the surface root on its own, only the skill dirs under it.
+    const refused = [];
+    for (const surface of inScopeSurfaces) {
+        const surfaceAbs = join(targetRepo, surface.folder);
+        if (!existsSync(surfaceAbs))
+            continue;
+        const inScope = options.skillFilter === undefined
+            ? inScopeSkills
+            : inScopeSkills.filter((skill) => skill === options.skillFilter);
+        // Hand-authored skill dirs the manifest did not write.
+        for (const name of directoryNames(surfaceAbs)) {
+            if (inScope.includes(name))
+                continue;
+            // A skill the manifest owns under this surface is in-scope; an
+            // unrecorded same-name dir is user-authored and refused.
+            const isManaged = manifest.files.some((file) => file.startsWith(`${surface.folder}/${name}/`));
+            if (isManaged)
+                continue; // already handled in the removal pass above
+            refused.push({
+                folder: surface.folder,
+                skill: name,
+                path: `${surface.folder}/${name}`,
+                reason: "folder is not recorded in the deploy manifest; refusing to remove user-authored content",
+            });
+        }
+        // For each in-scope skill dir, any file inside that is not in the
+        // manifest is reported and never removed.
+        for (const skill of inScope) {
+            const skillDirAbs = join(surfaceAbs, skill);
+            if (!existsSync(skillDirAbs))
+                continue;
+            const isManaged = manifest.files.some((file) => file.startsWith(`${surface.folder}/${skill}/`));
+            if (!isManaged)
+                continue; // already refused above as user-authored
+            for (const relFile of walkFiles(skillDirAbs)) {
+                const relPath = `${surface.folder}/${skill}/${relFile}`;
+                if (ownedPaths.has(relPath))
+                    continue;
+                refused.push({
+                    folder: surface.folder,
+                    skill,
+                    path: relPath,
+                    reason: "file is inside a managed skill dir but is not recorded in the deploy manifest; refusing to remove user-authored content",
+                });
+            }
+        }
+    }
+    refused.sort((a, b) => a.path.localeCompare(b.path));
+    // The "absent" report: every (surface, skill) pair the deploy profile
+    // resolves to, filtered to in-scope, that has no files on disk and no
+    // manifest record. This is the idempotency signal a second run will
+    // see.
+    const absent = [];
+    for (const surface of inScopeSurfaces) {
+        for (const skill of inScopeSkills) {
+            const skillDirAbs = join(targetRepo, surface.folder, skill);
+            const prefix = `${surface.folder}/${skill}/`;
+            const hasManifestEntry = manifest.files.some((file) => file.startsWith(prefix));
+            if (!hasManifestEntry && !existsSync(skillDirAbs)) {
+                absent.push(`${surface.folder}/${skill}`);
+            }
+        }
+    }
+    absent.sort();
+    // Rewrite the manifest to drop the paths we removed (and only those).
+    // The surviving set keeps every path the manifest recorded that is
+    // outside the in-scope (surface, skill) pairs — those belong to other
+    // surfaces/skills the user did not ask to uninstall.
+    if (!dryRun) {
+        const surviving = manifest.files.filter((file) => !ownedPaths.has(file));
+        writeManifest(targetRepo, surviving);
+    }
+    return { removed: removed.sort(), absent, refused };
+}
 export function deploySkills(options) {
     const { assetsDir, targetRepo } = options;
     const dryRun = options.dryRun === true;
@@ -91,8 +223,51 @@ export function deploySkills(options) {
     // conflict, with a reason naming what disqualified it.
     const takeoverFiles = new Set();
     const takeoverConflictReasons = new Map();
+    /** `${folder}/${skill}` in a retired folder that the legacy lock wrote and assets/ retired — removed by the retired-folder cleanup below. */
+    const legacyRetiredInRetired = new Set();
     if (legacyLock !== null) {
+        // Legacy retirement: a folder the old engine fully wrote (per the
+        // lock) whose skill no longer ships in assets/ is folded into
+        // takeoverFiles so the removal pass below deletes it — the header's
+        // "dropped from assets/ is removed" promise extended to old-engine
+        // folders. A repo-subset exclusion keeps the folder (the subset only
+        // limits what THIS deploy writes, it does not retract skills assets
+        // still ships). A folder failing the ownership check (hand-modified,
+        // extra file) is left untouched: it is becoming user-owned, the same
+        // disposition as the takeover conflict case. In retired folders there
+        // is no takeover pass: the folder is only recorded, and the
+        // retired-folder cleanup removes it under the same conditions.
+        const legacyRetired = (folder, foldIntoTakeover) => {
+            const prefix = `${folder}/`;
+            for (const skill of new Set([...legacyLock.files.keys()]
+                .filter((relPath) => relPath.startsWith(prefix))
+                .map((relPath) => relPath.slice(prefix.length).split("/", 1)[0]))) {
+                if (availableSkills.includes(skill))
+                    continue; // still shipped — selected or subset path owns it
+                const skillDirRel = `${folder}/${skill}`;
+                const skillDirAbs = join(targetRepo, skillDirRel);
+                if (!existsSync(skillDirAbs))
+                    continue;
+                if (manifest.files.some((file) => file.startsWith(`${skillDirRel}/`)))
+                    continue; // already ours
+                const check = checkLegacyOwnership(legacyLock, targetRepo, skillDirRel, skillDirAbs);
+                if (!check.owned)
+                    continue;
+                if (foldIntoTakeover) {
+                    for (const relFile of walkFiles(skillDirAbs))
+                        takeoverFiles.add(`${skillDirRel}/${relFile}`);
+                }
+                else {
+                    legacyRetiredInRetired.add(skillDirRel);
+                }
+            }
+        };
         for (const surface of profile.surfaces) {
+            // az567 surfaceFilter: skip non-target surfaces entirely. The
+            // legacy-takeover pass for the non-target surface is irrelevant
+            // when only one surface is being deployed.
+            if (options.surfaceFilter !== undefined && surface.name !== options.surfaceFilter)
+                continue;
             for (const skill of selectedSkills) {
                 const skillDirRel = `${surface.folder}/${skill}`;
                 const skillDirAbs = join(targetRepo, skillDirRel);
@@ -109,10 +284,24 @@ export function deploySkills(options) {
                     takeoverConflictReasons.set(skillDirRel, check.reason);
                 }
             }
+            legacyRetired(surface.folder, true);
+        }
+        for (const folder of retiredFolders(profile)) {
+            // az567 surfaceFilter: retired-folder cleanup is also filtered to
+            // the active surfaces. A non-target surface's retired folder is
+            // left exactly as found.
+            if (options.surfaceFilter !== undefined) {
+                const isTargetActive = profile.surfaces.some((s) => s.folder === folder && s.name === options.surfaceFilter);
+                if (!isTargetActive)
+                    continue;
+            }
+            legacyRetired(folder, false);
         }
     }
     const manifestFiles = new Set([...manifest.files, ...takeoverFiles]);
     const adopted = [];
+    // Total over `selectedSkills`: every loop below iterates that same array, so
+    // `sourceFilesBySkill.get(skill)` is never undefined and needs no fallback.
     const sourceFilesBySkill = new Map();
     for (const skill of selectedSkills)
         sourceFilesBySkill.set(skill, walkFiles(join(assetsDir, skill)));
@@ -121,6 +310,11 @@ export function deploySkills(options) {
     const conflicts = [];
     const keptPaths = new Set();
     for (const surface of profile.surfaces) {
+        // az567 surfaceFilter: only iterate the named surface. Other
+        // surfaces' deploy paths, conflicts, and removal decisions are out
+        // of scope and never appear in this result.
+        if (options.surfaceFilter !== undefined && surface.name !== options.surfaceFilter)
+            continue;
         for (const skill of selectedSkills) {
             const skillDirRel = `${surface.folder}/${skill}`;
             const skillDirAbs = join(targetRepo, skillDirRel);
@@ -129,7 +323,7 @@ export function deploySkills(options) {
             // An unrecorded folder whose whole tree is byte-identical to the asset
             // is adopted: its files fall through to the write loop below as
             // unchanged and so land in the manifest. Anything else stays a conflict.
-            if (skillDirExists && !managedByUs && folderIdenticalToAsset(skillDirAbs, join(assetsDir, skill), sourceFilesBySkill.get(skill) ?? [])) {
+            if (skillDirExists && !managedByUs && folderIdenticalToAsset(skillDirAbs, join(assetsDir, skill), sourceFilesBySkill.get(skill))) {
                 managedByUs = true;
                 adopted.push(skillDirRel);
             }
@@ -142,7 +336,7 @@ export function deploySkills(options) {
                 });
                 continue; // never write into it, never claim its files in the manifest
             }
-            for (const relFile of sourceFilesBySkill.get(skill) ?? []) {
+            for (const relFile of sourceFilesBySkill.get(skill)) {
                 const targetRel = `${skillDirRel}/${relFile}`;
                 keptPaths.add(targetRel);
                 const targetAbs = join(targetRepo, targetRel);
@@ -168,6 +362,13 @@ export function deploySkills(options) {
         // already satisfy that by construction.
         if (!profile.surfaces.some((surface) => relPath.startsWith(`${surface.folder}/`)))
             continue;
+        // az567 surfaceFilter: paths under a non-target surface are not in
+        // scope and must not be removed during a per-surface deploy.
+        if (options.surfaceFilter !== undefined) {
+            const inTargetSurface = profile.surfaces.some((surface) => surface.name === options.surfaceFilter && relPath.startsWith(`${surface.folder}/`));
+            if (!inTargetSurface)
+                continue;
+        }
         const absolute = join(targetRepo, relPath);
         if (existsSync(absolute)) {
             if (!dryRun) {
@@ -191,12 +392,22 @@ export function deploySkills(options) {
     const retiredRemovals = [];
     const availableSkillSet = new Set(availableSkills);
     for (const folder of retiredFolders(profile)) {
+        // az567 surfaceFilter: only clean up retired folders that are NOT
+        // tied to a non-target surface. A retired folder is per-profile
+        // (the active-surface filters above do not reduce the retired list);
+        // when a surfaceFilter is set, retired-folder cleanup runs the same
+        // way it does for a full deploy, because retired folders are not
+        // tied to a particular active surface.
         const folderAbs = join(targetRepo, folder);
         if (!existsSync(folderAbs))
             continue;
         for (const name of directoryNames(folderAbs)) {
-            if (!availableSkillSet.has(name))
-                continue; // not ours to manage — left byte-for-byte
+            // Ours to remove when the skill still ships in assets/ (a stale
+            // duplicate of a live skill) or the legacy lock proves the old
+            // engine wrote this copy of a now-retired skill. Anything else was
+            // never this package's to manage — left byte-for-byte.
+            if (!availableSkillSet.has(name) && !legacyRetiredInRetired.has(`${folder}/${name}`))
+                continue;
             if (!dryRun)
                 removeDirRecursive(join(folderAbs, name));
             retiredRemovals.push(`${folder}/${name}`);