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/runtime/workspace_memory_driver.py

View on GitHub
from __future__ import annotations

import argparse
import hashlib
import json
import os
import re
import sys
import tempfile
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

if os.name == "nt":
    import msvcrt
else:
    import fcntl


CONTRACTS_SRC = Path(__file__).resolve().parents[2] / "packages" / "contracts" / "src"
if CONTRACTS_SRC.is_dir() and str(CONTRACTS_SRC) not in sys.path:
    sys.path.insert(0, str(CONTRACTS_SRC))

from vgo_contracts.workspace_memory_identity import workspace_memory_id  # noqa: E402
from vgo_contracts.live_governance_contract import (  # noqa: E402
    LiveGovernanceContract,
    load_live_governance_contract_file,
)


LANE_KIND = {
    "serena": ("project_decision_gate", "architecture_decision"),
    "ruflo": ("handoff_card", "short_term_semantic_context"),
    "cognee": ("entity_relation_ingest", "long_term_graph_context"),
}

LANE_OWNER = {
    "serena": "Serena",
    "ruflo": "ruflo",
    "cognee": "Cognee",
}

WORKSPACE_MEMORY_IDENTITY_SCOPE = "workspace"
WORKSPACE_MEMORY_DRIVER_CONTRACT = "workspace_shared_memory_v1"
WORKSPACE_MEMORY_LOGICAL_OWNERS = ["state_store", "serena", "ruflo", "cognee"]

NOISE_TOKENS = {
    "tmp",
    "temp",
    "telemetry",
    "heartbeat",
    "trace",
    "debug",
    "metric",
    "metrics",
    "log",
    "logs",
    "cache",
    "latency",
}

SIGNAL_TOKENS = {
    "approved",
    "decision",
    "handoff",
    "relation",
    "specified_by",
    "planned_in",
    "executed_as",
    "compatibility",
    "continuity",
}

STOP_TOKENS = {
    "approved",
    "about",
    "after",
    "along",
    "and",
    "around",
    "asks",
    "because",
    "before",
    "between",
    "codex",
    "context",
    "continuity",
    "debug",
    "decision",
    "dependencies",
    "dependency",
    "evidence",
    "execution",
    "follow-up",
    "from",
    "graph",
    "implementation",
    "into",
    "keep",
    "next",
    "onto",
    "over",
    "plan",
    "planner",
    "planning",
    "preserving",
    "prior",
    "prepare",
    "recall",
    "relationship",
    "retain",
    "review",
    "runtime",
    "step",
    "than",
    "that",
    "their",
    "there",
    "these",
    "they",
    "this",
    "those",
    "through",
    "under",
    "until",
    "user",
    "vibe",
    "vibeskills",
    "what",
    "when",
    "where",
    "while",
    "them",
    "then",
    "which",
    "with",
    "within",
    "without",
    "would",
    "were",
    "whose",
    "your",
    "for",
    "the",
}


def utc_now() -> str:
    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")


def ensure_parent(path: Path) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)


def load_json(path: Path) -> dict[str, Any]:
    return json.loads(path.read_text(encoding="utf-8"))


def write_json(path: Path, payload: dict[str, Any]) -> None:
    ensure_parent(path)
    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")


def load_jsonl(path: Path) -> list[dict[str, Any]]:
    if not path.exists():
        return []
    rows: list[dict[str, Any]] = []
    for line in path.read_text(encoding="utf-8").splitlines():
        line = line.strip()
        if not line:
            continue
        rows.append(json.loads(line))
    return rows


def write_jsonl(path: Path, rows: list[dict[str, Any]]) -> None:
    ensure_parent(path)
    content = "\n".join(json.dumps(row, ensure_ascii=False, sort_keys=True) for row in rows)
    if content:
        content += "\n"
    path.write_text(content, encoding="utf-8")


def write_jsonl_atomic(path: Path, rows: list[dict[str, Any]]) -> None:
    ensure_parent(path)
    content = "\n".join(json.dumps(row, ensure_ascii=False, sort_keys=True) for row in rows)
    if content:
        content += "\n"

    with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=str(path.parent), delete=False) as handle:
        handle.write(content)
        temp_path = Path(handle.name)
    os.replace(temp_path, path)


