Skip to content

foryourhealth111-pixel/Vibe-Skills

Vibe Code Orchestrator (VCO) is a governed runtime entry that freezes requirements, bounds execution, and enforces verification and phase cleanup.

FileKindSize
SKILL.mdskill md17.2 KB
agents/templates/debugger.mdmarkdown323 B
agents/templates/planner.mdmarkdown313 B
agents/templates/reviewer.mdmarkdown331 B
agents/templates/security-reviewer.mdmarkdown341 B
references/change-proof-matrix.mdmarkdown2.6 KB
references/contributor-zone-decision-table.mdmarkdown2.2 KB
references/developer-entry-contract.mdmarkdown2.7 KB
references/fixtures/external-corpus/external-corpus-gate.jsonconfig8.6 KB
references/fixtures/external-corpus/prompt-signals.jsonconfig412.4 KB
references/fixtures/external-corpus/skill-keyword-index.backup.jsonconfig30.6 KB
references/fixtures/external-corpus/skill-keyword-index.candidate.jsonconfig26.5 KB
references/fixtures/external-corpus/vco-suggestions.jsonconfig16.6 KB
references/fixtures/migration-map.jsonconfig7.8 KB
references/fixtures/retro-compare/safety-gate/baseline-cer.jsonconfig294 B
references/fixtures/retro-compare/safety-gate/current-cer.jsonconfig1.1 KB
references/fixtures/retro-compare/safety-gate/delta.jsonconfig1.0 KB
references/fixtures/retro-compare/sample-run/baseline-cer.jsonconfig324 B
references/fixtures/retro-compare/sample-run/current-cer.jsonconfig1.2 KB
references/fixtures/retro-compare/sample-run/delta.jsonconfig1.0 KB
references/fixtures/retro-compare/smoke/baseline-smoke.jsonconfig266 B
references/fixtures/retro-compare/smoke/current-smoke.jsonconfig1.0 KB
references/fixtures/retro-compare/smoke/delta-smoke.jsonconfig1.0 KB
references/fixtures/runtime/vibe-sessions/20260413T131910Z-pr153-rabbit-review-fix/cleanup-receipt.jsonconfig1.3 KB
references/fixtures/runtime/vibe-sessions/20260413T131910Z-pr153-rabbit-review-fix/governance-capsule.jsonconfig408 B
references/fixtures/runtime/vibe-sessions/20260413T131910Z-pr153-rabbit-review-fix/intent-contract.jsonconfig2.2 KB
references/fixtures/runtime/vibe-sessions/20260413T131910Z-pr153-rabbit-review-fix/phase-plan-execute.jsonconfig2.4 KB
references/fixtures/runtime/vibe-sessions/20260413T131910Z-pr153-rabbit-review-fix/skeleton-receipt.jsonconfig722 B
references/fixtures/runtime/vibe-sessions/20260413T131910Z-pr153-rabbit-review-fix/stage-lineage.jsonconfig1.3 KB
references/fixtures/skills-audit/bio-science-problem/bio-science-problem-map.csvother9.2 KB
references/fixtures/skills-audit/bio-science-problem/bio-science-problem-map.jsonconfig18.1 KB
references/fixtures/verify/routing-stability/vibe-routing-stability-gate.jsonconfig24.4 KB
references/index.mdmarkdown1.3 KB
references/proof-bundles/claude-code-managed-closure-candidate/linux-managed-run-01-local-host/installed-runtime-outputs/runtime-freshness-receipt.jsonconfig262 B
references/proof-bundles/claude-code-managed-closure-candidate/manifest.jsonconfig2.6 KB
references/proof-bundles/linux-full-authoritative-candidate/linux-pwsh-run-01-wsl/installed-runtime-outputs/runtime-freshness-receipt.jsonconfig298 B
references/proof-bundles/linux-full-authoritative-candidate/linux-pwsh-run-02-docker/installed-runtime-outputs/runtime-freshness-receipt.jsonconfig298 B
references/proof-bundles/linux-full-authoritative-candidate/manifest.jsonconfig3.3 KB
references/proof-bundles/openclaw-runtime-core-preview-candidate/manifest.jsonconfig1.9 KB
references/release-ledger.jsonlother5.1 KB
scripts/README.mdmarkdown1.7 KB
scripts/bootstrap/one-shot-setup.ps1script797 B
scripts/bootstrap/one-shot-setup.shscript482 B
scripts/bootstrap/scaffold-claude-preview.ps1script875 B
scripts/bootstrap/scaffold-claude-preview.shexecutablescript866 B
scripts/bootstrap/sync-local-compat.ps1script2.6 KB
scripts/common/AntiProxyGoalDrift.ps1script15.1 KB
scripts/common/NodeLaunchWrapper.ps1script13.1 KB
scripts/common/ProcessLedger.ps1script27.1 KB
scripts/common/ProtectedDocumentCleanup.ps1script6.9 KB
scripts/common/README.mdmarkdown1.9 KB
scripts/common/Resolve-VgoAdapter.ps1script4.3 KB
scripts/common/adapter_registry_query.pyexecutablescript3.8 KB
scripts/common/python_helpers.shscript2.8 KB
scripts/common/resolve_vgo_adapter.pyexecutablescript2.4 KB
scripts/common/runtime_contracts.pyscript3.7 KB
scripts/common/vibe-governance-helpers.ps1script75.6 KB
scripts/common/vibe-wave-gate-runner.ps1script28.3 KB
scripts/governance/Invoke-NodeProcessAudit.ps1script3.6 KB
scripts/governance/Invoke-NodeZombieCleanup.ps1script3.7 KB
scripts/governance/README.mdmarkdown5.1 KB
scripts/governance/audit-upstream.ps1script22.7 KB
scripts/governance/export-repo-cleanliness-inventory.ps1script8.6 KB
scripts/governance/install-local-worktree-excludes.ps1script2.0 KB
scripts/governance/invoke-mem0-policy.ps1script1.0 KB
scripts/governance/invoke-openspec-governance.ps1script8.6 KB
scripts/governance/new-origin-record.ps1script3.3 KB
scripts/governance/phase-end-cleanup.ps1script10.7 KB
scripts/governance/publish-absorption-soft-rollout.ps1script3.2 KB
scripts/governance/publish-openspec-soft-rollout.ps1script9.3 KB
scripts/governance/release-cut.ps1script25.1 KB
scripts/governance/set-gsd-overlay-rollout.ps1script3.9 KB
scripts/governance/set-openspec-rollout.ps1script3.1 KB
scripts/governance/sync-bundled-vibe.ps1script20.3 KB
scripts/install/Install-VgoAdapter.ps1script2.0 KB
scripts/install/install_vgo_adapter.pyexecutablescript524 B
scripts/overlay/README.mdmarkdown885 B
scripts/overlay/suggest-browserops-provider.ps1script9.3 KB
scripts/overlay/suggest-overlays.ps1script17.3 KB
scripts/release/build_release_bundle.pyscript6.5 KB
scripts/research/README.mdmarkdown1.1 KB
scripts/research/build-eval-slicing-catalog.ps1script2.6 KB
scripts/research/build-watch-portfolio-review.ps1script3.5 KB
scripts/research/build-xl-operator-checklist.ps1script2.3 KB
scripts/research/extract-prompt-signals.ps1script6.7 KB
scripts/research/generate-vco-suggestions.ps1script9.7 KB
scripts/research/sync-mcp-catalog.ps1script3.5 KB
scripts/research/vibe-adaptive-train.ps1script10.1 KB
scripts/router/README.mdmarkdown1.8 KB
scripts/router/invoke-pack-route.pyscript428 B
scripts/router/modules/00-core-utils.ps1script14.6 KB
scripts/router/modules/01-openai-responses.ps1script17.9 KB
scripts/router/modules/10-observability.ps1script11.7 KB
scripts/router/modules/11-route-probe.ps1script20.7 KB
scripts/router/modules/12-heartbeat.ps1script19.9 KB
scripts/router/modules/19-custom-admission.ps1script16.3 KB
scripts/router/modules/20-routing-rules.ps1script1.7 KB
scripts/router/modules/21-capability-interview.ps1script11.8 KB
scripts/router/modules/22-intent-contract.ps1script18.2 KB
scripts/router/modules/30-openspec.ps1script8.3 KB
scripts/router/modules/31-gsd-overlay.ps1script5.5 KB
scripts/router/modules/32-prompt-overlay.ps1script8.0 KB
scripts/router/modules/33-memory-governance.ps1script5.5 KB
scripts/router/modules/34-data-scale-overlay.ps1script25.8 KB
scripts/router/modules/35-quality-debt-overlay.ps1script13.4 KB
scripts/router/modules/36-framework-interop-overlay.ps1script16.9 KB
scripts/router/modules/37-ml-lifecycle-overlay.ps1script22.4 KB
scripts/router/modules/38-python-clean-code-overlay.ps1script16.2 KB
scripts/router/modules/39-system-design-overlay.ps1script15.5 KB
scripts/router/modules/40-cuda-kernel-overlay.ps1script17.7 KB
scripts/router/modules/42-ai-rerank-overlay.ps1script14.0 KB
scripts/router/modules/43-retrieval-overlay.ps1script22.4 KB
scripts/router/modules/44-dialectic-team-gate.ps1script7.5 KB
scripts/router/modules/44-exploration-overlay.ps1script17.7 KB
scripts/router/modules/45-daily-dialectic-guard.ps1script6.6 KB
scripts/router/modules/47-closure-overlay.ps1script9.2 KB
scripts/router/modules/48-llm-acceleration-overlay.ps1script104.6 KB
scripts/router/modules/49-prompt-asset-boost.ps1script28.3 KB
scripts/router/resolve-pack-route.ps1script4.1 KB
scripts/router/runtime_neutral/custom_admission.pyscript349 B
scripts/router/runtime_neutral/router_contract.pyscript356 B
scripts/ruc-nlpir/preflight.ps1script5.3 KB
scripts/runtime/Freeze-RuntimeInputPacket.ps1script33.0 KB
scripts/runtime/Invoke-AntiProxyGoalDriftCompaction.ps1script551 B
scripts/runtime/Invoke-DeepInterview.ps1script1.1 KB
scripts/runtime/Invoke-PhaseCleanup.ps1script11.1 KB
scripts/runtime/Invoke-PlanExecute.ps1script13.7 KB
scripts/runtime/Invoke-SkeletonCheck.ps1script3.1 KB
scripts/runtime/Invoke-VibeCanonicalEntry.ps1script12.9 KB
scripts/runtime/VibeMemoryActivation.Common.ps1script41.3 KB
scripts/runtime/VibeMemoryBackends.Common.ps1script12.4 KB
scripts/runtime/VibeRuntime.Common.ps1script298.6 KB
scripts/runtime/VibeSkillRouting.Common.ps1script19.0 KB
scripts/runtime/VibeWorkspaceMemory.Common.ps1script6.9 KB
scripts/runtime/Write-RequirementDoc.ps1script23.7 KB
scripts/runtime/Write-XlPlan.ps1script32.3 KB
scripts/runtime/invoke-vibe-runtime.ps1script69.7 KB
scripts/runtime/memory_backend_driver.pyscript14.2 KB
scripts/runtime/skill_authority_driver.pyscript375 B
scripts/runtime/workspace_memory_driver.pyscript24.8 KB
scripts/setup/check-kvm-host-readiness.shscript3.4 KB
scripts/setup/check-windows-eval-iso-readiness.shexecutablescript2.2 KB
scripts/setup/check-windows-proof-vm-state.shexecutablescript2.0 KB
scripts/setup/export-codex-settings-sanitized.ps1script2.6 KB
scripts/setup/fetch-windows11-eval-iso.shexecutablescript4.1 KB
scripts/setup/install-local-vm-host.shexecutablescript1.6 KB
scripts/setup/persist-codex-openai-env.ps1script2.4 KB
scripts/setup/run-windows-proof-vm.shexecutablescript11.4 KB
scripts/setup/send-qmp-boot-keys.pyexecutablescript3.0 KB
scripts/setup/send-qmp-text.pyexecutablescript3.0 KB
scripts/setup/show-windows-proof-media-options.shexecutablescript1.6 KB
scripts/setup/stop-windows-proof-vm.shexecutablescript1.6 KB
scripts/setup/sync-codex-settings-to-user-env.ps1script2.6 KB
scripts/uninstall/Uninstall-VgoAdapter.ps1script1.4 KB
scripts/uninstall/uninstall_vgo_adapter.pyscript526 B
scripts/verify/README.mdmarkdown3.8 KB
scripts/verify/cer-compare.ps1script8.5 KB
scripts/verify/fixtures/README.mdmarkdown1.1 KB
scripts/verify/fixtures/document-cleanup-safety/README.mdmarkdown527 B
scripts/verify/fixtures/document-cleanup-safety/ambiguous-cn-set/metadata.jsonconfig101 B
scripts/verify/fixtures/document-cleanup-safety/ambiguous-cn-set/source/.tmp/docs/重庆市永川区技术预见与制度创新项目申报书1-修订版.docxbinary56 B
scripts/verify/fixtures/document-cleanup-safety/ambiguous-cn-set/source/.tmp/docs/重庆市永川区技术预见与制度创新项目申报书1-补充材料.pdfbinary56 B
scripts/verify/fixtures/document-cleanup-safety/ambiguous-cn-set/source/docs/重庆市永川区技术预见与制度创新项目申报书1-正式版.docxbinary36 B
scripts/verify/fixtures/document-cleanup-safety/mixed-office-assets/metadata.jsonconfig101 B
scripts/verify/fixtures/document-cleanup-safety/mixed-office-assets/source/.tmp/staging/budget-review.xlsxbinary59 B
scripts/verify/fixtures/document-cleanup-safety/mixed-office-assets/source/.tmp/staging/quarterly-review-deck.pptxbinary60 B
scripts/verify/fixtures/document-cleanup-safety/mixed-office-assets/source/docs/reference-manual.pdfbinary21 B
scripts/verify/fixtures/document-cleanup-safety/non-protected-control/metadata.jsonconfig101 B
scripts/verify/fixtures/document-cleanup-safety/non-protected-control/source/.tmp/control.txtmarkdown54 B
scripts/verify/fixtures/llm-acceleration.mock.jsonconfig1.0 KB
scripts/verify/fixtures/pilot-browserops.jsonconfig541 B
scripts/verify/fixtures/pilot-deep-extraction.jsonconfig731 B
scripts/verify/fixtures/pilot-desktopops.jsonconfig587 B
scripts/verify/fixtures/pilot-memory.jsonconfig575 B
scripts/verify/fixtures/pilot-prompt.jsonconfig525 B
scripts/verify/fixtures/process-health/external-node-protected-fixture.jsonconfig345 B
scripts/verify/fixtures/process-health/healthy-managed-fixture.jsonconfig1.1 KB
scripts/verify/fixtures/process-health/managed-completed-alive-fixture.jsonconfig1.2 KB
scripts/verify/fixtures/process-health/managed-stale-fixture.jsonconfig1.1 KB
scripts/verify/fixtures/process-health/no-node-processes-fixture.jsonconfig131 B
scripts/verify/fixtures/prompt-asset-boost.mock.jsonconfig1.2 KB
scripts/verify/gate-family-index.mdmarkdown2.5 KB
scripts/verify/lib/VibeOfflineSkillsAudit.Suites.ps1script11.8 KB
scripts/verify/lib/VibeOfflineSkillsAudit.ps1script12.2 KB
scripts/verify/lib/VibeRouteAudit.Suites.ps1script7.9 KB
scripts/verify/lib/VibeRouteAudit.ps1script5.2 KB
scripts/verify/live-document-gate.pyscript7.6 KB
scripts/verify/probe-scientific-packs.ps1script55.1 KB
scripts/verify/publish-proof.pyscript409 B
scripts/verify/runtime_neutral/README.mdmarkdown2.5 KB
scripts/verify/runtime_neutral/_bootstrap.pyscript321 B
scripts/verify/runtime_neutral/bio_science_pack_consolidation_audit.pyscript421 B
scripts/verify/runtime_neutral/bootstrap_doctor.pyscript494 B
scripts/verify/runtime_neutral/code_quality_pack_consolidation_audit.pyscript717 B
scripts/verify/runtime_neutral/coherence_gate.pyscript529 B
scripts/verify/runtime_neutral/freshness_gate.pyscript494 B
scripts/verify/runtime_neutral/global_pack_consolidation_audit.pyscript635 B
scripts/verify/runtime_neutral/ml_skills_pruning_audit.pyscript574 B
scripts/verify/runtime_neutral/opencode_preview_smoke.pyscript674 B
scripts/verify/runtime_neutral/release_notes_quality.pyscript701 B

