kushi-agents 6.1.2 → 6.2.0

package/plugin/instructions/skill-authoring.instructions.md

@@ -0,0 +1,147 @@
+---
+name: "skill-authoring"
+description: "v5.0.4 — How to author a new kushi skill so it ships conformant to the agentskills.io blueprint on day one. Codifies the required SKILL.md sections, file layout, evals starter, naming, and the description-optimization rules. Read this before running `npx kushi-agents create-skill`. Enforced by self-check D34.creator-conformance + by `kushi check-skill --lint`."
+applies_to: "every plugin/skills/<name>/ created from v5.0.4 onward; existing skills are audited via the dogfood gate"
+since: "kushi v5.0.4"
+---
+
+# skill-authoring — doctrine
+
+> Inspired by **Anthropic's [skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md)**. Adapted to kushi's PowerShell-first stack, our 2-host install matrix, and the reality that the first 30 kushi skills were authored before any harness existed — hence the **retrofit** path in `skill-checker`.
+
+## Why this exists
+
+A SKILL.md is the prompt that loads into the agent the moment its trigger fires. Drift between intent and spec is silent until evals catch it (and only if there are evals). This doctrine + the `skill-creator` + `skill-checker` skills make conformant authoring the default, not an afterthought.
+
+## Required files per skill
+
+```text
+plugin/skills/<name>/
+├── SKILL.md                 ← REQUIRED — agent-loaded prompt; ≤500 lines, ≤5000 tokens
+├── evals/
+│   └── evals.json           ← REQUIRED — ≥2 cases, each with ≥1 assertion
+├── references/              ← OPTIONAL — load-on-trigger bulk content (>500 lines splits here)
+└── .created-by-skill-creator  ← OPTIONAL marker — set by `scaffold.ps1`; opts into the strict D34 gate
+```
+
+A skill MAY also ship a runner (`run.ps1`, `run.sh`, `*.mjs`) when it's a tool-skill (`self-check`, `eval`, `skill-checker`, etc.). Pure prompt-skills don't need one.
+
+## Required SKILL.md sections
+
+Every SKILL.md MUST have:
+
+1. **YAML frontmatter** — `name` (kebab-case, matches dir) + `description` (lead with `USE WHEN`).
+2. **`# Skill: <name>`** H1.
+3. **One-paragraph purpose** immediately after the H1.
+4. **At least one** of these procedure-shape sections, picked by skill **type**:
+   - `## Gotchas` — REQUIRED for `pull-*` and discovery skills (top-5 failure modes).
+   - `## Step checklist` — REQUIRED for orchestrators (`bootstrap-project`, `refresh-project`, `build-state`, `link-entities`, `dashboard`, `tour`, etc.); use GitHub `- [ ]` checkboxes.
+   - `## Validation loop` — REQUIRED for writer skills (anything that writes to `Evidence/`, `State/`, `_graph/`, `dashboards/`, `tours/`).
+   - `## Steps` or `## Procedure` — acceptable for other skills, plus one of the three above where it applies.
+
+Skills can have more than one (e.g. `eval` ships all three). The checker is satisfied by **at least one** of `Gotchas` / `Step checklist` / `Validation loop` plus type-specific rules.
+
+## Description optimization (per agentskills.io)
+
+The `description:` is the sole trigger signal. Optimize it:
+
+```yaml
+description: "USE WHEN <situational trigger> AND <precondition>. DO NOT USE for <near-miss>. <one-line capability summary>."
+```
+
+Rules (enforced by `D30.description-optimized` + `skill-checker --optimize-description`):
+
+- Lead with `USE WHEN` (first 160 chars).
+- Include a `DO NOT USE` clause for the most likely near-miss invocation.
+- Be specific about the trigger (concrete user phrases or file/state conditions).
+- No marketing fluff ("powerful", "comprehensive", "blazing").
+- ≤1024 characters total.
+
+| Bad | Good |
+|---|---|
+| `"Pulls OneNote pages."` | `"USE WHEN refreshing project evidence for a known kushi project AND boundaries.onenote.section_ids is non-empty. DO NOT USE for global OneNote search."` |
+| `"Comprehensive eval framework."` | `"USE WHEN the user says 'run evals', 'eval canary', or before tagging a release. DO NOT USE for evidence validation of a real project."` |
+
+## Size caps
+
+- ≤ 500 lines (`D30.skill-size`)
+- ≤ 5000 tokens (~20 KB)
+
+When you exceed either, **split into `references/<topic>.md` files** and cite them with explicit triggers:
+
+```markdown
+Load `references/canonical-prompts.md` when constructing the WorkIQ query.
+Load `references/error-modes.md` if the API returns non-200.
+```
+
+Passive links (`[see foo](references/foo.md)`) do NOT count. The checker requires the literal substring `references/<file>.md` somewhere in SKILL.md if `references/` exists.
+
+## Evals (≥2 cases)
+
+Every skill MUST ship `evals/evals.json` validated against `plugin/skills/eval/evals.schema.json`. Per `skill-evals.instructions.md`:
+
+- `id`, `name`, `input`, `expected_assertions[]` (≥1), `grader_type` (`script` | `llm`).
+- ≥2 cases. Mark canary-worthy ones `"canary": true`.
+- Synthetic fixtures only — never real customer data.
+
+The `create-skill` scaffold emits a starter `evals.json` with one `file-exists` and one `regex-match` case so the skill ships green from minute one.
+
+## Naming conventions
+
+- **Skill directory + frontmatter `name`** — kebab-case, verb-led (`pull-onenote`, `consolidate-evidence`, `apply-ado-update`).
+- **Skill types** (informational; pick at create time so the scaffold picks the right sections):
+  - `pull` — fetches evidence from a source.
+  - `writer` — writes files to `Evidence/` or `State/`.
+  - `orchestrator` — coordinates other skills.
+  - `other` — utility / tool / meta.
+- **Instruction files** — `<topic>.instructions.md` in `plugin/instructions/`. Front-matter `name:` matches filename minus `.instructions.md`.
+
+## Contributor workflow
+
+```powershell
+# 1. Scaffold
+npx kushi-agents create-skill my-new-skill
+#   → answers: type (pull|writer|orchestrator|other), one-liner description
+#   → emits plugin/skills/my-new-skill/{SKILL.md, evals/evals.json}
+#   → marker file .created-by-skill-creator is written
+
+# 2. Fill in the placeholders (search for "TODO(skill-creator)")
+
+# 3. Validate
+npx kushi-agents check-skill my-new-skill        # lint mode
+npm run eval -- my-new-skill                     # run evals
+
+# 4. Optimize description before PR
+npx kushi-agents optimize-description my-new-skill
+#   → emits a rewritten description; you decide whether to apply
+
+# 5. Self-check + commit
+pwsh plugin/skills/self-check/run.ps1 -Deep
+git add plugin/skills/my-new-skill/
+git commit -m "v<x.y.z>: my-new-skill"
+```
+
+## Retrofit (existing skills predating the harness)
+
+Run `npx kushi-agents check-skill --all --retrofit` to identify gaps in legacy skills. `--apply` adds missing section stubs with `<!-- TODO(retrofit): fill in -->` markers — never overwrites existing content. The v5.0.4 dogfood report at `docs/audits/v5.0.4-skill-creator-dogfood.md` records the baseline.
+
+## Enforcement
+
+| Check | What it does |
+|---|---|
+| `D34.skill-creator-exists` | `plugin/skills/skill-creator/scaffold.ps1` is parseable. |
+| `D34.skill-checker-exists` | `plugin/skills/skill-checker/check-skill.ps1` is parseable. |
+| `D34.creator-output-conforms` | Every skill carrying `.created-by-skill-creator` passes `check-skill --lint`. |
+| `D34.retrofit-clean` | `check-skill --all --retrofit --dry-run` shows no unresolved non-additive gaps. |
+| `D34.dogfood-report-fresh` | `docs/audits/v5.0.4-skill-creator-dogfood.md` was touched within 14 days (warn-only). |
+
+## References
+
+- `plugin/instructions/agentskills-compliance.instructions.md` — the spec rules this builds on.
+- `plugin/instructions/skill-evals.instructions.md` — the evals doctrine.
+- `plugin/skills/skill-creator/SKILL.md` — the scaffolder.
+- `plugin/skills/skill-checker/SKILL.md` — the linter / retrofitter.
+- `docs/contributing/skill-authoring.md` — the human walkthrough.
+- <https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md> — upstream inspiration.
+- <https://agentskills.io/skill-creation/best-practices>
+- <https://agentskills.io/skill-creation/optimizing-descriptions>

