kushi-agents 5.0.0 → 5.0.2

package/plugin/skills/build-state/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "build-state"
 version: "4.0.0"
-description: "Render <project>/State/ from existing Evidence. v5.0.0: emits BOTH the legacy 00–09 synthesis (retained for `full` profile parity) AND the new Karpathy-style layout (index.md + log.md + per-entity pages under people/ opportunities/ adoworkitems/ decisions/ risks/ customerasks/ meetings/ artifacts/, plus CLAUDE.md + AGENTS.md). 3-step reader fallback: _index/entities.yml → weekly/*.md → legacy snapshot/ + stream/. No source pulls — pure re-render. Latest fact wins on conflicts. Every assertion cited. Always updates Open Questions. v5 pages are ADDITIVE and distinguished by `kushi_state_page: true` front-matter."
+description: "USE WHEN the user says \"regenerate State for <X>\", \"rebuild State\", or \"@Kushi state <X>\" AND the project already has Evidence/ populated. DO NOT USE to pull new evidence (use refresh-project or pull-*). Capability: pure re-render — reads Evidence/_index/entities.yml + weekly CSC + legacy fallback, writes <project>/State/ in BOTH legacy 00–09 synthesis (full profile) AND Karpathy layout (index.md + log.md + per-entity pages + CLAUDE.md/AGENTS.md). Plan-validate-execute writer."
 ---
 
 # Skill: build-state
@@ -28,8 +28,47 @@ Run this when the user says: "regenerate state for `<X>`", "rebuild State", "@Ku
 
 - `<project>` — already-bootstrapped project.
 
+## Plan / Validate / Execute
+
+Per `plan-validate-execute.instructions.md`:
+
+1. **Plan** — before Step 2 (regenerate State files), serialize the proposed
+   state shape to `<project>/Evidence/_plan/build-state-plan.json`:
+   - `inputs[]` — every `_index/entities.yml` row, `weekly/*.md` file, and
+     legacy `snapshot/`/`stream/` fallback file the run intends to read.
+     Each entry: `{ source, alias, path, last_modified, included_in: [<state_file>, ...] }`.
+   - `proposed_state_files[]` — `{ id: "00..08", title, sections: [...],
+     citation_count, evidence_window: [from_iso, to_iso] }`.
+   - `proposed_open_questions[]` — `{ text, source_refs[] }` (the OQ list
+     Step 5 plans to write).
+   - `proposed_karpathy_emit[]` — the v5 Karpathy block paths planned for Step 6.
+2. **Validate** — for every `evidence_ref` in the plan, re-confirm the source
+   file exists and its `last_modified` matches the plan. Drop any reference
+   whose anchor no longer resolves (the underlying weekly file may have been
+   re-written between plan and execute). If validate drops > 20% of references
+   in any single State file, abort that file's write and surface the plan for
+   review.
+3. **Execute** — write `State/00..08_*.md` and the Karpathy outputs. Stamp each
+   State file's banner with the plan ID + validate-pass timestamp.
+
+The `_plan/` file is overwritten on every run and is safe to delete between
+runs — transient working artifact, not authoritative truth.
+
 ## Steps
 
+
+## Step checklist
+
+Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.
+
+- [ ] Step 1 — Read all Evidence
+- [ ] Step 2 — For each State file (00–08), regenerate
+- [ ] Step 3 — Conflict resolution
+- [ ] Step 4 — Citation density
+- [ ] Step 5 — Open Questions (mandatory every run)
+- [ ] Step 6 — v5 Karpathy emission (ADDITIVE; per `karpathy-state-layout.instructions.md`)
+- [ ] Step 7 — Banner
+
 ### Step 1 — Read all Evidence
 
 For the resolved `<project>`, apply the v4.9.0 fallback chain for each `<alias>/<source>/`:
@@ -128,4 +167,13 @@ Top of every State file:
 ## Changelog
 
 - **v4.0.0 (kushi v5.0.0, 2026-05-26)**: ADDITIVE Karpathy-style emission — per-entity pages under `State/<category>/`, `State/index.md`, `State/log.md`, `State/CLAUDE.md`, `State/AGENTS.md`. Distinguished by `kushi_state_page: true`. Legacy 00–09 synthesis is retained for `full` profile parity. Gated on `m365Mutable.state.layout` (default `karpathy`). See `..\..\instructions\karpathy-state-layout.instructions.md`.
-- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.
+- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted state`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/consolidate-evidence/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "consolidate-evidence"
 version: "3.0.0"
-description: "Merge per-contributor evidence into Evidence/_Consolidated/ for a window (v4.9.0+). 3-step reader fallback per source: _index/entities.yml → weekly/*.md → legacy snapshot/ + stream/. Provenance tags on every merged claim. Used by refresh-project and bootstrap-project when multiple contributors exist."
+description: "USE WHEN multiple contributors have pulled the same project AND the orchestrator (refresh-project / aggregate-project) needs a merged view at Evidence/_Consolidated/ for downstream skills (build-state, link-entities, ask-project). DO NOT USE manually — it's an internal pass. Capability: merges per-contributor Evidence/<alias>/<source>/ into Evidence/_Consolidated/ for a window using the 3-step reader fallback (_index → weekly → legacy). Latest-fact-wins; cites originating alias."
 ---
 
 # Skill: consolidate-evidence
@@ -71,4 +71,13 @@ When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mi
 
 ## Changelog
 
-- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.
+- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted consolidate-evidence`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/dashboard/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "dashboard"
 version: "1.0.0"
-description: "v5.0.0 — Render an interactive HTML dashboard for a project. Reads Evidence/_graph/project-graph.json + per-source _index/entities.yml + State/index.md and emits a single self-contained <project>/dashboard.html via plugin/templates/dashboard/dashboard.template.html. Uses Cytoscape.js v3 + cose-bilkent layout (inlined), Clawpilot theme variables (per the web-artifacts-builder skill), two-view tabs (Graph + Timeline), source/alias/date filters, fuzzy search, side panel with cited CSC blocks. Idempotent — fully regenerated each run."
+description: "USE WHEN the user says \"@Kushi dashboard <X>\" OR after refresh-project/bootstrap-project completes AND <project>/Evidence/_graph/project-graph.json exists. DO NOT USE before link-entities has produced a graph (no-op without it). Capability: renders single self-contained <project>/dashboard.html via Cytoscape.js v3 + cose-bilkent, Clawpilot theme variables, two-view tabs (Graph + Timeline), source/alias/date filters, fuzzy search, side panel with cited CSC blocks."
 ---
 
 # Skill: dashboard
@@ -38,6 +38,16 @@ description: "v5.0.0 — Render an interactive HTML dashboard for a project. Rea
 
 ## Steps
 
+
+## Step checklist
+
+Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.
+
+- [ ] Step 1 — Verify inputs
+- [ ] Step 2 — Collect data
+- [ ] Step 3 — Render
+- [ ] Step 4 — Verify
+
 ### Step 1 — Verify inputs
 
 If `<project>/Evidence/_graph/project-graph.json` does not exist, exit
