kushi-agents 5.4.3 → 5.4.5

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

@@ -1,6 +1,6 @@
 ---
 name: "consolidate-evidence"
-version: "3.0.0"
+version: "3.1.0"
 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."
 ---
 
@@ -59,6 +59,98 @@ Snapshots are mostly per-source-of-truth (one canonical entity), so consolidatio
 
 Append a `consolidation_runs:` entry: `{ window, contributors, files_written }`.
 
+### Step 5 — Consolidate per-user authored files (v5.4.4+)
+
+Per `multi-user-shared-files.instructions.md` § "Per-user authored files", three artifacts are written per-user under `Evidence/<alias>/<file>`. This step emits the cross-contributor rollup under `_Consolidated/<file>` for each. Deterministic merge — NO LLM. Idempotent: same input set produces byte-identical output.
+
+This step **always runs** (even with a single contributor — a single-alias rollup is just a verbatim copy with an attribution header).
+
+For each of the three files (`bootstrap-status.md`, `FOLLOW-UPS.md`, `OPEN-QUESTIONS-DRAFT.md`):
+
+1. Walk `<project>/Evidence/<alias>/<file>` for every alias listed in `Evidence/contributors.yml` (skip aliases that don't have the file).
+2. Apply the merge rules below.
+3. Write the result atomically to `<project>/_Consolidated/<file>` (write to `<file>.tmp`, then rename).
+
+#### `_Consolidated/bootstrap-status.md`
+
+Shape:
+
+```markdown
+# Bootstrap Status (consolidated, <N> contributors)
+
+> Auto-generated by `consolidate-evidence` Step 5 at <ISO-ts>. Source of truth lives under each `Evidence/<alias>/bootstrap-status.md`. Do not edit by hand.
+
+## Contributors who have bootstrapped this project
+
+| Alias | Display Name | Last Run | Mode | Outcome |
+|---|---|---|---|---|
+| <alias> | ... | ... | ... | ... |
+
+## Latest discovery sweep results (most recent resolved per source, across all contributors)
+
+| Source | Status | Discovered by | Discovered at |
+|---|---|---|---|
+| crm | resolved | ushak | 2026-05-27 09:42 EDT |
+| ado | resolved | stand | 2026-05-25 11:01 EDT |
+...
+
+## Per-contributor bootstrap-status snapshots
+
+### ushak — `Evidence/ushak/bootstrap-status.md`
+
+<verbatim copy of that file's body, demoted one heading level>
+
+### stand — `Evidence/stand/bootstrap-status.md`
+
+<verbatim copy>
+```
+
+- The "Contributors" table is harvested from each per-user file's `## Run summary` row.
+- The "Latest discovery sweep results" table is harvested from each per-user file's `## Context Artifact Status` table; per source, keep the row whose Status is `resolved` (or `populated`) with the most recent timestamp.
+- Per-contributor snapshot bodies are copied verbatim with heading levels demoted (`#` → `##`, etc.) for unambiguous Markdown nesting.
+
+#### `_Consolidated/FOLLOW-UPS.md`
+
+Shape:
+
+```markdown
+# Follow-ups (consolidated, <N> contributors)
+
+> Auto-generated by `consolidate-evidence` Step 5 at <ISO-ts>. Source of truth lives under each `Evidence/<alias>/FOLLOW-UPS.md`. Do not edit by hand.
+
+## Open follow-ups
+
+### <source> · <YYYY-MM-DD> · <alias> (also reported by: <other-alias>, ...)
+
+<verbatim 5-field block from the originating alias's `Evidence/<alias>/FOLLOW-UPS.md`>
+
+## Resolved follow-ups
+
+<dedup-merged blocks tagged with originating alias>
+```
+
+- Dedup key per row: `(source, normalized first line of "Next-time-do")`. When two aliases report the same gap, keep the earliest-dated block and append "also reported by: <alias>" to the heading.
+- Resolution status is per-alias — a row stays in "Open" if ANY contributor still has it Open.
+
+#### `_Consolidated/OPEN-QUESTIONS-DRAFT.md`
+
+Shape:
+
+```markdown
+# Open questions (consolidated, <N> contributors)
+
+> Auto-generated by `consolidate-evidence` Step 5 at <ISO-ts>. Source of truth lives under each `Evidence/<alias>/OPEN-QUESTIONS-DRAFT.md`. Do not edit by hand.
+
+| # | Question | Source | Earliest asked | Asked by | Status |
+|---|---|---|---|---|---|
+| 1 | ... | ... | 2026-05-20 | ushak, stand | open |
+| 2 | ... | ... | 2026-05-22 | stand | open |
+```
+
+- Dedup key: lowercase + whitespace-collapsed question text.
+- Earliest-asked = MIN(per-alias asked-on date).
+- Asked-by column = sorted union of every alias that asked it.
+
 ## Triggers
 
 - "consolidate `<X>` last `<N>` days"
@@ -71,6 +163,7 @@ When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mi
 
 ## Changelog
 
+- **v3.1.0 (kushi v5.4.4, 2026-05-27)**: Step 5 added — consolidate per-user authored files (`bootstrap-status.md`, `FOLLOW-UPS.md`, `OPEN-QUESTIONS-DRAFT.md`) into `_Consolidated/<file>`. Deterministic merge, no LLM. Always runs (even single-contributor). Cross-references per-user truth at `Evidence/<alias>/<file>`.
 - **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

package/plugin/skills/doctor/doctor.ps1

@@ -27,12 +27,51 @@ pwsh plugin/skills/doctor/doctor.ps1 -Json
 param(
     [string]$Repo = (Resolve-Path (Join-Path $PSScriptRoot "..\..\..")).Path,
     [switch]$Json,
-    [switch]$Strict
+    [switch]$Strict,
+    [ValidateSet('auto','source','install')] [string]$LayoutMode = 'auto'
 )
 
 $ErrorActionPreference = 'Continue'
 $sections = New-Object System.Collections.Generic.List[object]
 
+# === v5.4.5: layout-portable doctor ===
+function Resolve-KushiLayout([string]$RootPath) {
+    if (Test-Path (Join-Path $RootPath 'plugin')) {
+        return @{ Mode='source';  Plugin=(Join-Path $RootPath 'plugin'); Repo=$RootPath; HasPluginJson=$true }
+    }
+    if (Test-Path (Join-Path $RootPath 'skills')) {
+        $pj = Join-Path $RootPath 'kushi-install.json'
+        return @{ Mode='install'; Plugin=$RootPath; Repo=$RootPath; HasPluginJson=(Test-Path $pj) }
+    }
+    throw "Not a kushi layout: $RootPath (need either plugin/ or skills/)."
+}
+
+function Get-KushiInstallHost([string]$InstallRoot) {
+    $norm = ($InstallRoot -replace '\\','/').ToLower()
+    if ($norm -match '/\.copilot/') { return 'clawpilot' }
+    if ($norm -match '/\.vscode/')  { return 'vscode' }
+    return 'unknown'
+}
+
+$Layout = Resolve-KushiLayout $Repo
+if ($LayoutMode -ne 'auto' -and $Layout.Mode -ne $LayoutMode) {
+    if ($LayoutMode -eq 'source') {
+        if (-not (Test-Path (Join-Path $Repo 'plugin'))) { Write-Error "LayoutMode=source requested but no plugin/ under $Repo."; exit 2 }
+        $Layout = @{ Mode='source'; Plugin=(Join-Path $Repo 'plugin'); Repo=$Repo; HasPluginJson=$true }
+    } else {
+        if (-not (Test-Path (Join-Path $Repo 'skills'))) { Write-Error "LayoutMode=install requested but no skills/ under $Repo."; exit 2 }
+        $Layout = @{ Mode='install'; Plugin=$Repo; Repo=$Repo; HasPluginJson=(Test-Path (Join-Path $Repo 'kushi-install.json')) }
+    }
+}
+
+if (-not $Json) {
+    if ($Layout.Mode -eq 'install') {
+        Write-Host ("[layout=install (host={0})]" -f (Get-KushiInstallHost $Layout.Repo))
+    } else {
+        Write-Host "[layout=source]"
+    }
+}
+
 function Add-Section {
     param(
         [string]$Name,
@@ -90,9 +129,15 @@ if ($envProblems.Count -eq 0) {
 
 # ── Section 2: self-check -Deep ─────────────────────────────────────────────
 Write-Banner "2. self-check -Deep" "Cyan"
-$selfCheckPath = Join-Path $Repo 'plugin\skills\self-check\run.ps1'
+if ($Layout.Mode -eq 'source') {
+    $selfCheckPath = Join-Path $Layout.Plugin 'skills\self-check\run.ps1'
+} else {
+    $selfCheckPath = Join-Path $Layout.Plugin 'skills\self-check\run.ps1'
+}
 if (Test-Path $selfCheckPath) {
-    $scJson = & pwsh -NoProfile -File $selfCheckPath -Deep -Json -Root $Repo 2>$null
+    $scArgs = @('-NoProfile','-File',$selfCheckPath,'-Deep','-Json','-Root',$Layout.Repo)
+    if ($Layout.Mode -eq 'install') { $scArgs += @('-LayoutMode','install') }
+    $scJson = & pwsh @scArgs 2>$null
     $scExit = $LASTEXITCODE
     $scFindings = @()
     try { $scFindings = $scJson | ConvertFrom-Json } catch {}
@@ -106,15 +151,24 @@ if (Test-Path $selfCheckPath) {
             Write-Host "  ⚠️  $scCount finding(s)" -ForegroundColor Yellow
             foreach ($f in $scFindings) { Write-Host "      [$($f.code)] $($f.message)" -ForegroundColor DarkYellow }
         }
-        Add-Section 'self-check' 'yellow' "$scCount finding(s)" 'pwsh plugin/skills/self-check/run.ps1 -Deep   # then fix each [code]'
+        Add-Section 'self-check' 'yellow' "$scCount finding(s)" 'pwsh skills/self-check/run.ps1 -Deep   # then fix each [code]'
     }
 } else {
     if (-not $Json) { Write-Host "  ❌ run.ps1 missing" -ForegroundColor Red }
-    Add-Section 'self-check' 'red' 'run.ps1 not found' "Restore plugin/skills/self-check/run.ps1 from git."
+    if ($Layout.Mode -eq 'install') {
+        $hostFlag = switch (Get-KushiInstallHost $Layout.Repo) { 'clawpilot' { '--clawpilot' } 'vscode' { '--vscode' } default { '--all-hosts' } }
+        Add-Section 'self-check' 'red' 'run.ps1 not found in install' "Re-install: ``npx kushi-agents@latest $hostFlag --force``"
+    } else {
+        Add-Section 'self-check' 'red' 'run.ps1 not found' "Restore plugin/skills/self-check/run.ps1 from git."
+    }
 }
 
 # ── Section 3: canary evals ─────────────────────────────────────────────────
 Write-Banner "3. canary evals" "Cyan"
+if ($Layout.Mode -eq 'install') {
+    if (-not $Json) { Write-Host "  ℹ️  skipped in install mode (no eval baseline shipped)" -ForegroundColor Gray }
+    Add-Section 'canary-evals' 'green' 'skipped (install mode)' ''
+} else {
 Push-Location $Repo
 $canaryOut = & npm run --silent eval:canary 2>&1
 $canaryExit = $LASTEXITCODE
@@ -141,31 +195,66 @@ if ($canaryExit -eq 0) {
         Add-Section 'canary-evals' 'red' "FAIL exit=$canaryExit" 'npm run eval:canary   # investigate failing case'
     }
 }
+}
 
 # ── Section 4: skill-checker -All ───────────────────────────────────────────
 Write-Banner "4. skill-checker -All" "Cyan"
-$checkerPath = Join-Path $Repo 'plugin\skills\skill-checker\check-skill.ps1'
+$checkerPath = Join-Path $Layout.Plugin 'skills\skill-checker\check-skill.ps1'
 if (Test-Path $checkerPath) {
-    $ckOut = & pwsh -NoProfile -File $checkerPath -All -Root $Repo 2>&1
+    $ckOut = & pwsh -NoProfile -File $checkerPath -All -Root $Layout.Repo 2>&1
     $ckExit = $LASTEXITCODE
     if ($ckExit -eq 0) {
         if (-not $Json) { Write-Host "  ✅ all skills compliant" -ForegroundColor Green }
         Add-Section 'skill-checker' 'green' 'all skills pass blueprint' ''
     } else {
         if (-not $Json) { Write-Host "  ⚠️  blueprint violations (exit=$ckExit)" -ForegroundColor Yellow }
-        Add-Section 'skill-checker' 'yellow' "exit=$ckExit" 'pwsh plugin/skills/skill-checker/check-skill.ps1 -All   # review output'
+        Add-Section 'skill-checker' 'yellow' "exit=$ckExit" 'pwsh skills/skill-checker/check-skill.ps1 -All   # review output'
     }
 } else {
-    Add-Section 'skill-checker' 'red' 'check-skill.ps1 not found' "Restore plugin/skills/skill-checker/check-skill.ps1"
+    if ($Layout.Mode -eq 'install') {
+        if (-not $Json) { Write-Host "  ⚠️  skill-checker not installed in this profile (full only)" -ForegroundColor Yellow }
+        Add-Section 'skill-checker' 'yellow' 'not installed (full profile only)' "Re-install with full profile: ``npx kushi-agents@latest --all-hosts --profile full --force``"
+    } else {
+        Add-Section 'skill-checker' 'red' 'check-skill.ps1 not found' "Restore plugin/skills/skill-checker/check-skill.ps1"
+    }
 }
 
 # ── Section 5: Live-install drift ───────────────────────────────────────────
 Write-Banner "5. live-install drift" "Cyan"
+if ($Layout.Mode -eq 'install') {
+    # Install mode: compare installed version (from kushi-install.json) to npm latest.
+    $installPjPath = Join-Path $Layout.Repo 'kushi-install.json'
+    $installedVer = $null
+    if (Test-Path $installPjPath) {
+        try { $installedVer = (Get-Content -Raw $installPjPath | ConvertFrom-Json).version } catch {}
+    }
+    $npmOk = $false
+    try { $null = & npm --version 2>$null; if ($LASTEXITCODE -eq 0) { $npmOk = $true } } catch {}
+    if (-not $npmOk) {
+        if (-not $Json) { Write-Host "  ℹ️  npm not on PATH (skipped)" -ForegroundColor Gray }
+        Add-Section 'live-install' 'green' 'npm not on PATH (skipped)' ''
+    } elseif (-not $installedVer) {
+        if (-not $Json) { Write-Host "  ⚠️  no kushi-install.json version field" -ForegroundColor Yellow }
+        $hostFlag = switch (Get-KushiInstallHost $Layout.Repo) { 'clawpilot' { '--clawpilot' } 'vscode' { '--vscode' } default { '--all-hosts' } }
+        Add-Section 'live-install' 'yellow' 'install manifest missing version' "Re-install: ``npx kushi-agents@latest $hostFlag --force``"
+    } else {
+        $latest = $null
+        try { $latest = (& npm view kushi-agents version 2>$null).Trim() } catch {}
+        if ($latest -and $latest -ne $installedVer) {
+            if (-not $Json) { Write-Host "  ⚠️  installed=v$installedVer latest=v$latest" -ForegroundColor Yellow }
+            $hostFlag = switch (Get-KushiInstallHost $Layout.Repo) { 'clawpilot' { '--clawpilot' } 'vscode' { '--vscode' } default { '--all-hosts' } }
+            Add-Section 'live-install' 'yellow' "installed=v$installedVer latest=v$latest" "Re-install: ``npx kushi-agents@latest $hostFlag --force``"
+        } else {
+            if (-not $Json) { Write-Host "  ✅ install matches npm latest" -ForegroundColor Green }
+            Add-Section 'live-install' 'green' "installed=v$installedVer (matches npm latest)" ''
+        }
+    }
+} else {
 $liveSkill = Join-Path $userHome '.copilot\m-skills\kushi\SKILL.md'
-$agentFile = Join-Path $Repo 'plugin\agents\kushi.agent.md'
+$agentFile = Join-Path $Layout.Plugin 'agents\kushi.agent.md'
 $metaPath = Join-Path $userHome '.copilot\m-skills\skills-metadata.json'
 $repoVersion = $null
-try { $repoVersion = (Get-Content -Raw (Join-Path $Repo 'package.json') | ConvertFrom-Json).version } catch {}
+try { $repoVersion = (Get-Content -Raw (Join-Path $Layout.Repo 'package.json') | ConvertFrom-Json).version } catch {}
 $liveVersion = $null
 if (Test-Path $metaPath) {
     try {
@@ -204,6 +293,7 @@ if (-not (Test-Path $liveSkill)) {
         }
     }
 }
+}
 
 # ── Section 6: Global wiki shape ────────────────────────────────────────────
 Write-Banner "6. global wiki shape" "Cyan"

package/plugin/skills/migrate-per-user-files/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: "migrate-per-user-files"
+version: "1.0.0"
+description: "USE WHEN a project was bootstrapped under kushi ≤ v5.4.3 and the three root files (`bootstrap-status.md`, `FOLLOW-UPS.md`, `OPEN-QUESTIONS-DRAFT.md`) need to be relocated to per-user `Evidence/<alias>/` paths AND the user is ready to commit the move. DO NOT USE for routine refreshes (refresh-project already writes to new paths in v5.4.4+) or for shared root files (integrations.yml, kushi.yaml, .settings.yml) which stay at the project root."
+profile: "standard"
+verb: "migrate-files"
+---
+
+# migrate-per-user-files
+
+USE WHEN: A project repo was bootstrapped/refreshed under kushi ≤ v5.4.3 and the three previously-shared root files (`bootstrap-status.md`, `FOLLOW-UPS.md`, `OPEN-QUESTIONS-DRAFT.md`) exist at `<project>/`. v5.4.4 promotes those three files to per-user truth at `<project>/Evidence/<alias>/<file>`, with auto-consolidated rollups at `<project>/_Consolidated/<file>` emitted by `consolidate-evidence`. This skill performs the one-time relocation safely.
+
+DO NOT USE FOR: routine refreshes (`refresh-project` already writes to the new paths in v5.4.4+) or for the shared files that stay at the root (`integrations.yml`, `kushi.yaml`, `.settings.yml`).
+
+## Steps
+
+1. **Resolve alias** — `Get-KushiConfig -Name 'project-evidence'` returns the current user's alias. Refuse to run if no alias is configured.
+2. **Discover sources** — For each of the three basenames, check whether `<project>/<file>` exists at the root.
+3. **Check destination** — For each found source, check whether `<project>/Evidence/<alias>/<file>` already exists.
+   - **No destination** → planned action: `move` (root → per-user).
+   - **Destination exists with byte-identical content** → planned action: `delete-root-duplicate` (per-user is authoritative, root is stale copy).
+   - **Destination exists with different content** → planned action: `needs-merge`. **Defensive: never overwrite.** Emit a `[needs-merge]` row, exit 1 in `--apply` mode (in dry-run, still report and exit 0 so the user sees the full plan).
+4. **Print the plan** — One row per file: `<basename> | <action> | <reason>`. With `--apply`, also print the destination path that was written.
+5. **Execute or no-op**:
+   - Without `--apply`: dry-run only. Print plan, exit 0.
+   - With `--apply`: for each `move` or `delete-root-duplicate`, perform the filesystem operation. Re-running with `--apply` after a successful run is a no-op (nothing to migrate).
+6. **Log to run-log** — Append a `migrations:` entry to `Evidence/run-log.yml` with timestamp, alias, files moved, files needing merge.
+
+## Arguments
+
+- `-ProjectRoot <path>` (required) — Absolute path to the project folder.
+- `-Apply` (switch) — Perform the migration. Without this flag, the script is dry-run only.
+- `-StrictExit` (switch) — Exit 1 on any `needs-merge` row, even in dry-run mode.
+
+## Validation loop
+
+After `--apply`, the script self-verifies by re-listing the three root files. If any of them still exists (other than because of a `needs-merge` row), exit 2 with a `[verify]` error.
+
+## Idempotency contract
+
+Running with `--apply` on an already-migrated repo MUST be a no-op (exit 0, plan-table prints `nothing-to-do` for all three rows).
+
+## See also
+
+- `plugin/instructions/multi-user-shared-files.instructions.md` — the v5.4.4 doctrine.
+- `plugin/skills/consolidate-evidence/SKILL.md` Step 5 — the auto-rollup that consumes per-user files.
+- `references/migration-strategy.md` — why defensive, why content-hash compare, why dry-run by default.

package/plugin/skills/migrate-per-user-files/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill": "migrate-per-user-files",
+  "version": "1.0.0",
+  "description": "Migration script + SKILL.md ship together and document the three target basenames.",
+  "cases": [
+    {
+      "id": "skill-md-exists",
+      "name": "SKILL.md and migrate.ps1 are present",
+      "input": "verify migrate-per-user-files SKILL.md and migrate.ps1 exist",
+      "canary": true,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/migrate-per-user-files/SKILL.md" },
+        { "type": "file-exists", "path": "plugin/skills/migrate-per-user-files/migrate.ps1" }
+      ]
+    },
+    {
+      "id": "skill-documents-three-basenames",
+      "name": "SKILL.md documents all three target basenames",
+      "input": "verify SKILL.md mentions bootstrap-status.md, FOLLOW-UPS.md, and OPEN-QUESTIONS-DRAFT.md",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-contains", "path": "plugin/skills/migrate-per-user-files/SKILL.md", "needle": "bootstrap-status.md" },
+        { "type": "file-contains", "path": "plugin/skills/migrate-per-user-files/SKILL.md", "needle": "FOLLOW-UPS.md" },
+        { "type": "file-contains", "path": "plugin/skills/migrate-per-user-files/SKILL.md", "needle": "OPEN-QUESTIONS-DRAFT.md" }
+      ]
+    },
+    {
+      "id": "strategy-reference-ships",
+      "name": "references/migration-strategy.md documents the defensive contract",
+      "input": "verify migration-strategy.md exists and mentions content-hash",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/migrate-per-user-files/references/migration-strategy.md" },
+        { "type": "file-contains", "path": "plugin/skills/migrate-per-user-files/references/migration-strategy.md", "needle": "content-hash" }
+      ]
+    }
+  ]
+}