scripts/common/ProcessLedger.ps1

View on GitHub
Set-StrictMode -Version Latest

. (Join-Path $PSScriptRoot 'vibe-governance-helpers.ps1')

function Get-VgoUtcTimestamp {
    return (Get-Date).ToUniversalTime().ToString('o')
}

function Test-VgoIsWindows {
    if (Get-Variable -Name IsWindows -Scope Global -ErrorAction SilentlyContinue) {
        return [bool]$global:IsWindows
    }

    return ($env:OS -eq 'Windows_NT')
}

function ConvertFrom-VgoNullableTimestamp {
    param([AllowNull()] [object]$Value)

    if ($null -eq $Value) {
        return $null
    }

    $text = [string]$Value
    if ([string]::IsNullOrWhiteSpace($text)) {
        return $null
    }

    try {
        return [datetimeoffset]::Parse(
            $text,
            [System.Globalization.CultureInfo]::InvariantCulture,
            [System.Globalization.DateTimeStyles]::RoundtripKind
        )
    } catch {
        return $null
    }
}

function Get-VgoElapsedSeconds {
    param(
        [AllowNull()] [object]$Timestamp,
        [AllowNull()] [datetimeoffset]$Now
    )

    $parsed = ConvertFrom-VgoNullableTimestamp -Value $Timestamp
    if ($null -eq $parsed) {
        return $null
    }

    $baseline = if ($null -ne $Now) { $Now } else { [datetimeoffset]::UtcNow }
    return [int][Math]::Max(0, [Math]::Floor(($baseline - $parsed).TotalSeconds))
}

