kushi-agents 6.1.2 → 6.2.0

package/plugin/templates/state/09_open-questions.template.md

@@ -0,0 +1,62 @@
+# Open Questions & Low-Fidelity Items — {{project_name}}
+
+> **Purpose.** Living list of things we don't yet know, are unsure about, or have only partial / second-hand info on. Each item gets resolved → moves to **Resolved** section with the answer + source. Never delete — the history is the audit trail.
+
+**As of:** {{as_of_date}}
+**Maintained by:** project-evidence skill (auto-updated each run; humans may add / edit freely)
+
+---
+
+## Conventions
+
+- **ID:** `Q-NNN` (monotonic, never reused)
+- **Status:** `🔴 Open` · `🟡 Partial` (some info, more needed) · `🟢 Resolved` · `⚫ Stale` (no longer relevant — leave with reason)
+- **Fidelity:** `Low` (rumor / inferred / single second-hand source) · `Medium` (one direct source, unconfirmed) · `High` (confirmed from authoritative source — at which point it usually moves to a State file and Q is Resolved)
+- **Category:** `People` · `Scope` · `Timeline` · `Architecture` · `Decision` · `Risk` · `Process` · `Funding` · `Data` · `Other`
+- **Needed By:** date or milestone the answer is needed for (blank = nice-to-know)
+- **Source:** evidence file or person where the question originated
+- **Resolution:** when status flips to 🟢, fill answer + source + date; the resolved item also gets folded into the right State file (00–08) and that destination is recorded in **Folded Into**
+
+---
+
+## 🔴 Open / 🟡 Partial
+
+| ID | Status | Fidelity | Category | Question / Concern | Needed By | Asked Of | Source | Notes |
+|---|---|---|---|---|---|---|---|---|
+| Q-001 | 🔴 Open | Low | _example_ | _What is the customer's preferred go-live date?_ | _next steering_ | _Acct team_ | _Evidence/ushak/Teams-Chats/2026-04-27_ | _Mentioned in passing, no commitment_ |
+
+<!-- Add new rows above this line. Keep newest at top within each status. -->
+
+---
+
+## 🟢 Resolved
+
+| ID | Resolved On | Question | Answer | Source of Answer | Folded Into |
+|---|---|---|---|---|---|
+| _(none yet)_ | | | | | |
+
+---
+
+## ⚫ Stale / No Longer Relevant
+
+| ID | Marked Stale On | Question | Reason |
+|---|---|---|---|
+| _(none yet)_ | | | |
+
+---
+
+## How items get added
+
+1. **Auto** — during a weekly run, the skill flags anything where evidence is conflicting, second-hand, or implies a follow-up question. Each becomes a new `Q-NNN` row with Fidelity=Low or Medium.
+2. **Manual** — anyone can add a row. Use next free `Q-NNN`.
+3. **From action items** — if an `AI-NNN` blocks on a question, mirror it here and cross-reference.
+
+## How items get resolved
+
+1. When evidence comes in (a meeting transcript, a CRM/ADO update, an email reply) the skill updates the row's Fidelity → Medium/High and may flip Status → 🟢.
+2. On resolution, the answer is also written into the appropriate State file (00–08), and **Folded Into** points to it.
+3. The row stays here forever as audit trail.
+
+## How items go stale
+
+If the question stops mattering (scope cut, customer dropped the topic, decision overtaken), flip to ⚫ with reason. Do not delete.

package/plugin/templates/state/AGENTS.template.md

