platformforge 0.1.0__py3-none-any.whl

platformforge/cases/ledgers.py

@@ -0,0 +1,174 @@
+"""§64–§68 — false-positive / false-negative ledgers.
+
+A ledger entry is a claim about a *finding* (rule verdict), never a
+repo bug. Every reproducible failure carries a `regression_test`
+pointer that must resolve to a case or test — the gate enforces it.
+Precision is computed only when ground truth exists (§68).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT_CAUSES = (
+    "missing-extractor", "bad-normalization", "bad-identity",
+    "bad-scope", "stale-knowledge", "rule-too-broad", "rule-too-narrow",
+    "graph-gap", "agent-reasoning", "routing-failure",
+    "context-omission", "provider-limitation",
+)
+
+LEDGER_DIR = Path(".platformforge/ledgers")
+
+_REQUIRED = ("finding_id", "rule", "case", "root_cause", "regression_test")
+
+
+@dataclass(frozen=True)
+class FalsePositiveRecord:
+    finding_id: str = ""
+    rule: str = ""
+    case: str = ""
+    why_false: str = ""
+    evidence: tuple[str, ...] = ()
+    root_cause: str = ""
+    fix: str = ""
+    regression_test: str = ""
+    status: str = "open"  # open | fixed | wontfix
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/fp-record/v1",
+                "finding_id": self.finding_id, "rule": self.rule,
+                "case": self.case, "why_false": self.why_false,
+                "evidence": list(self.evidence),
+                "root_cause": self.root_cause, "fix": self.fix,
+                "regression_test": self.regression_test,
+                "status": self.status}
+
+
+@dataclass(frozen=True)
+class FalseNegativeRecord:
+    finding_id: str = ""        # the verdict that should have fired
+    rule: str = ""
+    case: str = ""
+    missed_evidence: str = ""   # what truth was present but unfound
+    root_cause: str = ""
+    fix: str = ""
+    regression_test: str = ""
+    status: str = "open"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/fn-record/v1",
+                "finding_id": self.finding_id, "rule": self.rule,
+                "case": self.case,
+                "missed_evidence": self.missed_evidence,
+                "root_cause": self.root_cause, "fix": self.fix,
+                "regression_test": self.regression_test,
+                "status": self.status}
+
+
+def _errors(d: dict[str, Any], kind: str) -> list[str]:
+    errs = [f"missing field: {k}" for k in _REQUIRED if not d.get(k)]
+    if d.get("root_cause") and d["root_cause"] not in ROOT_CAUSES:
+        errs.append(f"root_cause {d['root_cause']!r} not in {ROOT_CAUSES}")
+    if kind == "fp" and not d.get("why_false"):
+        errs.append("false-positive record without why_false")
+    if kind == "fn" and not d.get("missed_evidence"):
+        errs.append("false-negative record without missed_evidence")
+    return errs
+
+
+def record_errors(d: dict[str, Any], kind: str) -> list[str]:
+    return _errors(d, kind)
+
+
+def load_ledger(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    doc = yaml.safe_load(path.read_text()) or {}
+    return doc.get("records", [])
+
+
+def ledger_report(root: str | Path = LEDGER_DIR) -> dict[str, Any]:
+    """§66 — confirmed/refuted/unresolved + precision when truth exists."""
+    root = Path(root)
+    fp = load_ledger(root / "false-positives.yaml")
+    fn = load_ledger(root / "false-negatives.yaml")
+    errors = []
+    for d in fp:
+        errors += [f"fp:{d.get('finding_id', '?')}: {e}"
+                   for e in _errors(d, "fp")]
+    for d in fn:
+        errors += [f"fn:{d.get('finding_id', '?')}: {e}"
+                   for e in _errors(d, "fn")]
+    confirmed = sum(1 for d in fn if d.get("status") == "fixed") + \
+        sum(1 for d in fp if d.get("status") == "wontfix")
+    refuted = sum(1 for d in fp if d.get("status") == "fixed")
+    unresolved = sum(1 for d in fp + fn if d.get("status") == "open")
+    # §68 — precision only when a ground-truth corpus exists
+    truth = list(Path(".platformforge/cases/golden").glob("*/case.yaml")) + \
+        list(Path(".platformforge/cases/holdout").glob("*/case.yaml"))
+    precision = None
+    if truth:
+        # precision = confirmed findings / (confirmed + refuted findings)
+        denom = len(fp) + len(fn) or None
+        precision = ({"value": None, "records": 0,
+                      "note": "no FP/FN records — precision "
+                              "unmeasurable without findings to grade"}
+                     if denom is None else
+                     {"value": (None if denom < 3
+                                else round(1 - (len(fp) / denom), 4)),
+                      "records": denom,
+                      "note": ("too few records for a meaningful estimate"
+                               if denom < 3 else
+                               "records-based estimate") +
+                              f"; ground truth = {len(truth)} "
+                              "replay cases"})
+    return {"schema": "platformforge/fp-fn-ledger/v1",
+            "false_positives": len(fp), "false_negatives": len(fn),
+            "confirmed": confirmed, "refuted": refuted,
+            "unresolved": unresolved, "precision": precision,
+            "errors": errors,
+            "verdict": "pass" if not errors else "fail"}
+
+
+def validate_ledgers(root: str | Path = LEDGER_DIR) -> dict[str, Any]:
+    """Gate: every record is well-formed AND its regression_test resolves
+    to an existing case.yaml or test file."""
+    root = Path(root)
+    errors = []
+    for kind, f in (("fp", "false-positives.yaml"),
+                    ("fn", "false-negatives.yaml")):
+        for d in load_ledger(root / f):
+            for e in _errors(d, kind):
+                errors.append(f"{kind}:{d.get('finding_id', '?')}: {e}")
+            rt = d.get("regression_test", "")
+            if rt and not _regression_resolves(rt):
+                errors.append(f"{kind}:{d.get('finding_id', '?')}: "
+                              f"regression_test {rt!r} does not resolve")
+    return {"errors": errors, "verdict": "pass" if not errors else "fail"}
+
+
+def _regression_resolves(ref: str) -> bool:
+    """A regression pointer resolves to a case dir, a test file (with an
+    optional ``::test_name`` selector that must exist in the file), or a
+    scenario dir — never to prose."""
+    file_part, _, selector = ref.partition("::")
+    p = Path(file_part)
+    found = p.exists() or any(
+        (Path(base) / file_part).exists()
+        for base in (".platformforge/cases/golden",
+                     ".platformforge/cases/holdout",
+                     "lab/scenarios", "tests"))
+    if not found:
+        return False
+    if selector:
+        target = p if p.is_file() else next(
+            (Path(base) / file_part for base in
+             (".platformforge/cases/golden", ".platformforge/cases/holdout",
+              "lab/scenarios", "tests")
+             if (Path(base) / file_part).is_file()), None)
+        if target is None or f"def {selector}(" not in target.read_text():
+            return False
+    return True

platformforge/cases/replay.py

@@ -0,0 +1,142 @@
+"""§57–§62 — deterministic, offline replay.
+
+Reuses lab/runner analyzer dispatch (fixture → facts → RuleEngine).
+Grading: violated/absent rules + fact kinds vs expected_known_truth.
+Output includes a canonical hash — replay twice, hashes must match.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.cases.casefile import CaseFile, case_errors, discover_cases
+
+SCHEMA = "platformforge/case-replay/v1"
+
+
+def _fixture_dir(c: CaseFile) -> Path:
+    if c.fixture_from:
+        return Path(c.fixture_from) / "fixture"
+    return c.path.parent / "fixture"
+
+
+def _run_case(c: CaseFile) -> dict[str, Any]:
+    """One deterministic pass: analyzers → facts → findings."""
+    from platformforge.lab.runner import CATALOG, _analyzer
+    from platformforge.models import Fact
+    from platformforge.rules import RuleEngine, load_catalog
+
+    fixture = _fixture_dir(c)
+    facts: list[dict[str, Any]] = []
+    errors = []
+    for dom in c.analyzers:
+        try:
+            facts += _analyzer(dom, fixture)["facts"]
+        except Exception as e:  # noqa: BLE001 — analyzer failure is a case error
+            errors.append(f"{dom}: {e}")
+    rule_facts = [Fact.from_dict(f) for f in facts]
+    findings, skipped = RuleEngine(load_catalog(CATALOG)).evaluate(rule_facts)
+    violated = sorted({f.rule_id for f in findings if f.status == "violated"})
+    kinds = sorted({f.kind for f in rule_facts})
+    canonical = json.dumps({"violated": violated, "kinds": kinds,
+                            "errors": sorted(errors)}, sort_keys=True)
+    return {"violated": violated, "kinds": kinds,
+            "errors": errors, "skipped_rules": len(skipped),
+            "hash": hashlib.sha256(canonical.encode()).hexdigest()}
+
+
+def replay_case(c: CaseFile) -> dict[str, Any]:
+    errs = case_errors(c)
+    if errs:
+        return {"case": c.id, "verdict": "unresolved",
+                "errors": errs}
+    exp = c.expected_known_truth
+    t0 = time.time()
+    r1 = _run_case(c)
+    r2 = _run_case(c)  # §62 — determinism: identical canonical result
+    deterministic = r1["hash"] == r2["hash"]
+
+    failures = []
+    want_v = set(exp.get("violated_rules", []))
+    want_absent = set(exp.get("absent_rules", []))
+    want_kinds = set(exp.get("fact_kinds", []))
+    got_v = set(r1["violated"])
+    got_k = set(r1["kinds"])
+    failures += [f"expected violated missing: {r}" for r in sorted(want_v - got_v)]
+    failures += [f"unexpected violation: {r}" for r in sorted(want_absent & got_v)]
+    failures += [f"expected fact kind missing: {k}"
+                 for k in sorted(want_kinds - got_k)]
+    # FP/FN accounting vs declared truth (§65)
+    false_positives = sorted(got_v - want_v)
+    false_negatives = sorted(want_v - got_v)
+    if not deterministic:
+        failures.append("nondeterministic replay: hash mismatch")
+    verdict = "pass" if not failures and not r1["errors"] else "fail"
+    return {"schema": SCHEMA, "case": c.id, "tier": c.tier,
+            "classification": c.classification,
+            "truth_class": c.truth_class,
+            "verdict": verdict, "deterministic": deterministic,
+            "failures": failures, "analyzer_errors": r1["errors"],
+            "violated": r1["violated"], "fact_kinds": r1["kinds"],
+            "false_positives": false_positives,
+            "false_negatives": false_negatives,
+            "result_hash": r1["hash"], "ms": round((time.time() - t0) * 1000, 1)}
+
+
+def replay_all(root: str | Path = ".platformforge/cases",
+               tier: str | None = None) -> dict[str, Any]:
+    cases = discover_cases(root)
+    if tier:
+        cases = [c for c in cases if c.tier == tier]
+    results = [replay_case(c) for c in cases]
+    by_tier: dict[str, dict[str, int]] = {}
+    for r in results:
+        t = by_tier.setdefault(r["tier"], {"pass": 0, "fail": 0,
+                                           "unresolved": 0, "total": 0})
+        t[r["verdict"]] = t.get(r["verdict"], 0) + 1
+        t["total"] += 1
+    failed = [r["case"] for r in results if r["verdict"] == "fail"]
+    corpus_hash = hashlib.sha256(json.dumps(
+        [(r["case"], r.get("result_hash", "")) for r in results],
+        sort_keys=True).encode()).hexdigest()
+    return {"schema": "platformforge/case-corpus/v1",
+            "cases": results, "by_tier": by_tier,
+            "corpus_hash": corpus_hash,
+            "verdict": "pass" if not failed and results else "fail",
+            "failed": failed,
+            "note": "golden = development corpus; holdout = never tuned "
+                    "against — report both, merge neither"}
+
+
+def validate_corpus(root: str | Path = ".platformforge/cases"
+                    ) -> dict[str, Any]:
+    """Structure-only check — every case.yaml satisfies §54."""
+    cases = discover_cases(root)
+    bad = {c.id: case_errors(c) for c in cases}
+    bad = {k: v for k, v in bad.items() if v}
+    return {"cases": len(cases), "invalid": bad,
+            "verdict": "pass" if cases and not bad else "fail"}
+
+
+def write_case_template(path: str | Path) -> None:
+    Path(path).write_text(yaml.safe_dump({
+        "id": "case-<n>",
+        "classification": "fixture-derived",
+        "tier": "golden",
+        "truth_class": "known-bad",
+        "task": "<one-line task the operator ran>",
+        "scope": "<repo/platform slice>",
+        "analyzers": ["k8s"],
+        "fixture_from": "lab/scenarios/<id>",
+        "expected_known_truth": {
+            "violated_rules": [], "absent_rules": [], "fact_kinds": []},
+        "observations": [],
+        "agent_route": {"selected": [], "rejected": [], "fanout": 0},
+        "context_cost": {"input_bytes": 0, "relevant_bytes": 0},
+        "verdict": "unresolved",
+    }, sort_keys=False, allow_unicode=True))