function Get-VgoProcessHealthContext {
    param([string]$RepoRoot)

    $resolvedRoot = if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
        Resolve-VgoRepoRoot -StartPath $PSScriptRoot
    } else {
        [System.IO.Path]::GetFullPath($RepoRoot)
    }

    $healthPolicyPath = Join-Path $resolvedRoot 'config\process-health-policy.json'
    $ledgerPolicyPath = Join-Path $resolvedRoot 'config\process-ledger-policy.json'

    if (-not (Test-Path -LiteralPath $healthPolicyPath)) {
        throw "Missing process-health policy: $healthPolicyPath"
    }
    if (-not (Test-Path -LiteralPath $ledgerPolicyPath)) {
        throw "Missing process-ledger policy: $ledgerPolicyPath"
    }

    $healthPolicy = Get-Content -LiteralPath $healthPolicyPath -Raw -Encoding UTF8 | ConvertFrom-Json
    $ledgerPolicy = Get-Content -LiteralPath $ledgerPolicyPath -Raw -Encoding UTF8 | ConvertFrom-Json

    $runtimeRoot = Join-Path $resolvedRoot ([string]$ledgerPolicy.paths.runtime_root)
    $ledgerPath = Join-Path $resolvedRoot ([string]$ledgerPolicy.paths.ledger)
    $eventsPath = Join-Path $resolvedRoot ([string]$ledgerPolicy.paths.events)
    $heartbeatsDir = Join-Path $resolvedRoot ([string]$ledgerPolicy.paths.heartbeats)
    $auditsDir = Join-Path $resolvedRoot ([string]$ledgerPolicy.paths.audits)
    $cleanupsDir = Join-Path $resolvedRoot ([string]$ledgerPolicy.paths.cleanups)

    return [pscustomobject]@{
        repoRoot = $resolvedRoot
        healthPolicyPath = $healthPolicyPath
        ledgerPolicyPath = $ledgerPolicyPath
        healthPolicy = $healthPolicy
        ledgerPolicy = $ledgerPolicy
        runtimeRoot = $runtimeRoot
        ledgerPath = $ledgerPath
        eventsPath = $eventsPath
        heartbeatsDir = $heartbeatsDir
        auditsDir = $auditsDir
        cleanupsDir = $cleanupsDir
    }
}