@@ -0,0 +1,33 @@
+# AGENTS.md — kushi project agent doc
+
+> _Mirror of `CLAUDE.md`. Written by `build-state` from `plugin/templates/state/AGENTS.template.md`. Preserved across runs if user-edited._
+
+This is a **kushi**-managed project. Everything authoritative about the project lives under:
+
+- `Evidence/<alias>/<source>/weekly/<YYYY-MM-DD>_<source>-csc.md` — per-week, per-source, per-contributor Comprehensive Structured Capture (CSC) blocks.
+- `Evidence/<alias>/<source>/_index/entities.yml` — per-contributor entity index (canonical entity-id, latest CSC file, last_touched).
+- `Evidence/_graph/project-graph.json` — cross-source entity graph (nodes + edges with citations).
+- `State/` — synthesized wiki pages. v5 pages have `kushi_state_page: true` in front-matter; legacy v4.x State files live alongside.
+
+## Reading rules for AI agents
+
+1. **Cite every claim.** Every assertion about this project MUST carry an inline citation of the form `[source: <alias>/<source>/weekly/<file>#<entity-anchor> · <iso-ts>]`. If you cannot cite, do not claim.
+2. **Use `[[wikilinks]]`.** When referring to a State page, use `[[slug]]` — slug = lowercase-kebab-case of the page title. The wikilink resolves to `State/<category>/<slug>.md`. Categories: people, opportunities, adoworkitems, decisions, risks, customerasks, meetings, artifacts.
+3. **Graph-first for cross-source questions.** If the question spans sources ("what ADO items did the May 7 meeting decide?", "who owns the action items from this opp?"), consult `Evidence/_graph/project-graph.json` first to find connected entities, THEN read the cited weekly files for the body.
+4. **Never invent IDs.** Canonical entity-id formats are defined in `plugin/instructions/weekly-csc.instructions.md` (email://, teams://, meetings://, onenote://, sharepoint://, crm://, ado://). The graph never invents IDs; neither should you.
+5. **Open the dashboard for visual orientation.** `<project>/dashboard.html` is a single self-contained HTML file. Open in any browser; click a node to surface its cited CSC blocks.
+6. **Start with the tour.** `State/tour.md` is the auto-generated week-in-review walkthrough. Top-N entities by recency × cross-reference count.
+
+## Writing rules for AI agents
+
+- **Do NOT modify `Evidence/`.** That folder is owned by the `pull-*` skills.
+- **Do NOT modify `State/index.md`, `State/log.md`, `State/tour.md`, or `State/<category>/*.md` pages with `kushi_state_page: true`.** Those are owned by `build-state` + `tour` and regenerated each run.
+- Legacy State files (`State/00_overview.md`, `State/05_action-items.md`, etc., without the `kushi_state_page` flag) ARE user-editable when the project profile is `standard` — `build-state` only touches them on `full` profile.
+
+## Related kushi doctrines
+
+- `plugin/instructions/entity-graph.instructions.md`
+- `plugin/instructions/karpathy-state-layout.instructions.md`
+- `plugin/instructions/weekly-csc.instructions.md`
+- `plugin/instructions/comprehensive-structured-capture.instructions.md`
+- `plugin/instructions/citation-ledger.instructions.md`

package/plugin/templates/state/CLAUDE.template.md

@@ -0,0 +1,33 @@
+# CLAUDE.md — kushi project agent doc
+
+> _Mirror of `AGENTS.md`. Written by `build-state` from `plugin/templates/state/CLAUDE.template.md`. Preserved across runs if user-edited._
+
+This is a **kushi**-managed project. Everything authoritative about the project lives under:
+
+- `Evidence/<alias>/<source>/weekly/<YYYY-MM-DD>_<source>-csc.md` — per-week, per-source, per-contributor Comprehensive Structured Capture (CSC) blocks.
+- `Evidence/<alias>/<source>/_index/entities.yml` — per-contributor entity index (canonical entity-id, latest CSC file, last_touched).
+- `Evidence/_graph/project-graph.json` — cross-source entity graph (nodes + edges with citations).
+- `State/` — synthesized wiki pages. v5 pages have `kushi_state_page: true` in front-matter; legacy v4.x State files live alongside.
+
+## Reading rules for AI agents
+
+1. **Cite every claim.** Every assertion about this project MUST carry an inline citation of the form `[source: <alias>/<source>/weekly/<file>#<entity-anchor> · <iso-ts>]`. If you cannot cite, do not claim.
+2. **Use `[[wikilinks]]`.** When referring to a State page, use `[[slug]]` — slug = lowercase-kebab-case of the page title. The wikilink resolves to `State/<category>/<slug>.md`. Categories: people, opportunities, adoworkitems, decisions, risks, customerasks, meetings, artifacts.
+3. **Graph-first for cross-source questions.** If the question spans sources ("what ADO items did the May 7 meeting decide?", "who owns the action items from this opp?"), consult `Evidence/_graph/project-graph.json` first to find connected entities, THEN read the cited weekly files for the body.
+4. **Never invent IDs.** Canonical entity-id formats are defined in `plugin/instructions/weekly-csc.instructions.md` (email://, teams://, meetings://, onenote://, sharepoint://, crm://, ado://). The graph never invents IDs; neither should you.
+5. **Open the dashboard for visual orientation.** `<project>/dashboard.html` is a single self-contained HTML file. Open in any browser; click a node to surface its cited CSC blocks.
+6. **Start with the tour.** `State/tour.md` is the auto-generated week-in-review walkthrough. Top-N entities by recency × cross-reference count.
+
+## Writing rules for AI agents
+
+- **Do NOT modify `Evidence/`.** That folder is owned by the `pull-*` skills.
+- **Do NOT modify `State/index.md`, `State/log.md`, `State/tour.md`, or `State/<category>/*.md` pages with `kushi_state_page: true`.** Those are owned by `build-state` + `tour` and regenerated each run.
+- Legacy State files (`State/00_overview.md`, `State/05_action-items.md`, etc., without the `kushi_state_page` flag) ARE user-editable when the project profile is `standard` — `build-state` only touches them on `full` profile.
+
+## Related kushi doctrines
+
+- `plugin/instructions/entity-graph.instructions.md`
+- `plugin/instructions/karpathy-state-layout.instructions.md`
+- `plugin/instructions/weekly-csc.instructions.md`
+- `plugin/instructions/comprehensive-structured-capture.instructions.md`
+- `plugin/instructions/citation-ledger.instructions.md`

package/plugin/templates/state/README.md

@@ -0,0 +1,41 @@
+# Contoso — Current State
+
+**As of:** 2026-05-06
+**Status:** Pre-engagement / fit-assessment phase
+**Source:** Consolidated from `Evidence\<contributor>\*` summaries through week of 2026-04-27. Latest evidence wins on conflicts.
+
+This folder is **outcome-based**, not source-based. Each file answers a single question about the project's current truth. The per-source weekly summaries under `Evidence\` remain the audit trail.
+
+---
+
+## Files in this folder
+
+| File | Answers |
+|------|---------|
+| `00_overview.md` | What is this engagement? Where does it stand right now? |
+| `01_decisions.md` | What has been decided (and what was superseded)? |
+| `02_stakeholders.md` | Who is involved? Roles, accountability, contact. |
+| `03_architecture-and-solution.md` | What is being built / proposed? Use cases, components, dependencies. |
+| `04_workshops-and-key-meetings.md` | What significant meetings/workshops happened or are planned? |
+| `05_action-items.md` | What's owed, by whom, by when — open items only. |
+| `06_risks-and-issues.md` | What could derail this, and what's the mitigation? |
+| `07_timeline-and-milestones.md` | What's the trajectory — past, present, planned? |
+| `08_artifacts-and-deliverables.md` | What concrete artifacts exist (decks, docs, recordings, code)? |
+| `09_open-questions.md` | What don't we know yet, what's low-fidelity, and what's been answered? Living tracker — items move from 🔴 Open → 🟡 Partial → 🟢 Resolved (never deleted). |
+
+---
+
+## Conventions
+
+- **Latest evidence wins** on conflicts. Each fact carries `[as of YYYY-MM-DD, source: <alias>/<source>/<file>]`.
+- A **Supersedes:** line preserves the prior value when a fact changes (e.g., owner change), so history isn't lost.
+- A short `## Conflicts` section appears wherever contributors disagree.
+- Files are **regenerated on each refresh** from the latest weekly summaries — do not hand-edit; edit the source summary instead.
+
+---
+
+## How to refresh
+
+1. Ensure all contributors' weekly summaries under `Evidence\<alias>\` are up to date.
+2. Run the consolidation/state-refresh step. This re-reads every weekly summary, sorts facts by their evidence date, and emits these `State\*.md` files.
+3. The run-log (`Evidence\run-log.md`) records when State was last refreshed and from what cutoff.

package/plugin/templates/state/answers.README.md

@@ -0,0 +1,7 @@
+# State/answers/
+
+This folder contains filed-back Q&A answers from `ask-project --file-back`.
+
+Each file is named `YYYY-MM-DD_<slug>.md` and contains the question, answer, and source citations.
+
+These are durable knowledge artifacts — they persist across refreshes and serve as a queryable FAQ for the project.

package/plugin/templates/state/hot.template.md

@@ -0,0 +1,12 @@
+---
+kushi_state_hot: true
+generated_at: "{{generated_at}}"
+---
+
+# Hot — {{project}}
+
+> _Auto-generated. Entities touched in the last 7 days, ranked by recency. Content between fences is regenerated on every build-state run._
+
+<!-- kushi:auto:start section="hot-entities" -->
+{{hot_entities}}
+<!-- kushi:auto:end section="hot-entities" -->

package/plugin/templates/state/index.template.md

@@ -0,0 +1,41 @@
+---
+kushi_state_index: true
+generated_at: "{{generated_at}}"
+generated_by_alias: "{{alias}}"
+---
+
+# State Index — {{project}}
+
+> _Auto-regenerated by `build-state` on every run. Lists every v5 State page (those with `kushi_state_page: true` in front-matter). Legacy v4.x State files (00–08 + 09_open-questions) live alongside and are not enumerated here._
+
+## People
+
+{{people_links}}
+
+## Opportunities
+
+{{opportunities_links}}
+
+## ADO Work Items
+
+{{adoworkitems_links}}
+
+## Decisions
+
+{{decisions_links}}
+
+## Risks
+
+{{risks_links}}
+
+## Customer Asks
+
+{{customerasks_links}}
+
+## Meetings
+
+{{meetings_links}}
+
+## Artifacts
+
+{{artifacts_links}}

package/plugin/templates/state/log.template.md

@@ -0,0 +1,14 @@
+---
+kushi_state_log: true
+---
+
+# State Log — {{project}}
+
+> _Chronological refresh log. One entry per `bootstrap-project` or `refresh-project` run. Appended (never rewritten) by `build-state`._
+
+## {{first_entry_timestamp}} · {{first_entry_alias}} · {{first_entry_mode}}
+
+- **Sources pulled:** {{first_entry_sources}}
+- **Entities added:** {{first_entry_added}}
+- **Entities updated:** {{first_entry_updated}}
+- **Link-entities edges added:** {{first_entry_edges_added}}

package/plugin/templates/state/page.template.md

@@ -0,0 +1,22 @@
+---
+kushi_state_page: true
+category: "{{category}}"
+entity_ids: {{entity_ids_yaml}}
+related: {{related_yaml}}
+last_synthesized_iso: "{{last_synthesized_iso}}"
+synthesized_by_alias: "{{alias}}"
+---
+
+# {{title}}
+
+## Summary
+
+{{summary}}
+
+## Cross-references
+
+{{related_bullets}}
+
+## Evidence
+
+{{evidence_bullets}}

package/plugin/templates/state/review-queue.template.md

@@ -0,0 +1,10 @@
+---
+kushi_state_review_queue: true
+---
+
+# Review Queue
+
+> _Open contradictions requiring human review. Updated by build-state when contradictions are detected. Cleared when resolved (auto or manual)._
+
+| Entity | Property | Old value | New value | Flagged | Sources |
+|---|---|---|---|---|---|

package/plugin/runners/test/integration/csc-pull.integration.test.mjs

@@ -1,160 +0,0 @@
-// plugin/runners/test/integration/csc-pull.integration.test.mjs
-//
-// Integration tests for the WorkIQ-only CSC pull pipeline (kushi v6.1.0+).
-// One table-driven suite covers all 5 user-scoped sources
-// (email, teams, meetings, onenote, sharepoint) — they share lib/csc-pull.mjs,
-// so a single contract test fixture set proves them all.
-//
-// Fixture shape (WorkIQ stdout, NOT Graph JSON):
-//   { "stdout": "> [block: csc]\n> entity_id: ...", "stderr": "", "exitCode": 0 }
-
-import { test, beforeEach, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { spawnSync } from 'node:child_process';
-import YAML from 'yaml';
-import { fileURLToPath } from 'node:url';
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(HERE, '..', '..', '..', '..');
-const FIXTURE_DIR = path.join(HERE, '..', 'fixtures');
-
-const RUNNERS = {
-  email:      path.join(REPO_ROOT, 'plugin', 'runners', 'pull-email.mjs'),
-  teams:      path.join(REPO_ROOT, 'plugin', 'runners', 'pull-teams.mjs'),
-  meetings:   path.join(REPO_ROOT, 'plugin', 'runners', 'pull-meetings.mjs'),
-  onenote:    path.join(REPO_ROOT, 'plugin', 'runners', 'pull-onenote.mjs'),
-  sharepoint: path.join(REPO_ROOT, 'plugin', 'runners', 'pull-sharepoint.mjs'),
-};
-
-const ENTITIES = {
-  email:      'Inbox/102. Test Project',
-  teams:      '19:abc123@thread.v2',
-  meetings:   'https://teams.microsoft.com/l/meetup-join/abc',
-  onenote:    'sectionFileId-deadbeef',
-  sharepoint: 'https://contoso.sharepoint.com/sites/test',
-};
-
-const WEEK = '2026-05-25';
-
-let projectRoot;
-beforeEach(async () => {
-  projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kushi-csc-int-'));
-  await fs.mkdir(path.join(projectRoot, 'Evidence', 'ushak'), { recursive: true });
-});
-afterEach(async () => { await fs.rm(projectRoot, { recursive: true, force: true }); });
-
-function runRunner(source, fixtureName, extra = []) {
-  const fixture = path.join(FIXTURE_DIR, fixtureName);
-  return spawnSync(process.execPath, [RUNNERS[source],
-    '--project', projectRoot, '--alias', 'ushak',
-    '--entity', ENTITIES[source],
-    '--week', WEEK, '--fixture', fixture,
-    ...extra,
-  ], { encoding: 'utf8' });
-}
-
-for (const source of Object.keys(RUNNERS)) {
-  test(`[${source}] captured: writes weekly CSC + index + raw + ledger`, async () => {
-    const res = runRunner(source, 'csc-captured.json');
-    assert.equal(res.status, 0, `stderr: ${res.stderr}`);
-    const result = JSON.parse(res.stdout.trim().split('\n').pop());
-    assert.equal(result.status, 'captured');
-    assert.equal(result.items_pulled, 2);
-    assert.equal(result.source, source);
-
-    const sourceDir = path.join(projectRoot, 'Evidence', 'ushak', source);
-    const weeklyFile = path.join(sourceDir, 'weekly', `${WEEK}_${source}-csc.md`);
-    const md = await fs.readFile(weeklyFile, 'utf8');
-    assert.match(md, /Kickoff agenda/);
-    assert.match(md, /Architecture review notes/);
-    assert.match(md, new RegExp(`# ${source.toUpperCase()} CSC`));
-
-    const idx = YAML.parse(await fs.readFile(path.join(sourceDir, '_index', 'entities.yml'), 'utf8'));
-    assert.equal(idx.entities.length, 2);
-    assert.ok(idx.entities.every(e => e.id.startsWith(`${source}://`)));
-    assert.ok(idx.entities.every(e => e.weeks_touched.includes(WEEK)));
-
-    const ledger = YAML.parse(await fs.readFile(path.join(projectRoot, 'Evidence', 'ushak', '_ledger.yml'), 'utf8'));
-    const cell = ledger.entries[`${source}::${ENTITIES[source]}::${WEEK}`];
-    assert.ok(cell);
-    assert.equal(cell.last_status, 'captured');
-    assert.equal(cell.items_pulled, 2);
-
-    const rawFiles = await fs.readdir(path.join(sourceDir, '_raw'));
-    assert.equal(rawFiles.length, 1);
-  });
-
-  test(`[${source}] no-activity: empty stdout → status no-activity, no weekly file`, async () => {
-    const res = runRunner(source, 'csc-empty.json');
-    assert.equal(res.status, 0);
-    const result = JSON.parse(res.stdout.trim().split('\n').pop());
-    assert.equal(result.status, 'no-activity');
-    assert.equal(result.items_pulled, 0);
-    let exists = true;
-    try { await fs.access(path.join(projectRoot, 'Evidence', 'ushak', source, 'weekly', `${WEEK}_${source}-csc.md`)); }
-    catch { exists = false; }
-    assert.equal(exists, false);
-  });
-
-  test(`[${source}] throttled: deferred + no learning candidate`, async () => {
-    const res = runRunner(source, 'csc-throttled.json');
-    assert.equal(res.status, 0);
-    const result = JSON.parse(res.stdout.trim().split('\n').pop());
-    assert.equal(result.status, 'deferred');
-    assert.match(result.errors[0].signature, /throttled/);
-    let learningExists = true;
-    try { await fs.access(path.join(projectRoot, 'Evidence', '_learnings-candidates')); }
-    catch { learningExists = false; }
-    assert.equal(learningExists, false, 'throttled is retryable; should NOT emit learning candidate');
-  });
-
-  test(`[${source}] novel error: failed + learning candidate`, async () => {
-    const res = runRunner(source, 'csc-novel-error.json');
-    assert.equal(res.status, 0);
-    const result = JSON.parse(res.stdout.trim().split('\n').pop());
-    assert.equal(result.status, 'failed');
-    const candDir = path.join(projectRoot, 'Evidence', '_learnings-candidates');
-    const entries = await fs.readdir(candDir);
-    const md = entries.filter(f => f.endsWith('.md'));
-    assert.equal(md.length, 1, `expected 1 candidate, got: ${entries.join(', ')}`);
-  });
-
-  test(`[${source}] citation tokens / placeholders are filtered → no-activity`, async () => {
-    const res = runRunner(source, 'csc-citation-tokens.json');
-    assert.equal(res.status, 0);
-    const result = JSON.parse(res.stdout.trim().split('\n').pop());
-    assert.equal(result.status, 'no-activity', `bogus turn1searchN / <value> blocks must be dropped`);
-  });
-
-  test(`[${source}] dry-run: no files written, ledger empty`, async () => {
-    const res = runRunner(source, 'csc-captured.json', ['--dry-run']);
-    assert.equal(res.status, 0);
-    const result = JSON.parse(res.stdout.trim().split('\n').pop());
-    assert.deepEqual(result.files_written, []);
-    let ledgerExists = true;
-    try { await fs.access(path.join(projectRoot, 'Evidence', 'ushak', '_ledger.yml')); }
-    catch { ledgerExists = false; }
-    assert.equal(ledgerExists, false);
-  });
-
-  test(`[${source}] missing --entity exits 2`, () => {
-    const res = spawnSync(process.execPath, [RUNNERS[source],
-      '--project', projectRoot, '--alias', 'ushak',
-      '--fixture', path.join(FIXTURE_DIR, 'csc-captured.json'),
-    ], { encoding: 'utf8' });
-    assert.equal(res.status, 2);
-  });
-
-  test(`[${source}] idempotent: re-running same fixture is a no-op rewrite`, async () => {
-    const r1 = runRunner(source, 'csc-captured.json');
-    assert.equal(r1.status, 0);
-    const r2 = runRunner(source, 'csc-captured.json');
-    assert.equal(r2.status, 0);
-    const idx = YAML.parse(await fs.readFile(path.join(projectRoot, 'Evidence', 'ushak', source, '_index', 'entities.yml'), 'utf8'));
-    assert.equal(idx.entities.length, 2, 'rerun must not duplicate entities');
-    assert.equal(idx.entities[0].weeks_touched.length, 1, 'rerun same week must not duplicate weeks_touched');
-  });
-}