package/plugin/skills/migrate-per-user-files/migrate.ps1

@@ -0,0 +1,136 @@
+#requires -Version 7.0
+<#
+.SYNOPSIS
+  Migrate root-level bootstrap-status.md / FOLLOW-UPS.md / OPEN-QUESTIONS-DRAFT.md
+  to per-user Evidence/<alias>/ paths (kushi v5.4.4+ doctrine).
+
+.PARAMETER ProjectRoot
+  Absolute path to the project folder.
+
+.PARAMETER Apply
+  Perform the migration. Without this switch, the script is dry-run only.
+
+.PARAMETER StrictExit
+  Exit 1 on any needs-merge row, even in dry-run mode.
+#>
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory)] [string] $ProjectRoot,
+  [switch] $Apply,
+  [switch] $StrictExit
+)
+
+$ErrorActionPreference = 'Stop'
+$basenames = @('bootstrap-status.md','FOLLOW-UPS.md','OPEN-QUESTIONS-DRAFT.md')
+
+if (-not (Test-Path -LiteralPath $ProjectRoot -PathType Container)) {
+  Write-Error "[migrate-per-user-files] ProjectRoot not found: $ProjectRoot"
+  exit 2
+}
+
+# --- Resolve alias --------------------------------------------------------
+# Read directly from the project's user config — keeps this script standalone
+# and avoids dot-sourcing helpers that have mandatory parameters.
+$alias = $null
+$cfgPath = Join-Path $ProjectRoot '.kushi/config/user/project-evidence.yml'
+if (Test-Path -LiteralPath $cfgPath) {
+  $aliasLine = (Get-Content -LiteralPath $cfgPath) | Where-Object { $_ -match '^\s*alias\s*:\s*(\S+)' } | Select-Object -First 1
+  if ($aliasLine -and $aliasLine -match '^\s*alias\s*:\s*(\S+)') { $alias = $Matches[1].Trim('"').Trim("'") }
+}
+if (-not $alias) {
+  Write-Error "[migrate-per-user-files] No alias configured at $cfgPath. Run setup or set the project-evidence alias before migrating."
+  exit 2
+}
+
+$perUserDir = Join-Path $ProjectRoot "Evidence\$alias"
+$plan = @()
+$needsMergeCount = 0
+$actedCount = 0
+
+foreach ($name in $basenames) {
+  $src = Join-Path $ProjectRoot $name
+  $dst = Join-Path $perUserDir $name
+  $hasSrc = Test-Path -LiteralPath $src -PathType Leaf
+  $hasDst = Test-Path -LiteralPath $dst -PathType Leaf
+
+  if (-not $hasSrc -and -not $hasDst) {
+    $plan += [pscustomobject]@{ file=$name; action='nothing-to-do'; reason='neither root nor per-user copy present' }
+    continue
+  }
+  if (-not $hasSrc -and $hasDst) {
+    $plan += [pscustomobject]@{ file=$name; action='nothing-to-do'; reason='already migrated' }
+    continue
+  }
+  if ($hasSrc -and -not $hasDst) {
+    if ($Apply) {
+      if (-not (Test-Path -LiteralPath $perUserDir -PathType Container)) {
+        New-Item -ItemType Directory -Path $perUserDir -Force | Out-Null
+      }
+      Move-Item -LiteralPath $src -Destination $dst
+      $actedCount++
+      $plan += [pscustomobject]@{ file=$name; action='moved'; reason="-> Evidence/$alias/$name" }
+    } else {
+      $plan += [pscustomobject]@{ file=$name; action='move'; reason="would move root -> Evidence/$alias/$name" }
+    }
+    continue
+  }
+  # Both exist — compare content hashes.
+  $srcHash = (Get-FileHash -LiteralPath $src -Algorithm SHA256).Hash
+  $dstHash = (Get-FileHash -LiteralPath $dst -Algorithm SHA256).Hash
+  if ($srcHash -eq $dstHash) {
+    if ($Apply) {
+      Remove-Item -LiteralPath $src -Force
+      $actedCount++
+      $plan += [pscustomobject]@{ file=$name; action='deleted-root-duplicate'; reason='per-user copy is byte-identical' }
+    } else {
+      $plan += [pscustomobject]@{ file=$name; action='delete-root-duplicate'; reason='would delete byte-identical root copy' }
+    }
+  } else {
+    $needsMergeCount++
+    $plan += [pscustomobject]@{ file=$name; action='needs-merge'; reason='root and per-user copies differ — manual merge required, will not overwrite' }
+  }
+}
+
+Write-Host ""
+Write-Host "[migrate-per-user-files] alias = $alias" -ForegroundColor Cyan
+Write-Host "[migrate-per-user-files] project = $ProjectRoot" -ForegroundColor Cyan
+Write-Host "[migrate-per-user-files] mode = $(if ($Apply) {'APPLY'} else {'DRY-RUN'})" -ForegroundColor Cyan
+Write-Host ""
+$plan | Format-Table -AutoSize | Out-String | Write-Host
+
+# --- Run-log append (apply mode only) ------------------------------------
+if ($Apply -and $actedCount -gt 0) {
+  $evDir = Join-Path $ProjectRoot 'Evidence'
+  if (-not (Test-Path -LiteralPath $evDir -PathType Container)) {
+    New-Item -ItemType Directory -Path $evDir -Force | Out-Null
+  }
+  $log = Join-Path $evDir 'run-log.yml'
+  $ts  = (Get-Date).ToString('s') + 'Z'
+  $moved = ($plan | Where-Object { $_.action -in @('moved','deleted-root-duplicate') } | ForEach-Object { $_.file }) -join ', '
+  $merge = ($plan | Where-Object { $_.action -eq 'needs-merge' } | ForEach-Object { $_.file }) -join ', '
+  $entry = @(
+    "migrations:",
+    "  - timestamp: $ts",
+    "    alias: $alias",
+    "    skill: migrate-per-user-files",
+    "    files_migrated: [$moved]",
+    "    files_needs_merge: [$merge]"
+  ) -join "`r`n"
+  Add-Content -LiteralPath $log -Value $entry
+}
+
+# --- Verify (apply mode only) --------------------------------------------
+if ($Apply) {
+  foreach ($name in $basenames) {
+    $src = Join-Path $ProjectRoot $name
+    $stillThere = Test-Path -LiteralPath $src -PathType Leaf
+    $row = $plan | Where-Object { $_.file -eq $name } | Select-Object -First 1
+    if ($stillThere -and $row.action -notin @('needs-merge','nothing-to-do')) {
+      Write-Error "[verify] $name still present at root after migration"
+      exit 2
+    }
+  }
+}
+
+if ($needsMergeCount -gt 0 -and ($Apply -or $StrictExit)) { exit 1 }
+exit 0