platformforge/cases/routing_audit.py

@@ -0,0 +1,162 @@
+"""§69–§84 — agent dogfooding: per-case route decisions, over/under-
+routing detection, champion/challenger shadow benchmark.
+
+Case-derived signals are inferred honestly: domains = analyzers;
+security_sensitive = security-family analyzers; complexity from domain
+count. The router's own output is the evidence — nothing is assumed.
+"""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from platformforge.cases.casefile import CaseFile, discover_cases
+
+SECURITY_DOMAINS = {"security", "iam", "secrets", "supply", "sbom",
+                    "slsa", "cosign", "policy"}
+# domain keys in routing.DOMAIN_SPECIALIST vocabulary
+_DOMAIN_MAP = {"cloud-aws": "aws", "cloud-gcp": "cloud",
+               "iac": "terraform", "secrets": "security",
+               "iam": "security", "supply": "security",
+               "sbom": "security", "slsa": "security",
+               "cosign": "security", "slo": "sre"}
+
+
+def signal_for_case(c: CaseFile):
+    from platformforge.routing.router import TaskSignal
+    domains = [_DOMAIN_MAP.get(d, d) for d in c.analyzers]
+    return TaskSignal(
+        task_type="analysis",
+        domains=domains,
+        complexity="high" if len(domains) >= 3 else (
+            "medium" if len(domains) == 2 else "low"),
+        security_sensitive=bool(SECURITY_DOMAINS & set(c.analyzers)),
+        evidence_available=True,
+        freshness="current",
+    )
+
+
+def audit_case(c: CaseFile) -> dict[str, Any]:
+    from platformforge.routing.router import route
+    sig = signal_for_case(c)
+    t0 = time.time()
+    d = route(sig)
+    agents = d["agents"]
+    flags: list[str] = []
+    # over-routing (§71): one specialist would do, but a crowd was called
+    if len(c.analyzers) == 1 and len(d["specialists"]) > 2:
+        flags.append("over-routing: single-domain case dispatched "
+                     f"{len(d['specialists'])} specialists")
+    if d["mode"] == "coordinated" and len(c.analyzers) == 1 \
+            and not sig.security_sensitive:
+        flags.append("over-routing: coordinated mode for a "
+                     "single-domain case")
+    # under-routing (§72): security-sensitive without security reviewer
+    if sig.security_sensitive and \
+            "platform-security-reviewer" not in d["reviewers"]:
+        flags.append("under-routing: security-sensitive case has no "
+                     "security reviewer")
+    # every agentic route must end in independent verification
+    if d["mode"] != "deterministic" and not d["verifier"]:
+        flags.append("missing verifier on an agentic route")
+    return {
+        "schema": "platformforge/route-decision/v1",
+        "case": c.id, "tier": c.tier,
+        "router_input": {k: getattr(sig, k)
+                         for k in sig.__dataclass_fields__},
+        "mode": d["mode"], "budget": d["budget"],
+        "selected": agents, "specialists": d["specialists"],
+        "reviewers": d["reviewers"], "coordinator": d["coordinator"],
+        "verifier": d["verifier"],
+        "rejected": sorted(set(_all_candidate_names()) - set(agents)),
+        "fanout": len(agents), "dag_stages": len(d["dag"]),
+        "reasons": d["reasons"], "flags": flags,
+        "ms": round((time.time() - t0) * 1000, 1),
+        "result": "flagged" if flags else "ok"}
+
+
+def _all_candidate_names() -> list[str]:
+    from platformforge.agents.roster import AGENTS
+    return list(AGENTS)
+
+
+def audit_corpus(root: str | Path = ".platformforge/cases",
+                 ledger: bool = True) -> dict[str, Any]:
+    cases = discover_cases(root)
+    decisions = [audit_case(c) for c in cases]
+    flagged = [d["case"] for d in decisions if d["flags"]]
+    by_mode: dict[str, int] = {}
+    fanout = 0
+    for d in decisions:
+        by_mode[d["mode"]] = by_mode.get(d["mode"], 0) + 1
+        fanout += d["fanout"]
+    out = {"schema": "platformforge/routing-audit/v1",
+           "cases": len(decisions), "decisions": decisions,
+           "by_mode": by_mode,
+           "avg_fanout": round(fanout / len(decisions), 2) if decisions else 0,
+           "flagged": flagged,
+           "verdict": "pass" if not flagged else "flagged",
+           "note": "flags are review signals, not auto-fixes — the "
+                   "router is not self-modified (§76)"}
+    if ledger:
+        p = Path(".platformforge/ledger")
+        p.mkdir(parents=True, exist_ok=True)
+        with open(p / "routing-decisions.jsonl", "w") as fh:
+            for d in decisions:
+                fh.write(json.dumps(d, default=str) + "\n")
+        out["ledger"] = str(p / "routing-decisions.jsonl")
+    return out
+
+
+def champion_challenger(root: str | Path = ".platformforge/cases",
+                        challenger: str | Path | None = None
+                        ) -> dict[str, Any]:
+    """§77 — champion = rules/catalog/routing.yaml; challenger = an
+    alternate table run in offline shadow mode. Scores per case:
+    correctness (right specialist for the domains), evidence recall,
+    agent count, projected cost, latency, tool calls (router-side).
+    Without a challenger file this reports champion-only shadow."""
+    from platformforge.routing.router import route
+
+    cases = discover_cases(root)
+    rows = []
+    for c in cases:
+        sig = signal_for_case(c)
+        champ = route(sig)
+        row = {"case": c.id, "champion": _score(c, sig, champ)}
+        if challenger and Path(challenger).is_file():
+            chal = route(sig, routes_path=challenger)
+            row["challenger"] = _score(c, sig, chal)
+            row["delta"] = _delta(row["champion"], row["challenger"])
+        rows.append(row)
+    return {"schema": "platformforge/routing-bench/v1",
+            "cases": rows, "challenger": str(challenger) if challenger
+            else "none — champion-only shadow",
+            "note": "challenger never activates silently — routing "
+                    "changes require review (§77)"}
+
+
+def _score(c: CaseFile, sig, d: dict[str, Any]) -> dict[str, Any]:
+    """Offline score — correctness = every case domain has its
+    specialist selected; recall = specialists / needed."""
+    from platformforge.routing.router import DOMAIN_SPECIALIST
+    needed = {DOMAIN_SPECIALIST[dom] for dom in
+              {_DOMAIN_MAP.get(a, a) for a in c.analyzers}
+              if dom in DOMAIN_SPECIALIST}
+    selected = set(d["specialists"])
+    recall = len(needed & selected) / len(needed) if needed else 1.0
+    return {"mode": d["mode"], "agents": len(d["agents"]),
+            "specialists": len(d["specialists"]),
+            "correctness": sorted(needed <= selected and ["full"]
+                                  or [s for s in needed - selected]),
+            "evidence_recall": round(recall, 3),
+            "budget": d["budget"], "dag_stages": len(d["dag"])}
+
+
+def _delta(champ: dict, chal: dict) -> dict[str, Any]:
+    return {"agents": chal["agents"] - champ["agents"],
+            "evidence_recall": round(chal["evidence_recall"]
+                                     - champ["evidence_recall"], 3),
+            "mode": f"{champ['mode']}→{chal['mode']}"}

