kushi-agents 4.0.0 → 4.1.0

package/.github/copilot-instructions.kushi.md

@@ -37,6 +37,7 @@ Project Q&A also auto-dispatches when the user names a known project under the e
 - `.kushi/instructions/` — doctrine (citations, WorkIQ-first, freshness gates)
 - `.kushi/reference-packs/` — bundled domain doctrine (override at project / workspace / packaged layers)
 - `.kushi/config/` — **user-editable** (project-evidence.yml, integrations.yml, reference-overrides). Seeded on first install; never overwritten on upgrade.
+- `.kushi/tracking/` — **agent working memory** (runs/, qa/, fde/, research/). Per-run Markdown journals: what was asked, what was done, what was decided, what's still open. Gitignored by default. See `instructions/tracking.instructions.md`.
 - `.kushi/kushi-install.json` — profile manifest written by the installer
 
 Full docs: <https://gim-home.github.io/kushi/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {

package/plugin/instructions/tracking.instructions.md

@@ -0,0 +1,165 @@
+---
+applyTo: "**"
+description: "Kushi tracking convention — every Kushi prompt/skill writes its working memory (what it was asked, what it did, what it decided, what's still open) to `<workspace>/.kushi/tracking/` so users can see, edit, diff, and resume the agent's work. This is host-agnostic (VS Code Chat, Clawpilot, Cursor) and complements — never replaces — Evidence/ (canonical outputs) or State/ (rollups)."
+---
+
+# Tracking — Agent Working Memory
+
+Kushi agents must leave a visible trail. Every meaningful run produces a small Markdown artifact under `<workspace>/.kushi/tracking/` describing what was asked, what was done, what was decided, and what is still open.
+
+This is **the journey**, not the **output**. Outputs land under `Evidence/`, `State/`, `Reports/`, `ado-updates/`, etc. Tracking files explain *why* and *how* those outputs ended up the way they did, so the user (or a future agent) can pick up where you left off.
+
+## Why this exists
+
+* **Visible thinking.** The user can read what the agent considered and rejected, not just the final artifact.
+* **Reliable handoff.** Stable filenames mean Bootstrap → Refresh → State → Ask never loses context across `/clear`, new chats, or host swaps.
+* **Resumability.** A 60-minute pull that died at 80% can be resumed from its last tracking entry instead of restarted.
+* **Audit + replay.** Diff-able, grep-able, commit-able (or gitignored — user's choice).
+* **Single convention across hosts.** Same shape in VS Code Chat, Clawpilot, Cursor, Cline.
+
+## Folder layout
+
+```
+<workspace>/.kushi/tracking/
+  .gitignore                                          ← ignore everything by default
+  runs/{{YYYY-MM-DD}}-<project>-<verb>.md             ← bootstrap / refresh / aggregate / state / consolidate
+  qa/{{YYYY-MM-DD}}-<project>-<question-slug>.md      ← /ask answers + citations, archived
+  fde/intake/{{YYYY-MM-DD}}-<project>-<slug>.md       ← /fde-intake drafts
+  fde/report/{{YYYY-MM-DD}}-<project>-<slug>.md       ← /fde-report drafts
+  fde/triage/{{YYYY-MM-DD}}-<project>-<slug>.md       ← /fde-triage drafts
+  research/{{YYYY-MM-DD}}-<topic>.md                  ← optional deep-dive notes
+```
+
+Rules:
+
+* Filenames start with `YYYY-MM-DD` (ISO date, UTC if ambiguous) so chronological sort works everywhere.
+* `<project>` is the engagement folder name (slugified — lowercase, hyphenated, no spaces).
+* `<verb>` is the prompt name without slash (`bootstrap`, `refresh`, ...).
+* `<slug>` / `<question-slug>` is 3–6 word kebab-case derived from the user's ask.
+* Create directories as needed on first write.
+
+## On first write — seed `.gitignore`
+
+If `<workspace>/.kushi/tracking/` does not yet exist, create it and write `<workspace>/.kushi/tracking/.gitignore` with:
+
+```gitignore
+# Kushi tracking files are working memory, not source of truth.
+# Outputs live under Evidence/, State/, Reports/, ado-updates/.
+# Uncomment the next line to start committing tracking artifacts.
+*
+!.gitignore
+```
+
+A user who wants to commit their agent transcripts deletes `*` from this file. Default is private.
+
+## Required sections in every tracking artifact
+
+Every tracking file is Markdown with frontmatter + a small set of named sections. Keep it short — this is a journal, not a report.
+
+```markdown
+---
+prompt: bootstrap                        # /bootstrap, /refresh, /ask, /fde-intake, ...
+project: hca                             # slugified engagement folder name
+window: last 30 days                     # bootstrap/refresh only; otherwise omit
+started: 2026-05-19T14:02:00-04:00
+finished: 2026-05-19T14:38:12-04:00      # omit if still in progress
+status: complete                         # complete | in-progress | blocked | failed
+host: vscode                             # vscode | clawpilot | cursor | cline | other
+kushi_version: 4.1.0
+---
+
+## Ask
+
+> Verbatim or near-verbatim of what the user asked for. One short paragraph.
+
+## Inputs resolved
+
+- Engagement root: `C:/.../Engagement Assets`
+- Project folder: `HCA Healthcare`
+- Alias: `ushak`
+- Config: `<workspace>/.kushi/config/project-evidence.yml`
+
+## Steps taken
+
+1. Resolved project context via `engagement-root-resolution.instructions.md`.
+2. Ran `pull-email` (WorkIQ) → 142 messages, 30-day window.
+3. Ran `pull-teams` (WorkIQ) → 11 chats, 308 messages.
+4. … (one line per meaningful step)
+
+## Decisions
+
+- Skipped `pull-crm` — `integrations.yml` has no `crm.engagement_id` for this project.
+- Used WorkIQ-only path; no `m365_*` fallback triggered.
+
+## Outputs
+
+- `HCA Healthcare/Evidence/ushak/email/snapshot/2026-05-19.md`
+- `HCA Healthcare/Evidence/ushak/teams/snapshot/2026-05-19.md`
+- `HCA Healthcare/State/00_overview.md` (updated)
+
+## Open questions / next steps
+
+- ADO field `Custom.FDEStatusSummary` is empty — recommend running `/fde-report hca` next.
+- 3 OneNote pages returned `page-body-unavailable`; see notes in `Evidence/ushak/onenote/run-notes.md`.
+
+## Errors / fallbacks
+
+- None.
+
+## Citations
+
+- `Evidence/ushak/email/snapshot/2026-05-19.md` · 2026-05-19
+- `Evidence/ushak/teams/snapshot/2026-05-19.md` · 2026-05-19
+```
+
+Section rules:
+
+* **Ask** — required. One short paragraph.
+* **Steps taken** — required. One bullet per meaningful action. Skip trivial tool calls.
+* **Decisions** — required when you chose A over B, skipped a step, or applied a fallback.
+* **Outputs** — required. Bullet list of files written/updated this run.
+* **Open questions / next steps** — required, even if empty (write "None.").
+* **Errors / fallbacks** — required when anything failed, retried, or fell back to a classified-fallback path (e.g., WorkIQ → `m365_*`).
+* **Citations** — required when the artifact references Evidence files; same format as everywhere else in Kushi (`<source-path> · <YYYY-MM-DD>`).
+
+## When to write
+
+* **First step of every prompt run:** create the file with frontmatter (`status: in-progress`) so a crash leaves something behind.
+* **As you go:** append "Steps taken" lines. Update "Outputs" when files land.
+* **Last step of every prompt run:** set `status: complete` (or `blocked` / `failed`), set `finished`, and fill in the closing sections.
+
+If the prompt runs multiple sub-skills in parallel, the orchestrating prompt owns the tracking file. Sub-skills do not write their own runs/ entry; they report back and the parent appends.
+
+## When NOT to write
+
+* `intro`, `status`, `self-check` — trivial / introspective. Skip the tracking file.
+* Any prompt that does nothing but read a single file and answer.
+* Dry-run / preview invocations (`--dry-run`, `--preview`) — log to stdout only.
+
+## Interaction with other doctrine
+
+* `update-ledger.instructions.md` — write-path skills (ADO apply, future CRM apply) still write a **ledger** under `<project>/ado-updates/<date>/`. The tracking file additionally records that a write happened and links to the ledger. Ledger is authoritative for *what was written*; tracking is the *story around it*.
+* `evidence-layout-canonical.instructions.md` — tracking files are NEVER a substitute for Evidence/. Evidence/ is the contract; tracking is the journal.
+* `answer-from-evidence.instructions.md` — `/ask` writes its answer to `qa/` *in addition to* returning it in chat, so the same question asked tomorrow can be answered from the archive (with a freshness check).
+
+## Cross-host behavior
+
+* Path is always relative to the **workspace root** (the folder the user opened in VS Code / Clawpilot / Cursor).
+* In Clawpilot specifically, the workspace root is whichever folder the user is operating on (an engagement folder, a code repo, etc.) — *not* `~/.copilot/m-skills/kushi/`. The Kushi install location and the tracking location are independent.
+* The Clawpilot weekly automation (`~/.copilot/kushi-projects.json`) is unaffected — it operates on engagement folders and produces tracking artifacts in each engagement folder's `.kushi/tracking/`.
+
+## Self-check coverage
+
+Future self-check rule **C14: tracking-artifact required** will verify:
+
+* Every prompt under `plugin/prompts/` (except the opt-out list above) references this instruction file.
+* Every prompt's closing step is "write/update the tracking artifact".
+
+C14 is added when this convention reaches 1.0 across all prompts.
+
+## References
+
+* `evidence-layout-canonical.instructions.md` — Evidence/ shape (the canonical output).
+* `update-ledger.instructions.md` — write-path ledger (orthogonal, additive).
+* `citation-ledger.instructions.md` — citation format used inside tracking artifacts.
+* `engagement-root-resolution.instructions.md` — how to resolve `<project>` for the filename slug.

package/plugin/prompts/aggregate.prompt.md

@@ -22,3 +22,5 @@ This is the **pull-only** verb. Every enabled source is pulled and per-user stre
 ```
 
 See `skills/aggregate-project/SKILL.md` for the full sequence and output contract.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-aggregate.md` as the final step.

package/plugin/prompts/ask.prompt.md

@@ -14,3 +14,5 @@ Read-only. NEVER triggers a `pull-*` skill — if evidence is stale or missing,
 You don't actually need this prompt — `ask-project` auto-routes whenever your message names a known project and asks a question (what / who / when / status / summarize / etc.). The slash form just provides an explicit handle.
 
 Delegates to `ask-project` skill.
+
+Tracking: see `tracking.instructions.md`. Archive every answer to `<workspace>/.kushi/tracking/qa/{{YYYY-MM-DD}}-<project>-<question-slug>.md` (frontmatter + Ask + Answer + Citations + freshness note).

package/plugin/prompts/bootstrap.prompt.md

@@ -20,4 +20,6 @@ Produces:
 - `<engagement-root>/<project>/Evidence/{contributors.yml, run-log.yml, <alias>/.settings.yml, <alias>/{email,teams,meetings,onenote,sharepoint,crm,ado}/{snapshot,stream}/}`
 - `<engagement-root>/<project>/State/{00..09}_*.md`
 
-Delegates to `bootstrap-project` skill. After scaffolding, calls each `pull-<source>` skill, then `build-state`.
+Delegates to `bootstrap-project` skill. After scaffolding, calls each `pull-<source>` skill, then `build-state`.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-bootstrap.md` as the final step.

package/plugin/prompts/consolidate.prompt.md

@@ -18,4 +18,6 @@ Writes:
 
 Provenance tags retained (source: <alias>/<source>/<file>) per `citation-ledger.instructions.md`.
 
-Delegates to `consolidate-evidence` skill.
+Delegates to `consolidate-evidence` skill.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-consolidate.md` as the final step.

package/plugin/prompts/fde-intake.prompt.md

@@ -39,3 +39,5 @@ Authors (first time) or updates (subsequent runs) the **FDE Intake** at `<engage
 - `skills/fde-intake/SKILL.md` for the full step-by-step.
 - `@Kushi fde-triage <project>` — produces the 7-file triage bundle that builds ON the intake.
 - `@Kushi fde-report <project> stage-readiness` — separate "should we advance the stage?" check.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/fde/intake/{{YYYY-MM-DD}}-<project>-<slug>.md` as the final step.

package/plugin/prompts/fde-report.prompt.md

@@ -44,3 +44,5 @@ Generates an FDE-shaped engagement report. Read-only against Evidence; no outbou
 - `skills/fde-report/SKILL.md` for the full step-by-step.
 - `@Kushi fde-intake <project>` — precursor first-artifact intake document.
 - `@Kushi fde-triage <project>` — full 7-file triage bundle (analysis + fitness + risk + 6Q + mobilization readiness + executive readout + reuse lens + validation warnings).
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/fde/report/{{YYYY-MM-DD}}-<project>-<shape>.md` as the final step.

package/plugin/prompts/fde-triage.prompt.md

@@ -44,3 +44,5 @@ Re-running on the same day overwrites files 00–06 in place and **merges file 0
 - `skills/fde-triage/SKILL.md` for the full step-by-step.
 - `@Kushi fde-intake <project>` — first-artifact intake document (precursor to the bundle).
 - `@Kushi fde-report <project> [shape]` — individual report shapes (weekly / short / long / fitness / stage-readiness).
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/fde/triage/{{YYYY-MM-DD}}-<project>-bundle.md` as the final step (one summary entry, not 7 — the bundle itself lives under `Reports/triage/`).

package/plugin/prompts/refresh.prompt.md

@@ -14,4 +14,6 @@ Window resolution (per `refresh-project` skill):
 
 Output is always weekly-bucketed regardless of input window.
 
-Delegates to `refresh-project` skill. Skips `pull-<source>` for sources marked disabled in `integrations.yml` or whose config is missing.
+Delegates to `refresh-project` skill. Skips `pull-<source>` for sources marked disabled in `integrations.yml` or whose config is missing.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-refresh.md` as the final step.

package/plugin/prompts/state.prompt.md

@@ -14,4 +14,6 @@ Pure renderer. Reads:
 Writes:
 - `<engagement-root>/<project>/State/{00_overview, 01_decisions, 02_stakeholders, 03_architecture-and-solution, 04_workshops-and-key-meetings, 05_action-items, 06_risks-and-issues, 07_timeline-and-milestones, 08_artifacts-and-deliverables, 09_open-questions}.md`
 
-Delegates to `build-state` skill. Use this when you've manually edited Evidence files and want State refreshed without re-pulling.
+Delegates to `build-state` skill. Use this when you've manually edited Evidence files and want State refreshed without re-pulling.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-state.md` as the final step.