class PlaneLock:
    def __init__(self, plane_path: Path) -> None:
        self._lock_path = Path(f"{plane_path}.lock")
        self._handle = None

    def __enter__(self) -> "PlaneLock":
        ensure_parent(self._lock_path)
        self._handle = self._lock_path.open("a+", encoding="utf-8")
        if os.name == "nt":
            self._handle.seek(0)
            msvcrt.locking(self._handle.fileno(), msvcrt.LK_LOCK, 1)
        else:
            fcntl.flock(self._handle.fileno(), fcntl.LOCK_EX)
        return self

    def __exit__(self, exc_type, exc, tb) -> None:
        if self._handle is None:
            return
        try:
            if os.name == "nt":
                self._handle.seek(0)
                msvcrt.locking(self._handle.fileno(), msvcrt.LK_UNLCK, 1)
            else:
                fcntl.flock(self._handle.fileno(), fcntl.LOCK_UN)
        finally:
            self._handle.close()
            self._handle = None


def tokenize(text: str, *, filter_stop_tokens: bool = True) -> set[str]:
    return {
        token
        for token in re.findall(r"[a-z0-9_/-]{3,}", text.lower())
        if token and (not filter_stop_tokens or token not in STOP_TOKENS)
    }


def score_record(query: str, record: dict[str, Any]) -> int:
    query_tokens = tokenize(query)
    haystack = " ".join(
        [
            str(record.get("summary") or ""),
            " ".join(str(v) for v in record.get("keywords") or []),
            " ".join(str(v) for v in record.get("items") or []),
            " ".join(str(v) for v in record.get("evidence_paths") or []),
            str(record.get("relation") or ""),
            str(record.get("source") or ""),
            str(record.get("target") or ""),
        ]
    )
    return len(query_tokens & tokenize(haystack))


def dedupe_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
    by_id: dict[str, dict[str, Any]] = {}
    for row in rows:
        row_id = str(row.get("record_id") or "")
        if not row_id:
            row_id = hashlib.sha256(json.dumps(row, sort_keys=True).encode("utf-8")).hexdigest()[:16]
            row["record_id"] = row_id
        by_id[row_id] = row
    return list(by_id.values())


def load_workspace_memory_policy_bundle(repo_root: Path) -> dict[str, Any]:
    config_root = repo_root / "config"
    bundle: dict[str, Any] = {}
    for name in (
        "memory-ingest-policy",
        "memory-disclosure-policy",
        "workspace-memory-plane",
    ):
        path = config_root / f"{name}.json"
        bundle[name.replace("-", "_")] = load_json(path) if path.exists() else {}
    return bundle


def _relative_runtime_contract(
    repo_root: Path,
    policy_bundle: dict[str, Any] | None,
) -> dict[str, Any]:
    contract_path = repo_root / "config" / "live-document-contract.json"
    policy_bundle = policy_bundle or {}
    if "live_document_contract" in policy_bundle:
        raw_contract = policy_bundle["live_document_contract"]
        if not isinstance(raw_contract, dict):
            raise ValueError(
                f"live governance artifact contract is required: {contract_path}: "
                "contract payload must be an object"
            )
        try:
            contract = LiveGovernanceContract.model_validate(raw_contract)
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"live governance artifact contract is required: {contract_path}: {exc}"
            ) from exc
    elif contract_path.is_file():
        try:
            contract = load_live_governance_contract_file(contract_path)
        except (OSError, TypeError, ValueError) as exc:
            raise ValueError(
                f"live governance artifact contract is required: {contract_path}: {exc}"
            ) from exc
    else:
        raise ValueError(
            f"live governance artifact contract is required: {contract_path}"
        )
    sink = contract.artifact_sink
    legacy_roots = sink.legacy_documentation_root_map
    session_receipts = sink.session_receipts.model_dump()
    return {
        "artifact_sink_root": sink.root,
        "legacy_requirement_root": legacy_roots["requirement"],
        "legacy_execution_plan_root": legacy_roots["plan"],
        "legacy_projection_root": sink.legacy_projection_root,
        "artifact_paths": sink.artifact_path_map,
        "primary_document_paths": sink.primary_document_path_map,
        "manifest_path": sink.manifest_path,
        "legacy_compatibility_path": sink.legacy_compatibility_path,
        "session_root": session_receipts["root"],
        "session_receipts": session_receipts,
        "legacy_documentation_roots": list(sink.legacy_documentation_roots),
        "legacy_removal_release": sink.legacy_removal_release,
        "legacy_write_mode": sink.legacy_write_mode,
    }


