@caddis/cli 0.4.23 → 0.4.24

package/bundles/antigravity-plugin-extras/skills/adopt-app/scripts/Get-AppInventory.ps1

@@ -0,0 +1,236 @@
+<#
+.SYNOPSIS
+    Phase 1. Read an existing app and write inventory.json. Changes nothing, runs nothing.
+
+.DESCRIPTION
+    An app that never went through a project generator is usually the only copy of
+    something that is already running. This script only READS: file metadata, the text of
+    small manifests and config files, git state, and what the host has registered to run
+    the folder. It never executes an entry point, an installer or a build.
+
+    It also refuses to let a partial answer look like a clean one. Walking a folder over a
+    network share can hit a file budget or an access denial. When that happens the script
+    reports the size as a MINIMUM, marks the scan partial and exits 1 unless you pass
+    -AllowPartial. A truncated scan that exits 0 is how a 140 GB data tree gets called
+    "about 200 MB" and committed.
+
+    File CONTENTS never reach inventory.json. A config file holds credentials and an
+    artefact gets copied into tickets and chats, so only the path, the line and the key
+    NAME are recorded.
+
+.PARAMETER Path
+    The app folder. A local path, a UNC share, or a path on the remote box when you pass
+    -ComputerName.
+
+.PARAMETER ComputerName
+    Scan on this box over WinRM. Use it when the app lives on a server: a UNC scan works
+    but is slow, and the host facts (services, scheduled tasks, web sites) can only be
+    read on the box itself.
+
+.EXAMPLE
+    ./Get-AppInventory.ps1 -Path E:\legacy-app
+.EXAMPLE
+    ./Get-AppInventory.ps1 -Path G:\apps\batch-engine -ComputerName appserver01 -FileBudget 5000
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Path,
+    [string]$Name,
+    [string]$ComputerName,
+    [string]$OutDir,
+    [int]$FileBudget = 0,
+    [int]$ProbeBudget = 4000,
+    # Top-level folders to leave unscanned by name. Use it for a tree you already know is
+    # bulk data, so the budget is spent on the folders whose contents are still a question.
+    # They are recorded as not-scanned, never as empty.
+    [string[]]$SkipFolder = @(),
+    [switch]$AllowPartial,
+    [switch]$SkipHostFacts
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'AdoptCommon.ps1')
+
+if (-not $Name) { $Name = (Split-Path $Path -Leaf) -replace '[^A-Za-z0-9._-]', '-' }
+$dir = Resolve-AdoptOutDir -Name $Name -OutDir $OutDir
+
+# The project config supplies the defaults; a parameter always wins. Reading it here is what
+# makes those keys real - a config value nothing consults is a promise the code does not keep.
+$cfg = Get-AdoptConfig
+if ($FileBudget -le 0) { $FileBudget = [int]$cfg.fileBudget }
+if ($SkipFolder.Count -eq 0) { $SkipFolder = @($cfg.skipFolders) }
+
+Write-AdoptHeading "Inventory: $Name"
+Write-Host "  source      : $Path$(if ($ComputerName) { "  (on $ComputerName)" })"
+Write-Host "  file budget : $FileBudget per top-level folder"
+Write-Host "  nothing in the source is written, and nothing in it is executed."
+
+$scan = Invoke-AdoptScan -Path $Path -ComputerName $ComputerName -FileBudget $FileBudget `
+    -ProbeBudget $ProbeBudget -SkipFolders $SkipFolder -SkipPattern $cfg.skipPattern
+
+if (-not $scan.exists) {
+    Write-Error "Source not found: $Path$(if ($ComputerName) { " on $ComputerName" }). $($scan.partialReason -join '; ')"
+    exit 1
+}
+
+$hostFacts = $null
+if (-not $SkipHostFacts) {
+    try { $hostFacts = Get-AdoptRunRegistrations -Path $Path -ComputerName $ComputerName }
+    catch { Write-Warning "Could not read host registrations: $($_.Exception.Message)" }
+}
+
+$kind = 'local'
+if ($ComputerName) { $kind = 'winrm' }
+elseif ($Path -match '^\\\\') { $kind = 'unc' }
+
+$inventory = [ordered]@{
+    name         = $Name
+    scannedAt    = (Get-Date).ToUniversalTime().ToString('o')
+    scannedBy    = 'adopt-app/Get-AppInventory.ps1'
+    source       = [ordered]@{ kind = $kind; path = $Path; computerName = $ComputerName }
+    partial      = [bool]$scan.partial
+    partialReason = @($scan.partialReason)
+    size         = [ordered]@{
+        totalMB       = $scan.totalMB
+        totalMBIsMinimum = [bool]$scan.partial
+        totalFiles    = $scan.totalFiles
+        folders       = @($scan.folders | Sort-Object { -1 * $_.mb })
+    }
+    git          = $scan.git
+    # A shallow index of ordinary paths, used only by profile detection in phase 2.
+    paths        = @($scan.paths)
+    manifests    = @($scan.manifests)
+    entryPoints  = @($scan.entryPoints)
+    configFiles  = @($scan.configFiles)
+    secretsSuspected = @($scan.secretFiles)
+    certificates = @($scan.certificates)
+    excludable   = @($scan.excludable)
+    reparsePoints = @($scan.reparse)
+    tests        = [ordered]@{ files = $scan.testFiles; markers = @($scan.testMarkers) }
+    ci           = @($scan.ciFiles)
+    docs         = @($scan.docFiles)
+    healthSignals = @($scan.healthHits)
+    runRegistrations = $hostFacts
+}
+
+# Roll the excludable file list up per top folder. A list of 40,000 paths is unreadable and
+# the decision is taken per folder anyway.
+$byFolder = @{}
+foreach ($e in @($scan.excludable)) {
+    $top = ($e.path -split '[\\/]')[0]
+    $key = "$top|$($e.category)"
+    if (-not $byFolder.ContainsKey($key)) { $byFolder[$key] = @{ folder = $top; category = $e.category; files = 0; bytes = [long]0 } }
+    $byFolder[$key].files++
+    $byFolder[$key].bytes += [long]$e.bytes
+}
+$inventory.excludableSummary = @($byFolder.Values |
+        ForEach-Object { [ordered]@{ folder = $_.folder; category = $_.category; files = $_.files; mb = [math]::Round($_.bytes / 1MB, 2) } } |
+        Sort-Object { -1 * $_.mb })
+
+$out = Write-AdoptArtifact -Dir $dir -FileName 'inventory.json' -Object $inventory
+
+# ---- report ---------------------------------------------------------------------------
+Write-AdoptHeading 'Size'
+if ($inventory.size.totalMBIsMinimum) { Write-Host "  total AT LEAST $($inventory.size.totalMB) MB in $($inventory.size.totalFiles)+ files - the scan did not finish" -ForegroundColor Yellow }
+else { Write-Host "  total $($inventory.size.totalMB) MB in $($inventory.size.totalFiles) files" }
+foreach ($f in @($inventory.size.folders | Select-Object -First 12)) {
+    $flag = ''
+    if ($f.skipped) { $flag = '  [NOT SCANNED - you passed -SkipFolder]' }
+    elseif ($f.truncated) { $flag = '  [truncated - at least this size]' }
+    elseif ($f.denied) { $flag = '  [access denied somewhere inside - at least this size]' }
+    Write-Host ("    {0,10:N1} MB  {1,8} files  {2,-12} {3}{4}" -f $f.mb, $f.files, $f.git, $f.path, $flag)
+}
+
+Write-AdoptHeading 'Git'
+if ($inventory.git.isRepo -and -not (Get-AdoptProp $inventory.git 'gitAvailable' $false)) {
+    Write-Host "  repo     : there is a .git folder, but GIT IS NOT AVAILABLE where the scan ran." -ForegroundColor Red
+    Write-Host "             Branches, remotes and which folders are tracked are UNKNOWN, not clean." -ForegroundColor Red
+    Write-Host "             Install git on that box, or scan a local copy, before trusting anything below." -ForegroundColor Red
+}
+elseif ($inventory.git.isRepo) {
+    $remotes = @($inventory.git.remotes | ForEach-Object { "$($_.name) -> $($_.url)" })
+    Write-Host "  repo     : yes, $($inventory.git.commits) commits on $($inventory.git.branch)"
+    Write-Host "  remotes  : $(if ($remotes.Count) { $remotes -join '; ' } else { 'NONE - this folder is the only copy' })"
+    Write-Host "  refs     : $($inventory.git.localBranches) local branches, $($inventory.git.remoteBranches) remote-tracking, $($inventory.git.tags) tags"
+    Write-Host "  dirty    : $($inventory.git.dirtyFiles) files"
+    if ($null -ne $inventory.git.unpushed -and $inventory.git.unpushed -gt 0) {
+        Write-Host "  UNPUSHED : $($inventory.git.unpushed) commits ahead of $($inventory.git.upstream)" -ForegroundColor Yellow
+    }
+}
+else { Write-Host "  repo     : NO - there is no history to port; adoption starts with one import commit" -ForegroundColor Yellow }
+
+# Neither committed nor ignored. This is the state that turns one careless `git add -A`
+# into gigabytes of runtime data in the history for ever, and no filename pattern finds
+# it - only git can tell an undeclared data tree from a source folder.
+$untracked = @($inventory.size.folders | Where-Object { $_.git -eq 'untracked' -and $_.mb -ge 1 -and $_.path -ne '.git' })
+if ($untracked.Count -gt 0) {
+    Write-AdoptHeading 'Neither committed nor ignored'
+    Write-Host "  These folders are not in the repository AND not in .gitignore. One 'git add -A'" -ForegroundColor Yellow
+    Write-Host "  commits them permanently. Decide each one: commit it, ignore it, or move it out." -ForegroundColor Yellow
+    foreach ($u in $untracked) { Write-Host ("    {0,10:N1} MB  {1,8} files  {2}" -f $u.mb, $u.files, $u.path) -ForegroundColor Yellow }
+}
+
+$ignoredBig = @($inventory.size.folders | Where-Object { $_.git -eq 'ignored' -and $_.mb -ge 200 })
+if ($ignoredBig.Count -gt 0) {
+    Write-AdoptHeading 'Correctly ignored, but the app needs them'
+    Write-Host "  Excluding these is right. It is only SAFE once something says how to get them back." -ForegroundColor DarkYellow
+    foreach ($i in $ignoredBig) { Write-Host ("    {0,10:N1} MB  {1}" -f $i.mb, $i.path) }
+}
+
+Write-AdoptHeading 'What the repository must not carry'
+if ($inventory.excludableSummary.Count -eq 0) { Write-Host "  nothing found" }
+foreach ($e in @($inventory.excludableSummary | Select-Object -First 15)) {
+    Write-Host ("    {0,10:N1} MB  {1,7} files  {2,-13} {3}" -f $e.mb, $e.files, $e.category, $e.folder)
+}
+
+Write-AdoptHeading 'Possible credentials'
+if ($inventory.secretsSuspected.Count -eq 0) { Write-Host "  none found by the heuristics - which is not the same as none present" }
+foreach ($s in @($inventory.secretsSuspected | Select-Object -First 25)) {
+    # Two traps in one line. A hashtable's PSObject.Properties are Keys/Values/Count and
+    # never its entries, so testing them showed a line number for nothing. And under
+    # StrictMode, reading a key that is absent THROWS - a name-only record has no 'line',
+    # so the whole inventory died after printing most of its report.
+    $where = $s.path
+    $hasLine = if ($s -is [hashtable]) { $s.ContainsKey('line') } else { @($s.PSObject.Properties.Name) -contains 'line' }
+    if ($hasLine -and $s.line) { $where = "$($s.path):$($s.line)  key '$($s.key)'" }
+    Write-Host "    $where   ($($s.why))" -ForegroundColor Yellow
+}
+if ($inventory.certificates.Count -gt 0) {
+    Write-Host "  $($inventory.certificates.Count) key container(s) hold a PUBLIC certificate, not a key - not a finding:" -ForegroundColor DarkGray
+    foreach ($c in @($inventory.certificates | Select-Object -First 8)) { Write-Host "    $c" -ForegroundColor DarkGray }
+}
+
+if ($inventory.reparsePoints.Count -gt 0) {
+    Write-AdoptHeading 'Junctions and symlinks'
+    Write-Host "  These were NOT followed. A junction inside a tree that git manages is a data-loss" -ForegroundColor Yellow
+    Write-Host "  hazard: git's recursive remove follows it and deletes the TARGET's contents." -ForegroundColor Yellow
+    foreach ($r in @($inventory.reparsePoints | Select-Object -First 15)) { Write-Host "    $($r.path)" }
+}
+
+if ($hostFacts) {
+    Write-AdoptHeading 'What runs it'
+    $any = $false
+    foreach ($s in @($hostFacts.services)) { $any = $true; Write-Host "    service        $($s.name)  [$($s.state)/$($s.startMode)] as $($s.account)" }
+    foreach ($t in @($hostFacts.scheduledTasks)) { $any = $true; Write-Host "    scheduled task $($t.path)$($t.name)  [$($t.state)] as $($t.account); last run $($t.lastRun)" }
+    foreach ($w in @($hostFacts.webSites)) { $any = $true; Write-Host "    web site       $($w.name)  -> $($w.physicalPath)" }
+    if (-not $any) {
+        Write-Host "    nothing on $(if ($ComputerName) { $ComputerName } else { 'this machine' }) references this folder." -ForegroundColor Yellow
+        Write-Host "    If the app IS running, it runs somewhere else. Find out where before you adopt it." -ForegroundColor Yellow
+    }
+    foreach ($e in @($hostFacts.errors)) { Write-Host "    (could not check $e)" -ForegroundColor DarkYellow }
+}
+
+Write-Host ""
+Write-Host "  wrote $out"
+
+if ($inventory.partial) {
+    Write-Host ""
+    Write-Host "SCAN INCOMPLETE. Sizes above are MINIMUMS:" -ForegroundColor Red
+    foreach ($r in @($inventory.partialReason)) { Write-Host "  - $r" -ForegroundColor Red }
+    Write-Host "Raise -FileBudget, or accept it with -AllowPartial once you know what is in those folders." -ForegroundColor Red
+    if (-not $AllowPartial) { exit 1 }
+    Write-Host "Accepted with -AllowPartial; inventory.json records partial=true." -ForegroundColor Yellow
+}
+
+exit 0

package/bundles/antigravity-plugin-extras/skills/adopt-app/scripts/New-AdoptionPlan.ps1

@@ -0,0 +1,311 @@
+<#
+.SYNOPSIS
+    Phase 4. Turn the inventory, the profile and the conformance report into an ORDERED
+    plan a person can work through. Writes adoption-plan.md and adoption.json.
+
+.DESCRIPTION
+    The order is the product. Every step in an adoption has a prerequisite, and doing them
+    in the wrong order costs real work:
+
+      - Create the repository BEFORE settling what must not be in it, and removing it
+        later means rewriting history that other people have already cloned.
+      - Rotate a credential AFTER publishing, and it was public in between.
+      - Wire up CI before anyone has said which branch is the truth, and CI builds the
+        wrong branch.
+
+    So the plan is emitted in dependency order, each step carrying the evidence that put
+    it there and the check that says it is done. Steps that cannot start are listed as
+    BLOCKED with the reason, rather than left out - a plan that silently omits what it
+    cannot do reads like a shorter job.
+
+    This script writes a document. It changes nothing else, and it deliberately does not
+    execute any step.
+
+.EXAMPLE
+    ./New-AdoptionPlan.ps1 -Name legacy-app
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Name,
+    [string]$OutDir,
+    # The fleet- or team-specific skill that performs the adoption once this plan is
+    # agreed. Named in the handover section so the plan does not end in mid-air.
+    [string]$HandoverSkill = ''
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'AdoptCommon.ps1')
+
+$dir = Resolve-AdoptOutDir -Name $Name -OutDir $OutDir
+$inv = Read-AdoptArtifact -Dir $dir -FileName 'inventory.json'
+$prof = Read-AdoptArtifact -Dir $dir -FileName 'profile.json'
+$conf = Read-AdoptArtifact -Dir $dir -FileName 'conformance.json'
+
+function Get-ConformanceItem { param([string]$Id) return @($conf.items | Where-Object { $_.id -eq $Id })[0] }
+function Test-ItemPasses { param([string]$Id) $i = Get-ConformanceItem $Id; return ($null -ne $i) -and ($i.verdict -in @('PASS', 'ANSWERED')) }
+
+$steps = @()
+function Add-Step {
+    param(
+        [string]$Id, [string]$Title, [string[]]$Needs = @(), [string]$Why = '',
+        [string[]]$Do = @(), [string]$Done = '', [string]$State = 'TODO'
+    )
+    $script:steps += [ordered]@{ id = $Id; title = $Title; needs = $Needs; why = $Why; actions = $Do; doneWhen = $Done; state = $State }
+}
+
+# ---------------------------------------------------------------------------------------
+# 1. Answer what only a person can answer.
+$openQuestions = @($conf.items | Where-Object { $_.verdict -eq 'ASK' })
+if ($openQuestions.Count -gt 0) {
+    Add-Step 'answers' 'Get the owner''s answers' @() `
+        'Every later step depends on at least one of these. They are not observable from files, so no amount of scanning will settle them.' `
+        (@($openQuestions | ForEach-Object { "[$($_.id)] $($_.question)" }) + @("Record each: Test-AppConformance.ps1 -Name $Name -Answer <id>=`"...`"")) `
+        'Test-AppConformance.ps1 reports no open ASK on a blocking item.' `
+        $(if (@($conf.blockingQuestions).Count -gt 0) { 'TODO' } else { 'TODO-NONBLOCKING' })
+}
+
+# 2. Decide the content policy, BEFORE any repository exists.
+$so = Get-ConformanceItem 'source-only'
+if ($so -and $so.verdict -eq 'GAP') {
+    $lines = @()
+    foreach ($f in @($inv.size.folders | Where-Object { $_.git -eq 'untracked' -and $_.path -ne '.git' -and $_.mb -ge 1 })) {
+        $lines += "$($f.path) - $($f.mb) MB, neither committed nor ignored: commit it, ignore it, or move it out of the tree"
+    }
+    foreach ($e in @($inv.excludableSummary | Select-Object -First 10)) {
+        $g = @($inv.size.folders | Where-Object { $_.path -eq $e.folder })
+        if ($g.Count -gt 0 -and $g[0].git -eq 'tracked') {
+            $lines += "$($e.folder) - $($e.mb) MB of $($e.category) is COMMITTED: needs a history rewrite, not a .gitignore line"
+        }
+    }
+    Add-Step 'content-policy' 'Settle what the repository may hold' @('answers') `
+        'A .gitignore added later does not remove what is already committed, and a folder that is neither committed nor ignored is one careless command away from being permanent.' `
+        $lines `
+        'Every folder over the size threshold is classified: source, ignored-and-provisioned, or moved out.'
+}
+
+# 3. Credentials.
+$sec = Get-ConformanceItem 'no-secrets'
+if ($sec -and $sec.verdict -eq 'GAP') {
+    Add-Step 'secrets' 'Read every flagged file, then rotate what was real' @('content-policy') `
+        'Publishing is irreversible. A credential that reaches a hosted repository must be treated as disclosed, whether or not anyone fetched it.' `
+        (@(@($inv.secretsSuspected | Select-Object -First 15 | ForEach-Object {
+            $ln = Get-AdoptProp $_ 'line'
+            if ($ln) { "$($_.path):$ln - key '$(Get-AdoptProp $_ 'key')'" } else { "$($_.path) - $($_.why)" }
+        })) + @('For each: is it real? If yes, ROTATE it and remove it from the tree AND from history.')) `
+        'No real credential remains in the tree, and every one that was there has been rotated.'
+}
+
+# 4. The repository.
+if (-not (Test-ItemPasses 'git-repo')) {
+    Add-Step 'import' 'Import the folder as a repository' @('content-policy', 'secrets') `
+        'There is no history to preserve, so the first commit is a decision about content, not about history.' `
+        @('Write .gitignore FIRST, from the content policy above.', 'Stage files BY NAME. Never `git add -A` in a folder this size.', 'One import commit, then push.') `
+        'The remote holds the source and nothing the content policy excluded.'
+}
+elseif (-not (Test-ItemPasses 'remote-on-team-host')) {
+    $rem = Get-ConformanceItem 'remote-on-team-host'
+    Add-Step 'port' 'Move the repository to the team''s host' @('content-policy', 'secrets', 'answers') `
+        "Today: $($rem.evidence)" `
+        @('Use the port-to-github skill: it stages the source read-only, verifies every branch and tag by SHA, and never pushes back to the source.',
+          'Push every ref that exists only on the old host BEFORE converting or deleting it.',
+          'Keep the old remote as a second remote until the first deploy from the new one is green.') `
+        'Every branch and tag matches by SHA on the new host, and the old one is read-only or archived.'
+}
+
+# 5. The rest, in the order they unblock each other.
+if (-not (Test-ItemPasses 'deps-pinned')) {
+    Add-Step 'pin-deps' 'Pin the dependencies' @('import', 'port') `
+        'Without a lock file a failed build cannot be told from a dependency that moved underneath it.' `
+        @('Commit the lock file the ecosystem produces.', 'Record the exact runtime version the app is built and run with.') `
+        'A clean checkout on another machine installs the same versions.'
+}
+
+$rm = Get-ConformanceItem 'runtime-manifest'
+if ($rm -and $rm.verdict -ne 'PASS') {
+    Add-Step 'provision' 'Write down how to rebuild the environment' @('content-policy') `
+        "Excluding a runtime from the repository is only safe once something says how to get it back. $($rm.evidence)" `
+        @('For each excluded folder: name the component, the EXACT version, and where it is installed from.',
+          'Write a provisioning script that FAILS for anything it cannot provision, rather than skipping it.',
+          'Copy configuration out of the runtime folders as templates - configuration is app content even when the runtime around it is not.') `
+        'A new machine can be brought to a working state from the repository plus the provisioning script.'
+}
+
+if (-not (Test-ItemPasses 'tests')) {
+    Add-Step 'tests' 'Get a test suite that CI can run' @('pin-deps') `
+        'CI that runs no tests only proves the code compiles.' `
+        @('Start with the paths that would break silently: the ones with no health signal and no rollback.') `
+        'One command runs the suite and returns a non-zero exit code when it fails.'
+}
+
+if (-not (Test-ItemPasses 'ci-build')) {
+    Add-Step 'ci' 'Add CI that builds and tests every push' @('import', 'port', 'pin-deps') `
+        'Until CI exists, "it works" means "it worked on one machine".' `
+        @('Build and test on push and on pull request.',
+          'Classify every credential in the workflow: it faces ORIGIN, or it names a DEPENDENCY host. There is no third kind.',
+          'Never write double-curly-brace text anywhere in a workflow file, including inside comments in a run block.') `
+        'A pull request cannot merge while the build or the tests fail.'
+}
+
+$health = Get-ConformanceItem 'health'
+if ($health -and $health.verdict -ne 'PASS') {
+    Add-Step 'health' 'Add a health signal that can fail' @('ci') `
+        'A check that cannot fail manufactures confidence. The commonest version returns 200 from a catch-all route while the app is broken.' `
+        @('For a service: an endpoint that reports its dependencies and fails when one is down.',
+          'For a batch job: a non-zero exit code AND an output artefact whose absence is detectable.',
+          'Prove it fails: break the dependency on purpose and watch the check go red.') `
+        'The check has been observed FAILING, not only passing.'
+}
+
+if (-not (Test-ItemPasses 'ci-deploy')) {
+    Add-Step 'deploy' 'Make the deployment reproducible' @('ci', 'health', 'provision') `
+        'A manual deploy is a procedure that exists only in somebody''s memory.' `
+        @('Build the artefact BEFORE stopping anything. Only a build that produced one earns the right to interrupt the service.',
+          'Roll the code and the built artefact back together - restoring one without the other leaves a mixed state that passes every check.',
+          'Verify by the artefact CHANGING - a bundle hash, a file time - never by an HTTP 200 or a version endpoint. Both pass in the mixed state.') `
+        'A deploy can be run by someone who has never done it, from the written steps alone.'
+}
+
+$rb = Get-ConformanceItem 'rollback'
+if ($rb -and $rb.verdict -ne 'PASS') {
+    Add-Step 'rollback' 'Write and TEST the way back' @('deploy') `
+        'A rollback nobody has run is a plan, not a capability.' `
+        @('Write the exact command.', 'Run it once, deliberately, on a real release.', 'Note what it cannot undo - a database migration usually cannot.') `
+        'The rollback has been executed at least once and the result was verified.'
+}
+
+$run = Get-ConformanceItem 'run-declared'
+if ($run -and $run.verdict -ne 'PASS') {
+    Add-Step 'run-declared' 'Declare how it runs, in the repository' @('deploy') `
+        "How this app starts is not currently recorded anywhere version-controlled. $($run.evidence)" `
+        @('Commit the service definition or the schedule.', 'Record the account it runs as and why that account.', 'Record the trigger: a port, a timer, a queue, a person.') `
+        'Recreating the runtime registration needs no undocumented knowledge.'
+}
+
+foreach ($small in @(
+        @{ id = 'docs'; item = 'docs-readme'; title = 'Write the README'; why = 'The first question a new person asks is what this is and how to run it.'; done = 'A new person can run it locally from the README alone.' },
+        @{ id = 'agent-rules'; item = 'agent-rules'; title = 'Add the agent rules file'; why = 'Without it every coding agent re-derives the project rules, and each derives them differently.'; done = 'The file exists and states the rules that are not obvious from the code.' },
+        @{ id = 'junctions'; item = 'no-junctions'; title = 'Remove the junctions from the tree'; why = 'git''s recursive remove follows a junction and deletes the TARGET''s contents. This is data loss, not an inconvenience.'; done = 'No reparse point remains inside the tree git manages; shared state is reached by absolute path.' }
+    )) {
+    if (-not (Test-ItemPasses $small.item)) {
+        Add-Step $small.id $small.title @('import', 'port') $small.why @() $small.done
+    }
+}
+
+# ---- mark blocked steps --------------------------------------------------------------
+$presentIds = @($steps | ForEach-Object { $_.id })
+foreach ($s in $steps) {
+    $blockers = @($s.needs | Where-Object { $presentIds -contains $_ })
+    if ($blockers.Count -gt 0 -and $s.id -ne 'answers') { $s.state = 'BLOCKED' }
+    $s.needs = $blockers
+}
+
+# ---- write ----------------------------------------------------------------------------
+$json = [ordered]@{
+    name = $Name; plannedAt = (Get-Date).ToUniversalTime().ToString('o')
+    source = $inv.source; components = @($prof.components)
+    blockingGaps = @($conf.blockingGaps); blockingQuestions = @($conf.blockingQuestions)
+    steps = $steps
+}
+$jsonPath = Write-AdoptArtifact -Dir $dir -FileName 'adoption.json' -Object $json
+
+$md = New-Object System.Text.StringBuilder
+[void]$md.AppendLine("# Adopting $Name")
+[void]$md.AppendLine()
+[void]$md.AppendLine("Generated $((Get-Date).ToUniversalTime().ToString('u')) by the adopt-app skill, from a read-only scan. Nothing in the app was executed.")
+[void]$md.AppendLine()
+[void]$md.AppendLine('## What this app is')
+[void]$md.AppendLine()
+# A markdown code span is delimited by a backtick, which is also PowerShell's escape
+# character, so the delimiter is built as a variable rather than typed inside the string.
+$tick = [char]0x60
+$sourceHost = ''
+if ($inv.source.computerName) { $sourceHost = " on $($inv.source.computerName)" }
+[void]$md.AppendLine("- **Source**: $tick$($inv.source.path)$tick$sourceHost ($($inv.source.kind))")
+$sizeWord = if ($inv.size.totalMBIsMinimum) { 'at least ' } else { '' }
+[void]$md.AppendLine("- **Size**: $sizeWord$($inv.size.totalMB) MB in $($inv.size.totalFiles) files")
+if ($inv.git.isRepo) {
+    $remoteText = if (@($inv.git.remotes).Count -gt 0) { (@($inv.git.remotes | ForEach-Object { $_.url }) -join ', ') } else { '**none - this folder is the only copy**' }
+    [void]$md.AppendLine("- **Git**: $($inv.git.commits) commits, $($inv.git.localBranches) local branches, $($inv.git.tags) tags; remote: $remoteText")
+}
+else { [void]$md.AppendLine('- **Git**: not a repository') }
+[void]$md.AppendLine("- **Components**:")
+foreach ($c in @($prof.components)) {
+    $also = if (@($c.alsoMatches).Count -gt 0) { " (also matches $((@($c.alsoMatches)) -join ', ') - confirm which it is)" } else { '' }
+    [void]$md.AppendLine("  - $tick$($c.path)$tick -> **$($c.profile)** [$($c.status)]$also")
+}
+if ($inv.partial) {
+    [void]$md.AppendLine()
+    [void]$md.AppendLine('> **The scan was partial.** Every "nothing found" below means "nothing found so far":')
+    foreach ($r in @($inv.partialReason)) { [void]$md.AppendLine("> - $r") }
+}
+[void]$md.AppendLine()
+
+[void]$md.AppendLine('## Where it stands')
+[void]$md.AppendLine()
+[void]$md.AppendLine('| | Item | Verdict | Evidence |')
+[void]$md.AppendLine('|---|---|---|---|')
+foreach ($it in @($conf.items)) {
+    $b = if ($it.blocking) { '**!**' } else { '' }
+    $ev = "$($it.evidence)" -replace '\|', '\|'
+    [void]$md.AppendLine("| $b | $($it.title) | $($it.verdict) | $ev |")
+}
+[void]$md.AppendLine()
+[void]$md.AppendLine('`!` marks a blocking item. `ASK` means it cannot be read from the files; a person must answer it.')
+[void]$md.AppendLine()
+
+if ($openQuestions.Count -gt 0) {
+    [void]$md.AppendLine('## Questions for the owner')
+    [void]$md.AppendLine()
+    [void]$md.AppendLine('Ask these before starting. Each one changes what the later steps are.')
+    [void]$md.AppendLine()
+    foreach ($q in $openQuestions) {
+        $star = if ($q.blocking) { ' **(blocking)**' } else { '' }
+        [void]$md.AppendLine("1. **$($q.id)**$star - $($q.question)")
+    }
+    [void]$md.AppendLine()
+}
+
+[void]$md.AppendLine('## The plan, in order')
+[void]$md.AppendLine()
+if ($steps.Count -eq 0) {
+    [void]$md.AppendLine('Nothing to do: every item passes.')
+}
+$n = 0
+foreach ($s in $steps) {
+    $n++
+    $needs = if (@($s.needs).Count -gt 0) { " - needs: $((@($s.needs)) -join ', ')" } else { '' }
+    [void]$md.AppendLine("### $n. $($s.title)$needs")
+    [void]$md.AppendLine()
+    if ($s.why) { [void]$md.AppendLine("$($s.why)"); [void]$md.AppendLine() }
+    foreach ($a in @($s.actions)) { [void]$md.AppendLine("- $a") }
+    if (@($s.actions).Count -gt 0) { [void]$md.AppendLine() }
+    [void]$md.AppendLine("**Done when:** $($s.doneWhen)")
+    [void]$md.AppendLine()
+}
+
+[void]$md.AppendLine('## Handover')
+[void]$md.AppendLine()
+if ($HandoverSkill) {
+    [void]$md.AppendLine("Once every blocking item is satisfied, the $tick$HandoverSkill$tick skill performs the adoption: it knows this team's hosts, ports, routing and CI. This plan is its input.")
+}
+else {
+    [void]$md.AppendLine('This plan says WHAT must be true, not HOW your platform does it. The team-specific skill that owns hosts, ports, routing and CI performs the steps; give it this file.')
+}
+[void]$md.AppendLine()
+[void]$md.AppendLine('Re-run Test-AppConformance.ps1 after each step. It is the same gate either way, so the plan cannot quietly drift from the standard.')
+
+$mdPath = Join-Path $dir 'adoption-plan.md'
+$md.ToString() | Set-Content -LiteralPath $mdPath -Encoding UTF8
+
+Write-AdoptHeading "Adoption plan: $Name"
+Write-Host "  $($steps.Count) steps, $(@($steps | Where-Object { $_.state -eq 'BLOCKED' }).Count) of them blocked by an earlier one"
+Write-Host "  $($openQuestions.Count) open question(s), $(@($conf.blockingQuestions).Count) of them blocking"
+foreach ($s in $steps) {
+    $mark = if ($s.state -eq 'BLOCKED') { 'blocked' } else { 'ready  ' }
+    Write-Host ("    {0}  {1}" -f $mark, $s.title)
+}
+Write-Host ""
+Write-Host "  wrote $mdPath"
+Write-Host "  wrote $jsonPath"
+exit 0