function Initialize-VgoProcessHealthRuntime {
    param([string]$RepoRoot)

    $context = Get-VgoProcessHealthContext -RepoRoot $RepoRoot
    foreach ($dir in @($context.runtimeRoot, $context.heartbeatsDir, $context.auditsDir, $context.cleanupsDir)) {
        if (-not (Test-Path -LiteralPath $dir)) {
            New-Item -ItemType Directory -Path $dir -Force | Out-Null
        }
    }

    if (-not (Test-Path -LiteralPath $context.ledgerPath)) {
        $initialLedger = [ordered]@{
            version = [int]$context.ledgerPolicy.schema_version
            updated_at = $null
            entries = @()
        }
        Write-VgoUtf8NoBomText -Path $context.ledgerPath -Content ($initialLedger | ConvertTo-Json -Depth 20)
    }

    return $context
}

function Get-VgoProcessLedgerMutexName {
    param([string]$RepoRoot)

    $context = Get-VgoProcessHealthContext -RepoRoot $RepoRoot
    $prefix = [string]$context.ledgerPolicy.locking.named_mutex_prefix
    if ([string]::IsNullOrWhiteSpace($prefix)) {
        $prefix = 'Global\VgoProcessLedger'
    }

    $sha256 = [System.Security.Cryptography.SHA256]::Create()
    try {
        $hashBytes = $sha256.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($context.repoRoot))
    } finally {
        $sha256.Dispose()
    }

    $repoHash = [System.BitConverter]::ToString($hashBytes).Replace('-', '').Substring(0, 16)

    return '{0}_{1}' -f $prefix, $repoHash
}

function Invoke-VgoProcessLedgerLocked {
    param(
        [string]$RepoRoot,
        [Parameter(Mandatory)] [scriptblock]$ScriptBlock
    )

    $context = Get-VgoProcessHealthContext -RepoRoot $RepoRoot
    $mutexName = Get-VgoProcessLedgerMutexName -RepoRoot $context.repoRoot
    $timeoutSec = [int]$context.ledgerPolicy.locking.wait_timeout_sec
    $createdNew = $false
    $mutex = [System.Threading.Mutex]::new($false, $mutexName, [ref]$createdNew)
    $lockAcquired = $false

    try {
        try {
            $lockAcquired = $mutex.WaitOne([TimeSpan]::FromSeconds($timeoutSec))
        } catch [System.Threading.AbandonedMutexException] {
            $lockAcquired = $true
        }

        if (-not $lockAcquired) {
            throw "Timed out waiting for process ledger mutex '$mutexName'."
        }

        return (& $ScriptBlock $context)
    } finally {
        if ($lockAcquired) {
            $mutex.ReleaseMutex()
        }
        $mutex.Dispose()
    }
}