@@ -111,3 +121,12 @@ re-run self-check D22.dashboard.
 - **v1.0.0 (kushi v5.0.0, 2026-05-26)**: initial release. Cytoscape.js v3 +
   cose-bilkent + Clawpilot theme variables; two-view tabs; side panel;
   filters; fuzzy search.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted dashboard`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/emit-vertex/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "emit-vertex"
-description: "Render vertex-shaped artifacts from kushi Evidence/+State/ — weekly status, decisions, workshops, comms, living-doc PR proposals. Stages first, validates against vertex's own schemas, applies on demand."
+description: "USE WHEN the user says \"emit vertex artifacts for <project>\", \"stage a vertex weekly status\", \"promote a kushi decision to vertex\" AND the project has been linked to vertex via vertex-link. DO NOT USE for projects with no kushi.yaml#vertex block (run vertex-link first). Capability: renders vertex-shaped artifacts (weekly status, decisions, workshops, comms, living-doc PR proposals) from kushi Evidence/ + State/; stages first; user reviews before commit."
 applyTo: ["emit-vertex"]
 version: "1.1.0"
 maturity: "preview"
@@ -171,3 +171,12 @@ Per `issue-recovery.instructions.md`. emit-vertex's pre-flight failures, schema
 - [`vertex-link/SKILL.md`](../vertex-link/SKILL.md) — sister skill that populates `kushi.yaml#vertex` mapping
 - [`docs/concepts/kushi-with-vertex.md`](../../../docs/concepts/kushi-with-vertex.md) — outcome-based user-facing guide
 - [vertex repo](https://github.com/commercial-software-engineering/vertex)
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted emit-vertex`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/fde-intake/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "fde-intake"
 version: "1.0.0"
-description: "Author or update the FDE Intake document — the first artifact in any FDE engagement. Reads project Evidence + the FDE reference pack (intake-questions + report-doctrine + core-fde-reference) and produces a single strategic brief that answers the 6 canonical FDE Intake questions. Read-only against the project; never refreshes sources; never sends outbound."
+description: "USE WHEN an FDE engagement begins AND the user says \"author the intake doc for <X>\", \"update the FDE intake\", \"kick off FDE for <X>\". DO NOT USE for non-FDE engagements or for the triage/report stages (use fde-triage / fde-report). Capability: authors or updates the FDE Intake document — the first artifact in any FDE engagement. Reads project Evidence + FDE reference pack (intake schema); fills missing fields by re-extracting from Evidence with citations."
 ---
 
 # Skill: fde-intake
@@ -145,3 +145,12 @@ Display:
 - "draft the fde intake for `<project>`"
 - "update the intake for `<project>`"
 - "@Kushi fde-intake `<project>`"
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted fde-intake`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/fde-report/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "fde-report"
 version: "1.0.0"
-description: "Generate FDE-shaped engagement reports in one of five shapes (weekly / short / long / fitness / stage-readiness), grounded in the project's Evidence/ folder AND the FDE reference pack (operating model, doctrine, intake questions, anti-patterns, fitness criteria, stage gates, CRM status meanings, risk categories). Read-only; no source pulls; no outbound."
+description: "USE WHEN the user asks for an \"FDE report\" / \"weekly status for <X>\" / \"stage-readiness report\" / \"fitness report\" / \"long-form FDE writeup\" for an FDE engagement. DO NOT USE for non-FDE reporting (use ask-project for Q&A). Capability: generates one of five FDE report shapes (weekly / short / long / fitness / stage-readiness), grounded in the project's Evidence/+State/, per the FDE reference pack templates."
 ---
 
 # Skill: fde-report
@@ -157,3 +157,12 @@ Display:
 - "fde fitness for `<project>`"
 - "stage readiness for `<project>`"
 - "@Kushi fde-report `<project>` [`<shape>`]"
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted fde-report`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/fde-triage/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "fde-triage"
 version: "1.0.0"
-description: "Produce the full FDE Triage bundle — 7 companion files at <project>/Reports/triage/<YYYY-MM-DD>/ covering analysis, fitness, risk, 6Q framing, mobilization readiness, executive readout, global reuse, and a central validation warnings tracker. Grounded in project Evidence + the FDE reference pack. Read-only; no outbound."
+description: "USE WHEN an FDE engagement reaches the triage stage AND the user says \"run FDE triage for <X>\", \"produce the triage bundle\", \"do the 6Q triage\". DO NOT USE for non-FDE engagements or for one-off reports (use fde-report). Capability: produces the full FDE Triage bundle — 7 companion files at <project>/Reports/triage/<YYYY-MM-DD>/ covering analysis, fitness, risk, 6Q framing, and recommendations."
 ---
 
 # Skill: fde-triage
@@ -112,3 +112,12 @@ Display:
 - "triage bundle for `<project>`"
 - "do the full fde triage for `<project>`"
 - "@Kushi fde-triage `<project>`"
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted fde-triage`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/intro/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "intro"
 version: "2.1.0"
-description: "Use when a user asks about Kushi, what it does, what its skills are, or wants a hands-on tour. Offers a quick overview OR an interactive walkthrough of every kushi verb (including Q&A and FDE authoring) with copy-and-send demo prompts."
+description: "USE WHEN the user asks \"what is Kushi?\", \"what can you do?\", \"show me the skills\", \"give me a tour\", or any first-touch onboarding question AND the user appears unfamiliar with kushi. DO NOT USE for project-specific work or for users already mid-workflow. Capability: offers a quick overview OR an interactive walkthrough — picks a known-bootstrapped project, runs a guided demo across ask, refresh, dashboard, tour."
 triggers:
   - "what is kushi"
   - "what can kushi do"

package/plugin/skills/link-entities/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "link-entities"
 version: "1.0.0"
-description: "v5.0.0 — Build the cross-source entity graph. Walks every contributor's Evidence/<alias>/<source>/_index/entities.yml + weekly/*.md files, runs deterministic extractors (ADO URLs, Teams meeting URLs, CRM record URLs, OneNote deep-links, conversation-id tokens, ADO/CRM token patterns), and emits Evidence/_graph/project-graph.json per entity-graph.instructions.md. LLM-augment pass is opt-in via m365Auth.linkEntities.llmInfer: true. Deterministic-first; idempotent (regenerates fully each run); multi-user safe (merges nodes by id, edges by (from,to,kind))."
+description: "USE WHEN refresh-project / bootstrap-project completes AND every enabled pull-* has written its weekly/_index pair, OR when the user says \"@Kushi link entities <X>\" / \"rebuild the graph for <X>\". DO NOT USE before any source has been pulled. Capability: walks per-contributor _index/entities.yml + weekly CSC, runs deterministic extractors, emits Evidence/_graph/project-graph.json with closed edge taxonomy. Plan-validate-execute writer (Evidence/_plan/link-entities-plan.json → validate → write graph)."
 ---
 
 # Skill: link-entities
@@ -37,8 +37,41 @@ modifies `<alias>/<source>/weekly/` or `<alias>/<source>/_index/`.
 - `<engagement-root>/<project>/Evidence/_graph/project-graph.json` —
   per `entity-graph.instructions.md` schema.
 
+## Plan / Validate / Execute
+
+Per `plan-validate-execute.instructions.md`:
+
+1. **Plan** — before Step 5 (merge+write), serialize the proposed merges to
+   `<project>/Evidence/_plan/link-entities-plan.json`:
+   - `nodes_in[]` — every node loaded from `_index/entities.yml` across contributors.
+   - `proposed_edges[]` — `{ from_id, to_id, kind, score, evidence_refs[] }`.
+   - `proposed_aliases[]` — `{ canonical_id, alias_ids[], confidence }`.
+   - `tombstones[]` — entries that would be removed/superseded.
+2. **Validate** — re-read each `evidence_ref` in `proposed_edges[]` against
+   the source `<alias>/<source>/_index/entities.yml` and `weekly/*.md`. Drop
+   any edge whose anchor no longer resolves. Drop alias rows whose confidence
+   falls below `link-entities.alias_min_confidence` (default 0.85).
+3. **Execute** — only after validate passes, write
+   `<project>/Evidence/_graph/project-graph.json` and the per-source
+   `entity-links.yml` upserts. If validate drops > 20% of proposed edges,
+   abort and surface the plan file for human review (do NOT execute).
+
+The `_plan/` file is overwritten on every run and is safe to delete between
+runs — transient working artifact, not authoritative truth.
+
 ## Steps
 
+
+## Step checklist
+
+Progress-trackable view of the steps below. Each `### Step` block expands the corresponding checkbox.
+
+- [ ] Step 1 — Discover contributors + sources
+- [ ] Step 2 — Load nodes from `_index/entities.yml`
+- [ ] Step 3 — Run deterministic extractors over `weekly/*.md`
+- [ ] Step 4 — LLM augment (opt-in)
+- [ ] Step 5 — Merge + write
+
 ### Step 1 — Discover contributors + sources
 
 Walk `<project>/Evidence/` for direct subdirectories (excluding names
@@ -214,3 +247,12 @@ the merge predicate), then re-run with `-Json` and inspect the envelope.
 
 - **v1.0.0 (kushi v5.0.0, 2026-05-26)**: initial release. Deterministic-first
   graph producer; opt-in LLM augment; multi-user merge.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted graph`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/project-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "project-status"
 version: "2.0.0"
-description: "Show the run-log status for a project: per-source watermarks, last-pulled, item counts, weekly_files index, recent errors. No source calls."
+description: "USE WHEN the user asks \"what's the status of <X>?\", \"when was <X> last refreshed?\", \"any errors in <X>?\", \"show the run-log for <X>\" for an already-bootstrapped project. DO NOT USE to answer substantive questions about project content (use ask-project). Capability: read-only — shows per-source watermarks, last-pulled, item counts, weekly_files index, recent errors from run-log.yml. No source calls."
 ---
 
 # Skill: project-status

package/plugin/skills/propose-ado-update/SKILL.md

@@ -2,7 +2,7 @@
 name: "propose-ado-update"
 version: "0.1.0-preview"
 status: "preview"
-description: "Read-only generator: reads the latest <project>/Evidence/_Consolidated/ and produces <project>/ado-updates/<YYYY-MM-DD>/proposed.md — a Markdown preview of the proposed ADO Initiative updates (FDE Status Summary field + Discussion comment). Performs NO writes to ADO. Safe to run unattended on the same Monday-9am schedule as refresh."
+description: "USE WHEN the user says \"propose ADO updates for <X>\", \"draft work-item edits from this week's evidence\", \"what should I update in ADO for <X>?\" AND <project>/Evidence/_Consolidated/ exists. DO NOT USE to push edits to ADO (use apply-ado-update). Capability: read-only generator — reads latest Consolidated evidence, produces <project>/ado-updates/<YYYY-MM-DD>/proposed.md with a Markdown diff per work-item field."
 ---
 
 # Skill: propose-ado-update
@@ -110,4 +110,13 @@ Refuse to produce `proposed.md` and tell the user exactly what's missing if any
 
 ## Issue Recovery
 
-When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted propose-ado-update`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.

package/plugin/skills/pull-ado/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "pull-ado"
 version: "3.0.0"
-description: "v3.0.0 (kushi v4.9.0): Pull ADO evidence as Comprehensive Structured Capture (CSC) blocks written to weekly/YYYY-MM-DD_ado-csc.md. One block per work item touched that week, upserted in _index/entities.yml. ADO REST + tree expansion UNCHANGED — only output shape changes. WI fields → CSC sections (AssignedTo→Participants, Description→Topics, State changes→Decisions, Comments→Q&A+Who Said What, etc.). No snapshot/+stream/ split. Per-contributor _index/. See weekly-csc + comprehensive-structured-capture doctrines."
+description: "USE WHEN refresh-project / bootstrap-project dispatches ADO source OR the user says \"pull ADO for <X>\" AND the project has integrations.yml#boundaries.ado.org_project set. DO NOT USE for non-kushi ADO queries or for write operations (use propose-ado-update / apply-ado-update). Capability: pulls ADO evidence as Comprehensive Structured Capture (CSC) blocks written to weekly/YYYY-MM-DD_ado-csc.md, one block per work item touched that week, upserted in _index/entities.yml. WorkIQ-only."
 ---
 
 # Skill: pull-ado
@@ -22,6 +22,14 @@ description: "v3.0.0 (kushi v4.9.0): Pull ADO evidence as Comprehensive Structur
 > - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
 > - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
 
+## Gotchas
+
+- **Work-item URL is the canonical id** — `ado://org=<o>/project=<p>/workitem=<id>`. Title is not stable across edits.
+- **Discussion comments are stream-only** — comments don''t change `Changed Date` on the parent work item. Use the comments collection for incrementality; CSC bullets cite per-comment timestamps.
+- **ADO-not-complete is a first-class state** — when WorkIQ returns partial work-item data (e.g. missing custom fields), log `ado-not-complete` in `_index/entities.yml#status` and retry next refresh. Do NOT fabricate field values.
+- **Parent/child links use different relation names per process template** — `System.LinkTypes.Hierarchy-Forward` vs `Microsoft.VSTS.Common.TestedBy-Forward`. Don''t hard-code; read the relation list and classify.
+- **Iteration paths contain slashes that look like file paths** — escape when rendering citations: `<Org>\<Project>\<Iter>` not `<Org>/<Project>/<Iter>`.
+
 ## v4.9.0 — Comprehensive Structured Capture (CSC) + weekly/ layout (HARD RULE; supersedes all snapshot/+stream/ guidance below)
 
 Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructions.md`:
@@ -69,8 +77,8 @@ Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructi
   - Iteration dates, story points, effort → **Dates & Numbers Shared**
   - Discussion comments → **Q&A** (when Q-and-A pattern detected) + **Who Said What**
   - Tags, related WIs, parent-child links, attachment metadata → **Artifacts/Links**
-- Entity id: `ado://org=<org>/project=<project>/workitemid=<int>`.
-
+- Entity id: `ado://org=<org>/project=<project>/workitemid=<int>`.
+
 Pulls **ado** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 
 - **snapshot/** — engagement TREE: parent Engagement + every child WI; each item gets full fields + every discussion comment verbatim + full revision history
@@ -299,11 +307,11 @@ After successful pass:
 - Step 1 returns zero candidates → record `no-match` + WIQL + `next_step`, stop.
 - A child WI fetch fails → mark `❌ item-fetch-failed` in `tree.md`, continue tree.
 - Discussion paging fails mid-stream → record `❌ comments-partial — N/M fetched` and continue.
-
-## References (v4.4.7)
-
-- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
-- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
+
+## References (v4.4.7)
+
+- Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
 
 
 ## Issue Recovery
@@ -324,4 +332,13 @@ An entity that cannot meet the threshold is flagged `low_signal: true` in `_inde
   changes. WI fields mapped to CSC sections (AssignedTo→Participants, Description→Topics, State
   changes→Decisions, Comments→Q&A+Who Said What, etc.). AI Narrative Summary requirement removed.
   Legacy snapshot/+stream/ folders left readable; no migration.
-- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted pull-ado`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.