def ensure_workspace_descriptor(repo_root: Path, policy_bundle: dict[str, Any] | None = None) -> dict[str, Any]:
    workspace_root = repo_root.resolve()
    sidecar_root = workspace_root / ".vibeskills"
    descriptor_path = sidecar_root / "project.json"
    if descriptor_path.exists():
        descriptor = load_json(descriptor_path)
    else:
        descriptor = {
            "schema_version": 1,
            "brand": "vibeskills",
            "generated_at": utc_now(),
            "workspace_root": str(workspace_root),
            "workspace_sidecar_root": str(sidecar_root),
            "project_descriptor_path": str(descriptor_path),
            "default_artifact_root": str(sidecar_root),
            "relative_runtime_contract": _relative_runtime_contract(
                workspace_root,
                policy_bundle,
            ),
            "host_sidecar_root": None,
        }
    descriptor["workspace_root"] = str(workspace_root)
    descriptor["workspace_sidecar_root"] = str(sidecar_root)
    descriptor["project_descriptor_path"] = str(descriptor_path)
    descriptor["default_artifact_root"] = str(sidecar_root)
    descriptor["relative_runtime_contract"] = _relative_runtime_contract(
        workspace_root,
        policy_bundle,
    )
    descriptor["memory_plane"] = {
        "identity_root": descriptor["project_descriptor_path"],
        "identity_scope": WORKSPACE_MEMORY_IDENTITY_SCOPE,
        "driver_contract": WORKSPACE_MEMORY_DRIVER_CONTRACT,
        "logical_owners": list(WORKSPACE_MEMORY_LOGICAL_OWNERS),
    }
    descriptor.setdefault("host_sidecar_root", None)
    write_json(descriptor_path, descriptor)
    return descriptor


def resolve_plane_path(descriptor: dict[str, Any]) -> Path:
    return Path(str(descriptor["workspace_sidecar_root"])) / "memory" / "workspace-memory-plane.jsonl"


def workspace_memory_projection(descriptor: dict[str, Any], plane_path: Path) -> dict[str, Any]:
    workspace_root = str(descriptor["workspace_root"])
    identity_root = str(descriptor["project_descriptor_path"])
    return {
        "schema_version": 1,
        "workspace_root": workspace_root,
        "workspace_sidecar_root": str(descriptor["workspace_sidecar_root"]),
        "descriptor_path": str(descriptor["project_descriptor_path"]),
        "workspace_id": workspace_memory_id(identity_root),
        "plane_path": str(plane_path),
    }


def is_temp_like_path(value: str) -> bool:
    normalized = value.replace("\\", "/").lower()
    return (
        normalized.startswith("/tmp/")
        or normalized.startswith("/var/tmp/")
        or "/.tmp/" in normalized
        or "/tmp/" in normalized
        or "/temp/" in normalized
        or "/cache/" in normalized
        or "/logs/" in normalized
        or normalized.endswith(".log")
    )