function Get-VgoProcessLedger {
    param(
        [string]$RepoRoot,
        [AllowNull()] [object]$LedgerOverride
    )

    if ($null -ne $LedgerOverride) {
        return $LedgerOverride
    }

    Initialize-VgoProcessHealthRuntime -RepoRoot $RepoRoot | Out-Null

    return Invoke-VgoProcessLedgerLocked -RepoRoot $RepoRoot -ScriptBlock {
        param($Context)
        Get-Content -LiteralPath $Context.ledgerPath -Raw -Encoding UTF8 | ConvertFrom-Json
    }
}

function Write-VgoProcessLedgerEventUnsafe {
    param(
        [Parameter(Mandatory)] $Context,
        [Parameter(Mandatory)] [hashtable]$Event
    )

    $payload = [ordered]@{
        timestamp = Get-VgoUtcTimestamp
        event = [string]$Event.event
        entry_id = $Event.entry_id
        pid = $Event.pid
        launcher_pid = $Event.launcher_pid
        status = $Event.status
        note = $Event.note
        data = $Event.data
    }

    Append-VgoUtf8NoBomText -Path $Context.eventsPath -Content (($payload | ConvertTo-Json -Depth 20 -Compress) + [Environment]::NewLine)
}

function New-VgoProcessLedgerEntryId {
    return ('vgo-node-{0}' -f ([guid]::NewGuid().ToString('N')))
}

function Update-VgoProcessLedgerEntry {
    param(
        [Parameter(Mandatory)] [string]$EntryId,
        [Parameter(Mandatory)] [hashtable]$Patch,
        [string]$RepoRoot,
        [string]$EventType = 'entry.updated',
        [string]$Note
    )

    Initialize-VgoProcessHealthRuntime -RepoRoot $RepoRoot | Out-Null

    return Invoke-VgoProcessLedgerLocked -RepoRoot $RepoRoot -ScriptBlock {
        param($Context)

        $ledger = Get-Content -LiteralPath $Context.ledgerPath -Raw -Encoding UTF8 | ConvertFrom-Json
        $entries = @($ledger.entries)
        $found = $false
        $updatedEntry = $null

        for ($index = 0; $index -lt $entries.Count; $index++) {
            if ([string]$entries[$index].entry_id -ne $EntryId) {
                continue
            }

            foreach ($key in $Patch.Keys) {
                $entries[$index] | Add-Member -NotePropertyName $key -NotePropertyValue $Patch[$key] -Force
            }
            $updatedEntry = $entries[$index]
            $found = $true
            break
        }

        if (-not $found) {
            throw "Ledger entry not found: $EntryId"
        }

        $ledger | Add-Member -NotePropertyName entries -NotePropertyValue $entries -Force
        $ledger | Add-Member -NotePropertyName updated_at -NotePropertyValue (Get-VgoUtcTimestamp) -Force
        Write-VgoUtf8NoBomText -Path $Context.ledgerPath -Content ($ledger | ConvertTo-Json -Depth 40)

        Write-VgoProcessLedgerEventUnsafe -Context $Context -Event @{
            event = $EventType
            entry_id = $updatedEntry.entry_id
            pid = $updatedEntry.pid
            launcher_pid = $updatedEntry.launcher_pid
            status = $updatedEntry.status
            note = $Note
            data = $Patch
        }

        return $updatedEntry
    }
}