package/plugin/skills/migrate-per-user-files/references/migration-strategy.md

@@ -0,0 +1,23 @@
+# Migration strategy — per-user file relocation
+
+## Why defensive (refuse to overwrite)
+
+The three migrated files are authored artifacts that may have hand edits, accumulated follow-ups, or carefully-curated open-question wording. A naive `Move-Item -Force` could silently destroy hours of work if a per-user copy already exists. We instead detect the collision and refuse — the user must decide which copy wins (or hand-merge them).
+
+## Why content-hash compare
+
+If both copies exist with byte-identical content, the per-user copy is authoritative (v5.4.4+) and the root copy is a stale duplicate left behind by some workflow. Deleting it is safe and quiet — no manual merge needed.
+
+If the content differs by even one byte, we cannot know which copy is newer, so we emit `[needs-merge]` and stop.
+
+## Why dry-run by default
+
+Mass filesystem operations should always print a plan first. The `--apply` flag is the explicit "yes, do it" gate. This matches the pattern used by `apply-ado-update` (preview profile) and the v5.4.3 lessons learned from the profile-allowlist catch-up.
+
+## Why one-time (not part of `refresh-project`)
+
+v5.4.4 `refresh-project` already writes to the new per-user paths. The migration is a one-time data move for repos initialized under ≤ v5.4.3. Folding it into refresh would mean checking-and-migrating on every refresh — wasteful and potentially destructive if the user has not yet decided how to handle a `needs-merge` situation.
+
+## Why log to run-log.yml
+
+Every project-touching kushi action logs to `Evidence/run-log.yml`. The migration is a project-touching action and follows the same convention so a future `doctor` or `project-status` run can see when the migration happened and which files were affected.

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