package/plugin/instructions/skill-evals.instructions.md

@@ -0,0 +1,130 @@
+---
+description: "v5.0.3 — Skill evals doctrine, adapted from https://agentskills.io/skill-creation/evaluating-skills. Every skill MUST ship an evals/ folder with at least 2 deterministic cases plus structured assertions; a per-skill pass-rate is the objective regression signal. Canary subset runs on every PR; full suite runs on demand. Real customer data is FORBIDDEN in fixtures — use synthetic data only."
+---
+
+# Skill evals — doctrine
+
+> Inspired by **<https://agentskills.io/skill-creation/evaluating-skills>**. Adapted to kushi's PowerShell + Node test stack and to our 2-host install matrix.
+
+## Why
+
+Skills are prompts plus a runner. Prompts drift silently. Without an objective per-skill regression signal, every change is a gamble. Evals make that signal cheap:
+
+- **Per-skill pass-rate** is the headline metric.
+- **Latency** and **tokens** are secondary metrics (regressions ≥50% latency / ≥10pp pass-rate flag a baseline failure).
+- A **canary subset** runs on every PR (target: < 60s wall clock); the **full suite** runs on demand (`npm run eval:all`).
+
+## Where evals live
+
+```text
+plugin/skills/<name>/
+├── SKILL.md
+└── evals/
+    ├── evals.json        ← REQUIRED — case list + assertions
+    └── fixtures/         ← OPTIONAL per-skill fixtures
+```
+
+Cross-skill fixtures live at the repo root:
+
+```text
+evals/
+├── baseline.json         ← Committed; maintainer updates with `npm run eval:baseline`
+└── fixtures/             ← Tiny synthetic evidence trees, ADO fixtures, etc.
+```
+
+Per-run output goes to `Evidence/_evals/<timestamp>.json` (gitignored; not customer data).
+
+## Case schema
+
+```jsonc
+{
+  "skill": "<skill-name>",
+  "cases": [
+    {
+      "id": "ap-citations-format",
+      "name": "ask-project emits weekly-csc citation form",
+      "input": "what was decided about MACC for fixture-acme?",
+      "fixture": "evals/fixtures/fixture-acme",        // optional
+      "canary": true,
+      "grader_type": "script",                          // "script" | "llm"
+      "expected_assertions": [
+        { "type": "regex-match", "pattern": "\\[source:\\s*fixture-acme/email/weekly/" },
+        { "type": "regex-match", "pattern": "Source-layout:\\s*weekly-csc" }
+      ]
+    }
+  ]
+}
+```
+
+### Required fields per case
+
+- `id` — unique within the skill; kebab-case.
+- `name` — human-readable.
+- `input` — what gets passed to the skill (string OR object).
+- `expected_assertions` — array, **≥ 1** entry (enforced by `D33.evals-have-assertions`).
+- `grader_type` — `"script"` for deterministic graders, `"llm"` for rubric-based.
+
+### Optional fields
+
+- `fixture` — repo-relative path to the fixture to point the skill at.
+- `canary` — `true` to include in the fast CI subset.
+- `args` — extra args forwarded to the skill script (e.g. `{ "DryRun": true }`).
+- `skip` — `true` to skip (must include `skip_reason`).
+- `timeout_ms` — override the runner default (30 000 ms).
+
+## Assertion types
+
+| Type | Shape | Passes when |
+|---|---|---|
+| `file-exists` | `{ "type": "file-exists", "path": "..." }` | Path exists post-run (relative to fixture or evidence dir). |
+| `file-contains` | `{ "type": "file-contains", "path": "...", "needle": "..." }` | File exists and substring is present. |
+| `json-path-equals` | `{ "type": "json-path-equals", "path": "...", "json_path": "$.foo.bar", "equals": "v" }` | JSON file parses; dotted path value === expected. |
+| `regex-match` | `{ "type": "regex-match", "pattern": "...", "flags": "i" }` | Captured stdout matches the regex. |
+| `llm-rubric` | `{ "type": "llm-rubric", "rubric": "...", "min_score": 4 }` | LLM grader scores ≥ min on a 1–5 rubric. |
+
+## Run modes
+
+The runner (`plugin/skills/eval/run-evals.ps1`) supports three dispatch modes:
+
+1. **Direct invocation** (default for `script` graders). Runs the skill's executable artifact (`run.ps1`, `*.mjs`, or a small probe stub) with the given input and fixture. Pure deterministic.
+2. **Sub-agent dispatch** (optional, gated by `-Live`). Forwards the case to a sub-agent. Used only for `llm-rubric` cases. Skipped in canary mode.
+3. **Recorded fixture replay** (for `pull-*` skills). Reads a recorded `--cached` output of a real pull and asserts against that, so no live M365 calls are needed.
+
+For each case the runner records: `pass`, `duration_ms`, `tokens_in`, `tokens_out`, `stdout`, `stderr`, per-assertion `pass`/`reason`. The aggregate is a JSON file under `Evidence/_evals/` plus a one-line `benchmark.json` summary.
+
+## Canary set
+
+Marked with `"canary": true`. Kept tiny so PRs stay fast.
+
+Default canary set (v5.0.3):
+
+- `ask-project`
+- `bootstrap-project`
+- `refresh-project`
+- `link-entities`
+- `build-state`
+- `self-check`
+
+## Baseline + regression detection
+
+- `evals/baseline.json` is **committed**.
+- Each per-skill record carries the last green `pass_rate`, `mean_duration_ms`, and `mean_tokens_total`.
+- `src/eval-aggregator.mjs` flags **regressions**:
+  - `pass_rate` drop ≥ 10 percentage points
+  - `mean_duration_ms` increase ≥ 50 %
+  - `mean_tokens_total` increase ≥ 50 %
+- Maintainers refresh the baseline with `npm run eval:baseline` after deliberate behavior changes.
+
+## Privacy + safety
+
+- **No real customer data** in any fixture. Use `fixture-acme`-style synthetic names.
+- `Evidence/_evals/` is in `.gitignore`.
+- `pull-*` evals NEVER hit live M365 endpoints in canary mode. Use recorded `--cached` payloads or `--dry-run`.
+- Tenant IDs / GUIDs in fixtures must be obviously fake (e.g. `00000000-...`).
+
+## References
+
+- [agentskills.io — evaluating skills](https://agentskills.io/skill-creation/evaluating-skills) (source of truth)
+- `plugin/skills/eval/SKILL.md` (the runner skill)
+- `plugin/skills/eval/evals.schema.json` (JSON schema; self-check D33.evals-schema)
+- `plugin/instructions/agentskills-compliance.instructions.md` (sibling doctrine — size + section caps)

package/plugin/runners/bootstrap.mjs

@@ -26,7 +26,7 @@ import {
   aliasRoot, projectSharedFile, userFile, USER_FILES,
 } from './lib/layout.mjs';
 import { writeAtomic, pathExists } from './lib/evidence.mjs';
-import { writeRefreshReport, appendRunLog } from './lib/runlog.mjs';
+import { writeRefreshReport, writeBootstrapStatus, appendRunLog } from './lib/runlog.mjs';
 
 function parseArgs(argv) {
   const args = { force: false, dryRun: false, lookbackDays: null, interactive: false };
@@ -329,11 +329,11 @@ async function main() {
   }
 
   const startedAt = new Date(); // capture when scaffold started (before report)
-  // v6.1.2: write bootstrap report to refresh-reports/<ts>_bootstrap.md per
-  // run-reports doctrine. Bootstrap is scaffold-only (no HTTP, no pulls), so
-  // the report enumerates files/dirs created vs. existed, plus optional
-  // dateFloor + interactive outcomes. Diagnostics-only; never blocks.
+  // v6.2.0: write bootstrap report per run-reports.instructions.md (proper
+  // sectioned format) AND write bootstrap-status.md per
+  // bootstrap-status-format.instructions.md. Diagnostics-only; never blocks.
   let reportPath = null;
+  let statusPath = null;
   if (!args.dryRun) {
     try {
       const created = log.created.map(p => path.relative(root, p) || '.');
@@ -342,30 +342,37 @@ async function main() {
         (dateFloorReport && dateFloorReport.fields?.length ? ` dateFloor=${dateFloorReport.dateFloor}` : '') +
         (interactiveReport && interactiveReport.fields?.length ? ` interactive=${interactiveReport.fields.length}` : '');
       const details = {
-        mode: 'bootstrap',
         contributor: args.alias,
         started: startedAt.toISOString(),
         ended: new Date().toISOString(),
-        scope: 'scaffold-only (no HTTP, no pulls)',
-        what_was_done: {
-          configs_probed: ['integrations.yml', 'project-info.md', 'external-links.yml', 'contributors.yml'],
-          shared_dirs: SHARED_DIRS,
-          user_dirs: USER_DIRS,
-          per_user_files: ['boundaries.yml', 'external-links.local.yml', '_ledger.yml'],
-          counts: {
-            created: created.length,
-            existed: existed.length,
-          },
-        },
-        created,
-        existed,
-        date_floor: dateFloorReport || null,
-        interactive: interactiveReport || null,
+        window: 'scaffold-only (no HTTP, no pulls)',
+        profile: 'standard',
+        what_was_done_table: [
+          { source: 'scaffold', action: 'create-or-skip', items: `${created.length} created / ${existed.length} existed`, outcome: 'completed', notes: 'project + Evidence trees + per-user dirs' },
+          ...(dateFloorReport ? [{ source: 'm365-auth', action: 'stamp dateFloor', items: (dateFloorReport.fields || []).length, outcome: dateFloorReport.updated ? 'completed' : 'skipped', notes: dateFloorReport.reason || dateFloorReport.dateFloor || '' }] : []),
+          ...(interactiveReport ? [{ source: 'interactive', action: 'prompt user', items: (interactiveReport.fields || []).length, outcome: 'completed', notes: 'fields stamped into m365-auth.json' }] : []),
+        ],
+        resolutions: [],
+        cleanups: [],
+        learnings: [],
         skips_and_gaps: [
           'Bootstrap is scaffold-only — no source pulls performed.',
           'Run `kushi discover <project>` next to populate boundaries.yml/integrations.yml.',
-          'Then `kushi refresh <project>` to capture per-source CSC weekly files.',
+          'Then `kushi refresh <project>` to capture per-source weekly evidence.',
+        ],
+        created,
+        existed,
+        next_steps: [
+          'Run `kushi discover <project>` to map boundaries (email folders, Teams chats, OneNote sections, SharePoint sites).',
+          'Run `kushi refresh <project>` to pull the current week of evidence from M365 + CRM + ADO.',
+          'Review `Evidence/<alias>/bootstrap-status.md` for the current durable state snapshot.',
         ],
+        date_floor: dateFloorReport || null,
+        interactive: interactiveReport || null,
+        counts: {
+          created: created.length,
+          existed: existed.length,
+        },
       };
       const r = await writeRefreshReport(args.project, args.alias, {
         type: 'bootstrap',
@@ -373,6 +380,30 @@ async function main() {
         details,
       });
       reportPath = r?.path || null;
+
+      // Bootstrap-status.md: durable per-user fast-orientation artifact.
+      try {
+        const s = await writeBootstrapStatus(args.project, args.alias, {
+          project: path.basename(root),
+          customer_hint: '',
+          mode: 'bootstrap',
+          lookback_days: args.lookbackDays || null,
+          preflight: [
+            { check: 'integrations.yml present', status: existed.includes('integrations.yml') ? 'present' : 'created', notes: '' },
+            { check: 'project-info.md present', status: existed.includes('project-info.md') ? 'present' : 'created', notes: '' },
+            { check: 'Evidence/_shared scaffold', status: 'present', notes: SHARED_DIRS.join(', ') },
+            { check: `Evidence/${args.alias}/ scaffold`, status: 'present', notes: USER_DIRS.join(', ') },
+          ],
+          artifacts: [],
+          outcome: [
+            'Project scaffold complete. No pulls performed.',
+            'Run `kushi discover` next to map boundaries from M365 signals.',
+          ],
+          access_limitations: [],
+        });
+        statusPath = s?.path || null;
+      } catch { /* status is diagnostics-only */ }
+
       try {
         await appendRunLog(args.project, {
           mode: 'bootstrap',
@@ -380,6 +411,7 @@ async function main() {
           status: 'ok',
           summary: summaryLine,
           report: reportPath ? path.relative(root, reportPath) : null,
+          status_md: statusPath ? path.relative(root, statusPath) : null,
         });
       } catch { /* run-log is diagnostics-only */ }
     } catch { /* bootstrap-report is diagnostics-only, never block */ }
@@ -393,6 +425,7 @@ async function main() {
     existed: log.existed.map(p => path.relative(root, p) || '.'),
     dry_run: args.dryRun,
     ...(reportPath ? { report: path.relative(root, reportPath) } : {}),
+    ...(statusPath ? { status_md: path.relative(root, statusPath) } : {}),
     ...(dateFloorReport ? { date_floor: dateFloorReport } : {}),
     ...(interactiveReport ? { interactive: interactiveReport } : {}),
   });

package/plugin/runners/lib/runlog.mjs

@@ -46,16 +46,163 @@ export async function writeRefreshReport(project, alias, { type, summary, detail
 }
 
 function renderRefreshReport({ type, ts, summary, details }) {
+  const d = details || {};
+  const localTs = ts.toLocaleString('sv-SE').slice(0, 16); // "YYYY-MM-DD HH:mm"
   const lines = [
-    `# ${type ?? 'refresh'} — ${ts.toISOString()}`,
+    `# ${type ? type.replace(/^./, c => c.toUpperCase()) : 'Refresh'} Report — ${localTs}`,
     '',
-    summary || '',
+    `- **Mode**: ${type || 'refresh'}`,
+    `- **Contributor**: ${d.contributor ?? '_unknown_'}`,
+    `- **Window**: ${d.window ?? d.week ?? '_n/a_'}`,
+    `- **Profile**: ${d.profile ?? 'standard'}`,
+    `- **Started**: ${d.started ?? ts.toISOString()}`,
+    `- **Ended**: ${d.ended ?? ts.toISOString()}`,
+    `- **Duration**: ${d.duration ?? _computeDuration(d.started, d.ended)}`,
     '',
-    '## Details',
-    '```yaml',
-    YAML.stringify(details).trimEnd(),
-    '```',
+  ];
+  if (summary) lines.push(summary, '');
+
+  // ## What was done
+  lines.push('## What was done', '');
+  if (Array.isArray(d.what_was_done_table) && d.what_was_done_table.length) {
+    lines.push('| Source | Action | Items pulled | Outcome | Notes |',
+               '|---|---|---|---|---|');
+    for (const r of d.what_was_done_table) {
+      lines.push(`| ${r.source ?? ''} | ${r.action ?? ''} | ${r.items ?? ''} | ${r.outcome ?? ''} | ${r.notes ?? ''} |`);
+    }
+    lines.push('');
+  } else if (d.what_was_done) {
+    lines.push('```yaml', YAML.stringify(d.what_was_done).trimEnd(), '```', '');
+  } else {
+    lines.push('_None this run._', '');
+  }
+
+  // ## Resolutions this run
+  lines.push('## Resolutions this run', '');
+  if (Array.isArray(d.resolutions) && d.resolutions.length) {
+    for (const r of d.resolutions) lines.push(`- ${typeof r === 'string' ? r : YAML.stringify(r).trim()}`);
+    lines.push('');
+  } else { lines.push('_None this run._', ''); }
+
+  // ## Cleanups this run
+  lines.push('## Cleanups this run', '');
+  if (Array.isArray(d.cleanups) && d.cleanups.length) {
+    for (const r of d.cleanups) lines.push(`- ${typeof r === 'string' ? r : YAML.stringify(r).trim()}`);
+    lines.push('');
+  } else { lines.push('_None this run._', ''); }
+
+  // ## Learnings appended
+  lines.push('## Learnings appended', '');
+  if (Array.isArray(d.learnings) && d.learnings.length) {
+    for (const r of d.learnings) lines.push(`- ${typeof r === 'string' ? r : YAML.stringify(r).trim()}`);
+    lines.push('');
+  } else { lines.push('_None this run._', ''); }
+
+  // ## Skips & gaps
+  lines.push('## Skips & gaps', '');
+  if (Array.isArray(d.skips_and_gaps) && d.skips_and_gaps.length) {
+    for (const r of d.skips_and_gaps) lines.push(`- ${typeof r === 'string' ? r : YAML.stringify(r).trim()}`);
+    lines.push('');
+  } else { lines.push('_None this run._', ''); }
+
+  // ## Files written
+  lines.push('## Files written', '');
+  const created = Array.isArray(d.created) ? d.created : (Array.isArray(d.files_written) ? d.files_written : []);
+  if (created.length) {
+    lines.push('| Path | Type |', '|---|---|');
+    for (const f of created) {
+      const p = typeof f === 'string' ? f : (f.path ?? '');
+      const t = typeof f === 'object' ? (f.type ?? '') : '';
+      lines.push(`| \`${p}\` | ${t} |`);
+    }
+    lines.push('');
+  } else { lines.push('_None this run._', ''); }
+
+  // ## Next steps
+  lines.push('## Next steps for this contributor', '');
+  if (Array.isArray(d.next_steps) && d.next_steps.length) {
+    for (const r of d.next_steps) lines.push(`- ${typeof r === 'string' ? r : YAML.stringify(r).trim()}`);
+    lines.push('');
+  } else { lines.push('_None this run._', ''); }
+
+  // ## Run summary (counts)
+  if (d.counts && typeof d.counts === 'object') {
+    lines.push('## Run summary', '',
+               '| Metric | Count |', '|---|---|');
+    for (const [k, v] of Object.entries(d.counts)) lines.push(`| ${k} | ${v} |`);
+    lines.push('');
+  }
+
+  // ## Raw details (for machine readers / debugging)
+  lines.push('## Raw details', '', '```yaml', YAML.stringify(d).trimEnd(), '```', '');
+  return lines.join('\n');
+}
+
+function _computeDuration(startIso, endIso) {
+  if (!startIso || !endIso) return '_n/a_';
+  try {
+    const ms = new Date(endIso) - new Date(startIso);
+    if (!Number.isFinite(ms) || ms < 0) return '_n/a_';
+    const s = Math.round(ms / 1000);
+    const h = Math.floor(s / 3600), m = Math.floor((s % 3600) / 60), sec = s % 60;
+    return `${h}h ${m}m ${sec}s`;
+  } catch { return '_n/a_'; }
+}
+
+/**
+ * Write Evidence/<alias>/bootstrap-status.md per bootstrap-status-format.instructions.md.
+ * Short, scannable summary of durable project state — NOT a run narrative.
+ */
+export async function writeBootstrapStatus(project, alias, status) {
+  const p = path.join(aliasRoot(project, alias), USER_FILES.bootstrapStatus);
+  const md = renderBootstrapStatus(status);
+  await writeAtomic(p, md, { skipIfUnchanged: false });
+  return { path: p };
+}
+
+function renderBootstrapStatus(s) {
+  const ts = new Date();
+  const localTs = ts.toLocaleString('sv-SE').slice(0, 16);
+  const lines = [
+    '# Bootstrap Status',
+    '',
+    `- Bootstrap Date: ${localTs}`,
+    `- Project: ${s.project ?? ''}`,
+    `- Customer Hint: ${s.customer_hint ?? ''}`,
+    `- Mode: ${s.mode ?? 'bootstrap'}`,
+    `- Lookback Window: ${s.lookback_days ?? '_n/a_'}`,
+    '',
+    '## Preflight Checks',
     '',
+    '| Check | Status | Notes |',
+    '|---|---|---|',
   ];
+  for (const c of (s.preflight || [])) {
+    lines.push(`| ${c.check ?? ''} | ${c.status ?? ''} | ${c.notes ?? ''} |`);
+  }
+  if ((s.preflight || []).length === 0) lines.push('| _none recorded_ | | |');
+  lines.push('',
+             '## Context Artifact Status',
+             '',
+             '| Artifact | Status | Notes |',
+             '|---|---|---|');
+  for (const a of (s.artifacts || [])) {
+    lines.push(`| ${a.artifact ?? ''} | ${a.status ?? ''} | ${a.notes ?? ''} |`);
+  }
+  if ((s.artifacts || []).length === 0) lines.push('| _none recorded_ | | |');
+  lines.push('',
+             '## Current Bootstrap Outcome',
+             '');
+  for (const r of (s.outcome || ['_None this run._'])) lines.push(`- ${r}`);
+  lines.push('',
+             '## Access Limitations',
+             '',
+             '| System | Status | Reason | Workaround |',
+             '|---|---|---|---|');
+  for (const a of (s.access_limitations || [])) {
+    lines.push(`| ${a.system ?? ''} | ${a.status ?? ''} | ${a.reason ?? ''} | ${a.workaround ?? ''} |`);
+  }
+  if ((s.access_limitations || []).length === 0) lines.push('| _none recorded_ | | | |');
+  lines.push('');
   return lines.join('\n');
 }