function Register-VgoProcessLedgerEntry {
    param(
        [Parameter(Mandatory)] [hashtable]$Entry,
        [string]$RepoRoot,
        [string]$Note = 'registered'
    )

    $context = Initialize-VgoProcessHealthRuntime -RepoRoot $RepoRoot
    $defaults = $context.ledgerPolicy.defaults
    $entryId = if ($Entry.ContainsKey('entry_id') -and $null -ne $Entry.entry_id -and -not [string]::IsNullOrWhiteSpace([string]$Entry.entry_id)) { [string]$Entry.entry_id } else { New-VgoProcessLedgerEntryId }
    $startedAt = if ($Entry.ContainsKey('started_at') -and $null -ne $Entry.started_at -and -not [string]::IsNullOrWhiteSpace([string]$Entry.started_at)) { [string]$Entry.started_at } else { Get-VgoUtcTimestamp }

    $normalizedEntry = [ordered]@{
        entry_id = $entryId
        label = if ($Entry.ContainsKey('label') -and $null -ne $Entry.label -and -not [string]::IsNullOrWhiteSpace([string]$Entry.label)) { [string]$Entry.label } else { 'node-runtime' }
        owner_id = if ($Entry.ContainsKey('owner_id') -and $null -ne $Entry.owner_id -and -not [string]::IsNullOrWhiteSpace([string]$Entry.owner_id)) { [string]$Entry.owner_id } else { $env:USERNAME }
        pid = if ($Entry.ContainsKey('pid')) { [int]$Entry.pid } else { $null }
        launcher_pid = if ($Entry.ContainsKey('launcher_pid')) { [int]$Entry.launcher_pid } else { $null }
        working_directory = if ($Entry.ContainsKey('working_directory') -and $null -ne $Entry.working_directory -and -not [string]::IsNullOrWhiteSpace([string]$Entry.working_directory)) { [string]$Entry.working_directory } else { $null }
        command_line = if ($Entry.ContainsKey('command_line') -and $null -ne $Entry.command_line -and -not [string]::IsNullOrWhiteSpace([string]$Entry.command_line)) { [string]$Entry.command_line } else { $null }
        status = if ($Entry.ContainsKey('status') -and $null -ne $Entry.status -and -not [string]::IsNullOrWhiteSpace([string]$Entry.status)) { [string]$Entry.status } else { [string]$defaults.status }
        started_at = $startedAt
        closed_at = if ($Entry.ContainsKey('closed_at') -and $null -ne $Entry.closed_at -and -not [string]::IsNullOrWhiteSpace([string]$Entry.closed_at)) { [string]$Entry.closed_at } else { $null }
        last_heartbeat_at = if ($Entry.ContainsKey('last_heartbeat_at') -and $null -ne $Entry.last_heartbeat_at -and -not [string]::IsNullOrWhiteSpace([string]$Entry.last_heartbeat_at)) { [string]$Entry.last_heartbeat_at } else { $startedAt }
        last_seen_alive_at = if ($Entry.ContainsKey('last_seen_alive_at') -and $null -ne $Entry.last_seen_alive_at -and -not [string]::IsNullOrWhiteSpace([string]$Entry.last_seen_alive_at)) { [string]$Entry.last_seen_alive_at } else { $startedAt }
        heartbeat_path = if ($Entry.ContainsKey('heartbeat_path') -and $null -ne $Entry.heartbeat_path -and -not [string]::IsNullOrWhiteSpace([string]$Entry.heartbeat_path)) { [string]$Entry.heartbeat_path } else { $null }
        ownership = if ($Entry.ContainsKey('ownership') -and $null -ne $Entry.ownership -and -not [string]::IsNullOrWhiteSpace([string]$Entry.ownership)) { [string]$Entry.ownership } else { [string]$defaults.ownership }
        cleanup_safe = if ($Entry.ContainsKey('cleanup_safe')) { [bool]$Entry.cleanup_safe } else { [bool]$defaults.cleanup_safe }
        stale_after_sec = if ($Entry.ContainsKey('stale_after_sec')) { [int]$Entry.stale_after_sec } else { [int]$defaults.stale_after_sec }
        heartbeat_interval_sec = if ($Entry.ContainsKey('heartbeat_interval_sec')) { [int]$Entry.heartbeat_interval_sec } else { [int]$defaults.heartbeat_interval_sec }
        node_pid_confirmed = if ($Entry.ContainsKey('node_pid_confirmed')) { [bool]$Entry.node_pid_confirmed } else { $false }
        target_process_name = if ($Entry.ContainsKey('target_process_name') -and $null -ne $Entry.target_process_name -and -not [string]::IsNullOrWhiteSpace([string]$Entry.target_process_name)) { [string]$Entry.target_process_name } else { $null }
    }

    return Invoke-VgoProcessLedgerLocked -RepoRoot $RepoRoot -ScriptBlock {
        param($LockedContext)
        $ledger = Get-Content -LiteralPath $LockedContext.ledgerPath -Raw -Encoding UTF8 | ConvertFrom-Json
        $entries = @($ledger.entries)
        $entries += ([pscustomobject]$normalizedEntry)
        $ledger | Add-Member -NotePropertyName entries -NotePropertyValue $entries -Force
        $ledger | Add-Member -NotePropertyName updated_at -NotePropertyValue (Get-VgoUtcTimestamp) -Force
        Write-VgoUtf8NoBomText -Path $LockedContext.ledgerPath -Content ($ledger | ConvertTo-Json -Depth 40)

        Write-VgoProcessLedgerEventUnsafe -Context $LockedContext -Event @{
            event = 'entry.registered'
            entry_id = $normalizedEntry.entry_id
            pid = $normalizedEntry.pid
            launcher_pid = $normalizedEntry.launcher_pid
            status = $normalizedEntry.status
            note = $Note
            data = $normalizedEntry
        }

        return [pscustomobject]$normalizedEntry
    }
}

function Complete-VgoProcessLedgerEntry {
    param(
        [Parameter(Mandatory)] [string]$EntryId,
        [string]$RepoRoot,
        [string]$FinalStatus = 'completed',
        [string]$Note = 'completed'
    )

    return Update-VgoProcessLedgerEntry -EntryId $EntryId -RepoRoot $RepoRoot -EventType 'entry.completed' -Note $Note -Patch @{
        status = $FinalStatus
        closed_at = Get-VgoUtcTimestamp
    }
}

function Write-VgoProcessHeartbeatFile {
    param(
        [Parameter(Mandatory)] [string]$Path,
        [Parameter(Mandatory)] [string]$EntryId,
        [Parameter(Mandatory)] [string]$State,
        [string]$Note,
        [int]$ProcessId,
        [int]$LauncherPid
    )

    $payload = [ordered]@{
        entry_id = $EntryId
        state = $State
        pid = if ($ProcessId -gt 0) { $ProcessId } else { $null }
        launcher_pid = if ($LauncherPid -gt 0) { $LauncherPid } else { $null }
        note = $Note
        updated_at = Get-VgoUtcTimestamp
    }

    Write-VgoUtf8NoBomText -Path $Path -Content ($payload | ConvertTo-Json -Depth 10)
}

function Test-VgoNodeProcessName {
    param(
        [AllowNull()] [string]$ProcessName,
        [AllowNull()] [object]$HealthPolicy
    )

    if ([string]::IsNullOrWhiteSpace($ProcessName)) {
        return $false
    }

    $names = if ($HealthPolicy -and $HealthPolicy.process_detection -and $HealthPolicy.process_detection.node_process_names) {
        @($HealthPolicy.process_detection.node_process_names | ForEach-Object { [string]$_ })
    } else {
        @('node', 'node.exe')
    }

    return ($names -contains $ProcessName.ToLowerInvariant())
}

function Test-VgoProcessAlive {
    param([Nullable[int]]$ProcessId)

    if ($null -eq $ProcessId -or $ProcessId -le 0) {
        return $false
    }

    try {
        $null = Get-Process -Id $ProcessId -ErrorAction Stop
        return $true
    } catch {
        return $false
    }
}

function Get-VgoWindowsProcessMetadata {
    param([AllowNull()] [int[]]$Pids)

    $metadata = @{}
    $uniquePids = @($Pids | Where-Object { $_ -gt 0 } | Select-Object -Unique)
    foreach ($processId in $uniquePids) {
        try {
            $proc = Get-CimInstance Win32_Process -Filter ("ProcessId={0}" -f $processId) -OperationTimeoutSec 2 -ErrorAction Stop
            if ($null -eq $proc) {
                continue
            }

            $metadata[[string]$processId] = [pscustomobject]@{
                pid = [int]$proc.ProcessId
                parent_pid = [int]$proc.ParentProcessId
                process_name = [string]$proc.Name
                command_line = [string]$proc.CommandLine
            }
        } catch {
            continue
        }
    }

    return $metadata
}