@@ -311,7 +311,7 @@ After successful pass:
 ## 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).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write Evidence/<alias>/FOLLOW-UPS.md per v5.4.4+ per-user files doctrine; consolidated at _Consolidated/FOLLOW-UPS.md).
 
 
 ## Issue Recovery

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

@@ -202,7 +202,7 @@ After successful pass:
 ## 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).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write Evidence/<alias>/FOLLOW-UPS.md per v5.4.4+ per-user files doctrine; consolidated at _Consolidated/FOLLOW-UPS.md).
 
 
 ## Issue Recovery

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

@@ -193,7 +193,7 @@ An entity that cannot meet the threshold is flagged `low_signal: true` in `_inde
 ## 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).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write Evidence/<alias>/FOLLOW-UPS.md per v5.4.4+ per-user files doctrine; consolidated at _Consolidated/FOLLOW-UPS.md).
 
 
 ## Issue Recovery

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

@@ -124,7 +124,7 @@ Per `loop-bootstrap-discovery.instructions.md`:
 | Pre-flight | Failure action |
 |---|---|
 | **A. Workspaces registered** for the resolved project | Refuse to run. Instruct user to run `@Kushi setup --reconfigure`. |
-| **B. Pages registered** OR `loop_pages_status: to-be-enumerated` | Run page enumeration via WorkIQ first; on enumerate-fail, write FOLLOW-UPS.md per the gate. |
+| **B. Pages registered** OR `loop_pages_status: to-be-enumerated` | Run page enumeration via WorkIQ first; on enumerate-fail, write Evidence/<alias>/FOLLOW-UPS.md per the gate (v5.4.4+; rollup at _Consolidated/FOLLOW-UPS.md). |
 | **C. Playwright profile exists** at `~/.kushi/playwright-profile/m365/` or `.../onenote/` | Refuse; instruct: `node plugin/skills/pull-onenote/runner.mjs --bootstrap`. |
 | **D. URLs are canonical** (matches Loop URL grammar; not synthesized) | Refuse + log to learnings/loop.md per `issue-recovery.instructions.md`. |
 

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

@@ -171,7 +171,7 @@ After the pass:
 ## 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).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write Evidence/<alias>/FOLLOW-UPS.md per v5.4.4+ per-user files doctrine; consolidated at _Consolidated/FOLLOW-UPS.md).
 
 
 ## Issue Recovery

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

@@ -98,7 +98,7 @@ For each project, the bootstrap step:
 1. **Locates `<project>/external-links.txt`.** If absent, write a starter template (same format as ABN AMRO has today) and mark `boundaries.misc.externalLinksPath` in `integrations.yml`.
 2. **Parses the file.** Skip comments, skip blank lines, skip placeholder URLs (`<PASTE_*_URL>`, `<TODO*>`).
 3. **Initializes `misc_links[]`** in `m365-mutable.json#knownSections.<projectKey>` with one entry per non-placeholder link, all `last_status: not-yet-attempted`.