def classify_noise(record: dict[str, Any]) -> str | None:
    lane = str(record.get("lane") or "")
    if lane == "serena" and not str(record.get("summary") or "").strip():
        return "empty_summary"
    if lane == "ruflo" and not str(record.get("summary") or "").strip() and not record.get("items"):
        return "empty_handoff"
    if lane == "cognee":
        fields = [str(record.get("source") or "").strip(), str(record.get("relation") or "").strip(), str(record.get("target") or "").strip()]
        if any(not value for value in fields):
            return "empty_relation"

    text_parts = [
        str(record.get("summary") or ""),
        str(record.get("source") or ""),
        str(record.get("relation") or ""),
        str(record.get("target") or ""),
        " ".join(str(v) for v in record.get("items") or []),
        " ".join(str(v) for v in record.get("keywords") or []),
        " ".join(str(v) for v in record.get("evidence_paths") or []),
    ]
    raw_tokens = tokenize(" ".join(text_parts), filter_stop_tokens=False)
    if not raw_tokens:
        return "empty_payload"
    if raw_tokens & SIGNAL_TOKENS:
        return None
    tokens = {token for token in raw_tokens if token not in STOP_TOKENS}
    if not tokens:
        return "noise_only_tokens"
    noise_token_count = len(tokens & NOISE_TOKENS)
    signal_token_count = len(tokens - NOISE_TOKENS)
    noise_ratio = float(noise_token_count) / float(len(tokens)) if tokens else 0.0
    evidence_paths = [str(v) for v in record.get("evidence_paths") or [] if str(v).strip()]
    all_temp_like = bool(evidence_paths) and all(is_temp_like_path(path) for path in evidence_paths)
    if signal_token_count == 0:
        return "noise_only_tokens"
    if all_temp_like and signal_token_count <= 2 and noise_token_count >= 2:
        return "temp_path_noise"
    if all_temp_like and noise_ratio >= 0.5 and signal_token_count <= 4:
        return "temp_path_telemetry_noise"
    return None


def _serena_records(payload: dict[str, Any], project_key: str | None) -> list[dict[str, Any]]:
    records: list[dict[str, Any]] = []
    for decision in payload.get("decisions") or []:
        if not isinstance(decision, dict):
            continue
        record_basis = json.dumps(
            {
                "lane": "serena",
                "project_key": project_key,
                "summary": decision.get("summary"),
                "evidence_paths": decision.get("evidence_paths"),
            },
            sort_keys=True,
        )
        records.append(
            {
                "record_id": hashlib.sha256(record_basis.encode("utf-8")).hexdigest()[:16],
                "lane": "serena",
                "kind": "architecture_decision",
                "signal_type": "architecture_decision",
                "project_key": project_key,
                "summary": str(decision.get("summary") or "").strip(),
                "evidence_paths": [str(v) for v in decision.get("evidence_paths") or [] if str(v).strip()],
                "keywords": [str(v) for v in decision.get("keywords") or [] if str(v).strip()],
                "updated_at": utc_now(),
            }
        )
    return records


def _ruflo_records(payload: dict[str, Any], project_key: str | None) -> list[dict[str, Any]]:
    records: list[dict[str, Any]] = []
    for card in payload.get("cards") or []:
        if not isinstance(card, dict):
            continue
        record_basis = json.dumps(
            {
                "lane": "ruflo",
                "project_key": project_key,
                "run_id": payload.get("run_id"),
                "summary": card.get("summary"),
                "scope": card.get("scope"),
            },
            sort_keys=True,
        )
        records.append(
            {
                "record_id": hashlib.sha256(record_basis.encode("utf-8")).hexdigest()[:16],
                "lane": "ruflo",
                "kind": "handoff_card",
                "signal_type": "handoff_card",
                "project_key": project_key,
                "scope": str(card.get("scope") or "xl"),
                "summary": str(card.get("summary") or "").strip(),
                "items": [str(v) for v in card.get("items") or [] if str(v).strip()],
                "evidence_paths": [str(v) for v in card.get("evidence_paths") or [] if str(v).strip()],
                "keywords": [str(v) for v in card.get("keywords") or [] if str(v).strip()],
                "run_id": str(payload.get("run_id") or ""),
                "updated_at": utc_now(),
            }
        )
    return records


def _cognee_records(payload: dict[str, Any], project_key: str | None) -> list[dict[str, Any]]:
    records: list[dict[str, Any]] = []
    for relation in payload.get("relations") or []:
        if not isinstance(relation, dict):
            continue
        record_basis = json.dumps(
            {
                "lane": "cognee",
                "project_key": project_key,
                "source": relation.get("source"),
                "relation": relation.get("relation"),
                "target": relation.get("target"),
            },
            sort_keys=True,
        )
        records.append(
            {
                "record_id": hashlib.sha256(record_basis.encode("utf-8")).hexdigest()[:16],
                "lane": "cognee",
                "kind": "entity_relation_ingest",
                "signal_type": "entity_relation_ingest",
                "project_key": project_key,
                "source": str(relation.get("source") or "").strip(),
                "relation": str(relation.get("relation") or "").strip(),
                "target": str(relation.get("target") or "").strip(),
                "evidence_paths": [str(v) for v in relation.get("evidence_paths") or [] if str(v).strip()],
                "keywords": [str(v) for v in relation.get("keywords") or [] if str(v).strip()],
                "updated_at": utc_now(),
            }
        )
    return records


def build_lane_records(lane: str, payload: dict[str, Any], project_key: str | None) -> list[dict[str, Any]]:
    if lane == "serena":
        return _serena_records(payload, project_key)
    if lane == "ruflo":
        return _ruflo_records(payload, project_key)
    return _cognee_records(payload, project_key)


def format_read_items(lane: str, ranked: list[dict[str, Any]], top_k: int) -> list[str]:
    if lane == "serena":
        return [
            f"Serena decision: {row.get('summary')} (evidence: {', '.join(row.get('evidence_paths') or [])})"
            for row in ranked
            if row.get("_score", 0) > 0
        ]
    if lane == "ruflo":
        return [
            f"ruflo handoff: {row.get('summary')} (scope: {row.get('scope')})"
            for row in ranked
            if row.get("_score", 0) > 0
        ]
    return [
        f"Cognee relation: {row.get('source')} {row.get('relation')} {row.get('target')}"
        for row in ranked
        if row.get("_score", 0) > 0
    ]


def read_ranked_rows(
    plane_path: Path,
    *,
    lane: str,
    project_key: str | None,
    query: str,
    top_k: int,
) -> list[dict[str, Any]]:
    rows = load_jsonl(plane_path)
    filtered: list[dict[str, Any]] = []
    for row in rows:
        if str(row.get("lane") or "") != lane:
            continue
        if str(row.get("kind") or "") not in LANE_KIND[lane]:
            continue
        if project_key and str(row.get("project_key") or "") != project_key:
            continue
        row = dict(row)
        row["_score"] = score_record(query, row)
        filtered.append(row)
    filtered.sort(key=lambda item: (item["_score"], str(item.get("updated_at") or "")), reverse=True)
    return filtered[:top_k]


def build_capsules(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
    capsules: list[dict[str, Any]] = []
    for row in rows:
        capsules.append(
            {
                "capsule_id": str(row.get("record_id") or ""),
                "owner": LANE_OWNER.get(str(row.get("lane") or ""), "state_store"),
                "lane": str(row.get("lane") or ""),
                "kind": str(row.get("kind") or ""),
                "disclosure_level": "bounded",
                "summary": str(row.get("summary") or row.get("relation") or ""),
                "updated_at": str(row.get("updated_at") or ""),
            }
        )
    return capsules


def write_response(
    response_path: Path,
    *,
    ok: bool,
    status: str,
    lane: str,
    store_path: Path,
    project_key: str | None,
    project_key_source: str | None,
    items: list[str],
    capsules: list[dict[str, Any]],
    suppressed_count: int,
    workspace_plane: dict[str, Any],
    driver_mode: str,
    extra: dict[str, Any] | None = None,
) -> None:
    payload: dict[str, Any] = {
        "ok": ok,
        "status": status,
        "lane": lane,
        "store_path": str(store_path),
        "project_key": project_key,
        "project_key_source": project_key_source,
        "item_count": len(items),
        "items": items,
        "capsule_count": len(capsules),
        "capsules": capsules,
        "suppressed_count": suppressed_count,
        "workspace_memory_plane": workspace_plane,
        "driver_mode": driver_mode,
        "generated_at": utc_now(),
    }
    if extra:
        payload.update(extra)
    write_json(response_path, payload)


def execute(
    *,
    lane: str,
    action: str,
    repo_root: Path,
    payload_path: Path,
    response_path: Path,
    project_key: str | None,
    driver_mode: str,
) -> int:
    payload = load_json(payload_path)
    policy_bundle = load_workspace_memory_policy_bundle(repo_root)
    descriptor = ensure_workspace_descriptor(repo_root, policy_bundle=policy_bundle)
    plane_path = resolve_plane_path(descriptor)
    ensure_parent(plane_path)
    workspace_plane = workspace_memory_projection(descriptor, plane_path)
    project_key_source = str(payload.get("project_key_source") or ("workspace_plane" if project_key else "")) or None

    status = "guarded_no_write"
    items: list[str] = []
    capsules: list[dict[str, Any]] = []
    suppressed_count = 0

    if action == "read":
        if lane == "serena" and not project_key:
            status = "deferred_no_project_key"
        else:
            top_k = int(payload.get("top_k") or 2)
            ranked = read_ranked_rows(
                plane_path,
                lane=lane,
                project_key=project_key,
                query=str(payload.get("task") or ""),
                top_k=top_k,
            )
            items = format_read_items(lane, ranked, top_k)
            status = "backend_read" if items else "backend_read_empty"
            capsules = build_capsules(ranked[: len(items) if items else 0])
    else:
        candidate_records = build_lane_records(lane, payload, project_key)
        if not candidate_records or (lane == "serena" and not project_key):
            status = "guarded_no_write"
        else:
            admitted: list[dict[str, Any]] = []
            for record in candidate_records:
                reason = classify_noise(record)
                if reason:
                    suppressed_count += 1
                    continue
                admitted.append(record)

            if not admitted:
                status = "guarded_noise_suppressed" if suppressed_count > 0 else "guarded_no_write"
            else:
                with PlaneLock(plane_path):
                    rows = load_jsonl(plane_path)
                    rows.extend(admitted)
                    write_jsonl_atomic(plane_path, dedupe_rows(rows))
                capsules = build_capsules(admitted)
                if lane == "serena":
                    items = [f"Persisted Serena decision: {row.get('summary')}" for row in admitted]
                elif lane == "ruflo":
                    items = [f"Persisted ruflo handoff card: {row.get('summary')}" for row in admitted]
                else:
                    items = [
                        f"Persisted Cognee relation: {row.get('source')} {row.get('relation')} {row.get('target')}"
                        for row in admitted
                    ]
                status = "backend_write_with_noise_suppressed" if suppressed_count > 0 else "backend_write"

    write_response(
        response_path,
        ok=status.startswith("backend_"),
        status=status,
        lane=lane,
        store_path=plane_path,
        project_key=project_key,
        project_key_source=project_key_source,
        items=items,
        capsules=capsules,
        suppressed_count=suppressed_count,
        workspace_plane=workspace_plane,
        driver_mode=driver_mode,
    )
    return 0


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--lane", required=True, choices=["serena", "ruflo", "cognee"])
    parser.add_argument("--action", required=True, choices=["read", "write"])
    parser.add_argument("--repo-root", required=True)
    parser.add_argument("--session-root", required=True)
    parser.add_argument("--store-path", required=True)
    parser.add_argument("--payload-path", required=True)
    parser.add_argument("--response-path", required=True)
    parser.add_argument("--project-key")
    parser.add_argument("--driver-mode", default="workspace_broker")
    args = parser.parse_args()

    return execute(
        lane=args.lane,
        action=args.action,
        repo_root=Path(args.repo_root),
        payload_path=Path(args.payload_path),
        response_path=Path(args.response_path),
        project_key=args.project_key,
        driver_mode=str(args.driver_mode),
    )


if __name__ == "__main__":
    raise SystemExit(main())
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