function Get-VgoLiveNodeProcessSnapshot {
    param([string]$RepoRoot)

    $context = Get-VgoProcessHealthContext -RepoRoot $RepoRoot
    $healthPolicy = $context.healthPolicy

    $rows = @()
    if (Test-VgoIsWindows) {
        $processes = @(Get-Process -Name node,node.exe -ErrorAction SilentlyContinue)
        foreach ($proc in $processes) {
            $processId = [int]$proc.Id
            $workingSetBytes = [int64]$proc.WorkingSet64

            $rows += [pscustomobject]@{
                pid = $processId
                parent_pid = $null
                process_name = [string]$proc.ProcessName
                command_line = $null
                working_set_bytes = [int64]$workingSetBytes
                working_set_mb = [double][Math]::Round(($workingSetBytes / 1MB), 2)
            }
        }
    } else {
        $processes = @(Get-Process -Name node -ErrorAction SilentlyContinue)
        foreach ($proc in $processes) {
            $rows += [pscustomobject]@{
                pid = [int]$proc.Id
                parent_pid = $null
                process_name = [string]$proc.ProcessName
                command_line = $null
                working_set_bytes = [int64]$proc.WorkingSet64
                working_set_mb = [double][Math]::Round(($proc.WorkingSet64 / 1MB), 2)
            }
        }
    }

    return $rows
}

function Get-VgoNodeAuditInput {
    param(
        [string]$RepoRoot,
        [string]$FixturePath
    )

    if (-not [string]::IsNullOrWhiteSpace($FixturePath)) {
        if (-not (Test-Path -LiteralPath $FixturePath)) {
            throw "Fixture not found: $FixturePath"
        }

        $fixture = Get-Content -LiteralPath $FixturePath -Raw -Encoding UTF8 | ConvertFrom-Json
        $now = ConvertFrom-VgoNullableTimestamp -Value $fixture.now
        if ($null -eq $now) {
            $now = [datetimeoffset]::UtcNow
        }

        return [pscustomobject]@{
            source = 'fixture'
            fixture_path = [System.IO.Path]::GetFullPath($FixturePath)
            now = $now
            live_processes = @($fixture.live_processes)
            ledger = if ($fixture.ledger) { $fixture.ledger } else { [pscustomobject]@{ entries = @() } }
            case_id = if ($fixture.case_id) { [string]$fixture.case_id } else { [System.IO.Path]::GetFileNameWithoutExtension($FixturePath) }
        }
    }

    return [pscustomobject]@{
        source = 'live'
        fixture_path = $null
        now = [datetimeoffset]::UtcNow
        live_processes = @(Get-VgoLiveNodeProcessSnapshot -RepoRoot $RepoRoot)
        ledger = Get-VgoProcessLedger -RepoRoot $RepoRoot
        case_id = 'live-runtime'
    }
}

function Find-VgoLedgerEntryForPid {
    param(
        [AllowNull()] [object[]]$Entries,
        [Nullable[int]]$ProcessId
    )

    if ($null -eq $ProcessId -or $ProcessId -le 0) {
        return $null
    }

    $matches = @($Entries | Where-Object { $_ -and $_.pid -eq $ProcessId })
    if ($matches.Count -eq 0) {
        return $null
    }

    return $matches | Sort-Object {
        $dt = ConvertFrom-VgoNullableTimestamp -Value $_.started_at
        if ($null -eq $dt) { [datetimeoffset]::MinValue } else { $dt }
    } -Descending | Select-Object -First 1
}