-4. **Records** `boundaries.misc.linkCount` and `placeholderCount` to `bootstrap-status.md`.
+4. **Records** `boundaries.misc.linkCount` and `placeholderCount` to `Evidence/<alias>/bootstrap-status.md` (per-user, v5.4.4+; consolidated rollup at `_Consolidated/bootstrap-status.md`).
 
 ## Step A — enumerate (every refresh)
 
@@ -117,7 +117,7 @@ The runner branches per `type`:
 
 Skip fetch. Write registry entry with `captured_via: delegated`, `delegated_to: pull-loop`. The actual workspace/page capture happens in `pull-loop` (see `plugin/skills/pull-loop/SKILL.md`), which uses the canonical Loop boundary in `<project>/integrations.yml#boundaries.loop.workspace_ids[]` rather than free-text `external-links.txt` URLs.
 
-If the Loop URL pasted into `external-links.txt` references a workspace NOT registered in `boundaries.loop.workspace_ids[]`, `pull-misc` records `last_status: unregistered-loop-workspace` and notes the URL in `<project>/OPEN-QUESTIONS-DRAFT.md` so the user can decide whether to register it via `@Kushi setup --reconfigure`.
+If the Loop URL pasted into `external-links.txt` references a workspace NOT registered in `boundaries.loop.workspace_ids[]`, `pull-misc` records `last_status: unregistered-loop-workspace` and notes the URL in `<project>/Evidence/<alias>/OPEN-QUESTIONS-DRAFT.md` (per-user, v5.4.4+; consolidated rollup at `_Consolidated/OPEN-QUESTIONS-DRAFT.md`) so the user can decide whether to register it via `@Kushi setup --reconfigure`.
 
 ### B.2 `web` / `confluence` / `learn` / `docs` / `github` / unknown — HTTP
 
@@ -263,7 +263,7 @@ Example: `[source: misc/loop/ABN-Core-Team-Sync-2026-03-27 · 2026-05-14]`
 ## 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).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write Evidence/<alias>/FOLLOW-UPS.md per v5.4.4+ per-user files doctrine; consolidated at _Consolidated/FOLLOW-UPS.md).
 
 
 ## Issue Recovery

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

@@ -171,7 +171,7 @@ Every refresh writes `Evidence/<alias>/refresh-reports/<YYYY-MM-DD>-<HHMM>-oneno
 ## 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).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write Evidence/<alias>/FOLLOW-UPS.md per v5.4.4+ per-user files doctrine; consolidated at _Consolidated/FOLLOW-UPS.md).
 
 
 ## Issue Recovery

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

@@ -183,7 +183,7 @@ An entity that cannot meet the threshold is flagged `low_signal: true` in `_inde
 ## 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).
+- After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write Evidence/<alias>/FOLLOW-UPS.md per v5.4.4+ per-user files doctrine; consolidated at _Consolidated/FOLLOW-UPS.md).
 
 
 ## Issue Recovery