platformforge/caveman/__init__.py

@@ -0,0 +1,11 @@
+"""Caveman — first-party output compression.
+
+Reduce language, never substance. Protected spans (commands, paths, ids,
+exceptions, warnings, IAM actions, ARNs, URLs, evidence, fact/rule ids,
+numbers, units, versions) are never compressed away. Every compression emits
+a receipt with before/after measurements.
+"""
+
+from platformforge.caveman.compress import CompressionReceipt, compress
+
+__all__ = ["CompressionReceipt", "compress"]

platformforge/caveman/compress.py

@@ -0,0 +1,156 @@
+"""Output compression with protected spans + receipts.
+
+Modes: off | lite | full | auto.
+  off   — passthrough
+  lite  — drop filler, keep sentences & structure
+  full  — aggressive: terse fragments, bullets over prose
+  auto  — decide by context risk (info→full, architecture→lite,
+          incident/destructive→prose with explicit warnings)
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from platformforge.tokensave.estimate import estimate_tokens
+
+PROTECTED_PATTERNS = [
+    r"\b(error|warning|exception|denied|failed|fatal|panic)[:\s][^\n]*",
+    r"PF-[A-Z0-9-]+-\d+",                                 # fact/rule ids
+    r"artifact://sha256/[0-9a-f]{64}",
+    r"arn:aws:[\w\-:]+/[^\s]*",                           # ARNs
+    r"https?://[^\s)\]]+",
+    r"[\w./\-]+/[\w./\-]+",                               # paths
+    r"\bv?\d+\.\d+(?:\.\d+)?\b",                          # versions
+    r"\b\d+(?:\.\d+)?\s*(?:ms|s|MB|GB|TB|%|Mi|Gi|m)?\b",
+    r"`[^`]+`",                                           # inline code/commands
+    r"\b(allow|deny|delete|create|update|iam:[\w*]+|s3:[\w*]+)\b",
+    r"AKIA[0-9A-Z]{16}|REDACTED:[\w]+:[0-9a-f]{8}",
+]
+
+FILLER = re.compile(
+    r"(?i)\b(certainly|basically|actually|essentially|in conclusion|"
+    r"it is important to note that|please note that|as you can see|"
+    r"as mentioned (earlier|above)|in order to|due to the fact that|"
+    r"it should be noted|the fact that)\b[,]?")
+WORDY = [
+    (re.compile(r"(?i)\bis able to\b"), "can"),
+    (re.compile(r"(?i)\bin the event that\b"), "if"),
+    (re.compile(r"(?i)\ba large number of\b"), "many"),
+    (re.compile(r"(?i)\bat this point in time\b"), "now"),
+    (re.compile(r"(?i)\bhas the ability to\b"), "can"),
+    (re.compile(r"(?i)\bprior to\b"), "before"),
+    (re.compile(r"(?i)\bin close proximity to\b"), "near"),
+    (re.compile(r"(?i)\bdo not hesitate to\b"), ""),
+]
+SENT_SPLIT = re.compile(r"(?<=[.!?])\s+")
+RISKY = re.compile(r"(?i)\b(destroy|delete|drop|production|incident|sev[0-9]|"
+                   r"irreversible|destructive|security breach|outage)\b")
+DECISION = re.compile(r"(?i)\b(architecture|design decision|tradeoff|trade-off|"
+                      r"alternatives? considered|rationale)\b")
+
+
+@dataclass
+class CompressionReceipt:
+    mode: str
+    before_chars: int
+    after_chars: int
+    before_tokens_est: int
+    after_tokens_est: int
+    compression_ratio: float
+    protected_spans: int
+    detail: str = ""
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+_COMBINED = re.compile(
+    "|".join(f"(?:{p})" for p in PROTECTED_PATTERNS), re.IGNORECASE)
+
+
+def _protect(text: str) -> tuple[str, list[str]]:
+    """Replace protected spans with placeholders → compress prose only.
+    Single alternation pass: a placeholder can never match a later pattern."""
+    spans: list[str] = []
+
+    def stash(m: re.Match) -> str:
+        spans.append(m.group(0))
+        return f"\x00{len(spans) - 1}\x00"
+
+    return _COMBINED.sub(stash, text), spans
+
+
+def _restore(text: str, spans: list[str]) -> str:
+    return re.sub(r"\x00(\d+)\x00", lambda m: spans[int(m.group(1))], text)
+
+
+def _lite(text: str) -> str:
+    text = FILLER.sub("", text)
+    for rx, rep in WORDY:
+        text = rx.sub(rep, text)
+    text = re.sub(r"[ \t]{2,}", " ", text)
+    return re.sub(r"\n{3,}", "\n\n", text).strip()
+
+
+def _full(text: str) -> str:
+    text = _lite(text)
+    out = []
+    for sent in SENT_SPLIT.split(text):
+        s = sent.strip()
+        if not s:
+            continue
+        # drop connective-only sentences, keep payload sentences
+        if len(s) < 4:
+            continue
+        if re.match(r"(?i)^(however|moreover|furthermore|additionally|also|"
+                    r"in addition|note that|it is worth)\b[,]?\s*", s):
+            s = re.sub(r"(?i)^(however|moreover|furthermore|additionally|also|"
+                       r"in addition|note that|it is worth)\b[,]?\s*", "", s)
+        out.append(s)
+    return "\n".join(out)
+
+
+def choose_mode(text: str, context_risk: str = "normal") -> str:
+    if context_risk in ("security-incident", "destructive"):
+        return "off"    # prose + explicit warnings — no compression on risk
+    if RISKY.search(text):
+        return "lite"   # keep signal fully readable
+    if DECISION.search(text):
+        return "lite"
+    return "full"
+
+
+def compress(text: str, mode: str = "lite",
+             context_risk: str = "normal") -> tuple[str, CompressionReceipt]:
+    if mode not in ("off", "lite", "full", "auto"):
+        raise ValueError(f"unknown mode {mode!r}")
+    # §16 — secrets never cross the compression boundary, mode "off"
+    # included. Redact before anything else; the receipt records counts.
+    from platformforge.core.redaction import redact_text_report, redaction_receipt
+    text, redactions = redact_text_report(text)
+    actual = choose_mode(text, context_risk) if mode == "auto" else mode
+    before_chars = len(text)
+    before_tokens = estimate_tokens(text)
+
+    protected, spans = _protect(text)
+    if actual == "off":
+        out = text
+    elif actual == "lite":
+        out = _lite(protected)
+    else:
+        out = _full(protected)
+    out = _restore(out, spans)
+
+    rc = CompressionReceipt(
+        mode=actual, before_chars=before_chars, after_chars=len(out),
+        before_tokens_est=before_tokens, after_tokens_est=estimate_tokens(out),
+        compression_ratio=(1 - len(out) / before_chars) if before_chars else 0.0,
+        protected_spans=len(spans),
+    )
+    if redactions:
+        rc.extra["redaction"] = redaction_receipt("caveman", redactions)
+    return out, rc

platformforge/cicd/__init__.py

@@ -0,0 +1,16 @@
+"""GitOps & CI/CD analysis: ArgoCD, Flux, GitHub Actions, GitLab CI,
+Dockerfile, Backstage catalog entities."""
+
+from platformforge.cicd.backstage import analyze_backstage
+from platformforge.cicd.dockerfile import analyze_dockerfile
+from platformforge.cicd.github_actions import analyze_gha
+from platformforge.cicd.gitlab_ci import analyze_gitlab_ci
+from platformforge.cicd.gitops import analyze_gitops
+
+__all__ = [
+           "analyze_backstage",
+           "analyze_dockerfile",
+           "analyze_gha",
+           "analyze_gitlab_ci",
+           "analyze_gitops",
+]