function Get-VgoNodeProcessAuditRows {
    param(
        [string]$RepoRoot,
        [string]$FixturePath
    )

    $context = Get-VgoProcessHealthContext -RepoRoot $RepoRoot
    $healthPolicy = $context.healthPolicy
    $inputData = Get-VgoNodeAuditInput -RepoRoot $context.repoRoot -FixturePath $FixturePath
    $now = [datetimeoffset]$inputData.now
    $entries = @($inputData.ledger.entries)
    $protectOwnership = @($healthPolicy.cleanup.protect_ownership | ForEach-Object { [string]$_ })
    $allowedCleanupStates = @($healthPolicy.cleanup.allowed_classifications | ForEach-Object { [string]$_ })
    $rows = @()

    foreach ($process in @($inputData.live_processes)) {
        $processId = if ($process.PSObject.Properties.Name -contains 'pid' -and $process.pid -ne $null) { [int]$process.pid } else { $null }
        $processName = if ($process.PSObject.Properties.Name -contains 'process_name') { [string]$process.process_name } else { $null }
        $entry = Find-VgoLedgerEntryForPid -Entries $entries -ProcessId $processId
        $ownership = if ($null -ne $entry) { [string]$entry.ownership } else { [string]$healthPolicy.ownership_contract.external }
        $cleanupSafe = if ($null -ne $entry) { [bool]$entry.cleanup_safe } else { $false }
        $classification = $null
        $reasons = New-Object System.Collections.Generic.List[string]
        $heartbeatAge = $null
        $staleAfterSec = if ($null -ne $entry -and $entry.stale_after_sec -ne $null) { [int]$entry.stale_after_sec } else { [int]$healthPolicy.audit.stale_heartbeat_sec }

        if ($null -eq $processId -or $processId -le 0 -or -not (Test-VgoNodeProcessName -ProcessName $processName -HealthPolicy $healthPolicy)) {
            $classification = [string]$healthPolicy.ownership_contract.unknown + '_audit_only'
            $ownership = [string]$healthPolicy.ownership_contract.unknown
            $cleanupSafe = $false
            $reasons.Add('missing_or_non_node_process_identity') | Out-Null
        } elseif ($null -eq $entry) {
            $classification = 'external_audit_only'
            $reasons.Add('no_ledger_owner_for_pid') | Out-Null
        } else {
            $startedAge = Get-VgoElapsedSeconds -Timestamp $entry.started_at -Now $now
            $heartbeatAge = Get-VgoElapsedSeconds -Timestamp $entry.last_heartbeat_at -Now $now
            $entryStatus = [string]$entry.status
            if ($entryStatus -in @('completed', 'terminated')) {
                $classification = 'managed_completed_process_alive'
                $reasons.Add("ledger_status=$entryStatus") | Out-Null
                $reasons.Add('process_still_alive_after_completion') | Out-Null
            } elseif ($null -eq $heartbeatAge) {
                if ($null -ne $startedAge -and $startedAge -gt [int]$healthPolicy.audit.startup_grace_sec) {
                    $classification = 'managed_missing_heartbeat'
                    $reasons.Add('heartbeat_missing_after_startup_grace') | Out-Null
                } else {
                    $classification = 'managed_live'
                    $reasons.Add('inside_startup_grace_without_heartbeat') | Out-Null
                }
            } elseif ($heartbeatAge -gt $staleAfterSec) {
                $classification = 'managed_stale'
                $reasons.Add("heartbeat_age_sec=$heartbeatAge") | Out-Null
                $reasons.Add("stale_after_sec=$staleAfterSec") | Out-Null
            } elseif ($heartbeatAge -gt [int]$healthPolicy.audit.missing_heartbeat_sec) {
                $classification = 'managed_missing_heartbeat'
                $reasons.Add("heartbeat_age_sec=$heartbeatAge") | Out-Null
                $reasons.Add('heartbeat_missing_threshold_exceeded') | Out-Null
            } else {
                $classification = 'managed_live'
                $reasons.Add("heartbeat_age_sec=$heartbeatAge") | Out-Null
                $reasons.Add('heartbeat_fresh') | Out-Null
            }
        }

        $cleanupCandidate = (
            $ownership -eq [string]$healthPolicy.ownership_contract.managed -and
            $cleanupSafe -and
            ($allowedCleanupStates -contains $classification) -and
            -not ($protectOwnership -contains $ownership)
        )

        $rows += [pscustomobject]@{
            pid = $processId
            parent_pid = if ($process.PSObject.Properties.Name -contains 'parent_pid' -and $process.parent_pid -ne $null) { [int]$process.parent_pid } else { $null }
            process_name = $processName
            command_line = if ($process.PSObject.Properties.Name -contains 'command_line') { [string]$process.command_line } else { $null }
            working_set_bytes = if ($process.PSObject.Properties.Name -contains 'working_set_bytes') { [int64]$process.working_set_bytes } else { 0 }
            working_set_mb = if ($process.PSObject.Properties.Name -contains 'working_set_mb') { [double]$process.working_set_mb } else { 0.0 }
            classification = $classification
            ownership = $ownership
            cleanup_safe = $cleanupSafe
            cleanup_candidate = $cleanupCandidate
            entry_id = if ($null -ne $entry) { [string]$entry.entry_id } else { $null }
            label = if ($null -ne $entry) { [string]$entry.label } else { $null }
            launcher_pid = if ($null -ne $entry -and $entry.launcher_pid -ne $null) { [int]$entry.launcher_pid } else { $null }
            status = if ($null -ne $entry) { [string]$entry.status } else { $null }
            last_heartbeat_at = if ($null -ne $entry) { [string]$entry.last_heartbeat_at } else { $null }
            heartbeat_age_sec = $heartbeatAge
            stale_after_sec = if ($null -ne $entry) { $staleAfterSec } else { $null }
            reasons = @($reasons)
        }
    }

    $classificationCounts = [ordered]@{}
    foreach ($row in $rows) {
        $key = [string]$row.classification
        if (-not $classificationCounts.Contains($key)) {
            $classificationCounts[$key] = 0
        }
        $classificationCounts[$key]++
    }

    $workingSetSum = 0.0
    if ($rows.Count -gt 0) {
        $measure = $rows | Measure-Object -Property working_set_mb -Sum
        if ($null -ne $measure -and $measure.PSObject.Properties.Name -contains 'Sum' -and $null -ne $measure.Sum) {
            $workingSetSum = [double]$measure.Sum
        }
    }

    $summary = [ordered]@{
        case_id = [string]$inputData.case_id
        source = [string]$inputData.source
        generated_at = Get-VgoUtcTimestamp
        total_processes = $rows.Count
        cleanup_candidate_count = @($rows | Where-Object { $_.cleanup_candidate }).Count
        external_count = @($rows | Where-Object { $_.ownership -eq [string]$healthPolicy.ownership_contract.external }).Count
        unknown_count = @($rows | Where-Object { $_.ownership -eq [string]$healthPolicy.ownership_contract.unknown }).Count
        total_working_set_mb = [double][Math]::Round($workingSetSum, 2)
        classifications = $classificationCounts
    }

    return [pscustomobject]@{
        source = [string]$inputData.source
        fixture_path = $inputData.fixture_path
        case_id = [string]$inputData.case_id
        now = $now.ToString('o')
        rows = $rows
        summary = [pscustomobject]$summary
    }
}

function Get-VgoNodeCleanupCandidates {
    param(
        [AllowNull()] [object[]]$Rows,
        [AllowNull()] [object]$HealthPolicy
    )

    if ($null -eq $Rows) {
        return @()
    }

    $allowed = if ($HealthPolicy -and $HealthPolicy.cleanup -and $HealthPolicy.cleanup.allowed_classifications) {
        @($HealthPolicy.cleanup.allowed_classifications | ForEach-Object { [string]$_ })
    } else {
        @('managed_stale', 'managed_completed_process_alive')
    }

    $managedOwnership = if ($HealthPolicy -and $HealthPolicy.ownership_contract -and $HealthPolicy.ownership_contract.managed) {
        [string]$HealthPolicy.ownership_contract.managed
    } else {
        'vco-managed'
    }

    return @(
        $Rows | Where-Object {
            $_ -and
            $_.ownership -eq $managedOwnership -and
            [bool]$_.cleanup_safe -and
            ($allowed -contains [string]$_.classification)
        }
    )
}
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall