@event4u/agent-config 2.13.0 → 2.15.0

package/scripts/ai_council/consensus.py

@@ -57,15 +57,42 @@ class FindingScore:
     reason: str
 
 
+def evidence_quality(mean_score: float) -> str:
+    """Classify mean score into a single-letter evidence-quality bucket.
+
+    H (high)   — mean ≥ 8.0; member agreement ran high.
+    M (medium) — 6.0 ≤ mean < 8.0; majority support, mixed conviction.
+    L (low)    — mean < 6.0 or no scorers; weak or contested.
+
+    Used by Phase 9 to surface a quick "how much did members back this"
+    signal next to the raw consensus_strength number.
+    """
+    if mean_score >= 8.0:
+        return "H"
+    if mean_score >= 6.0:
+        return "M"
+    return "L"
+
+
 @dataclass(frozen=True)
 class ConsensusMetadata:
-    """Aggregate consensus stats for a single finding."""
+    """Aggregate consensus stats for a single finding.
+
+    Phase 9 adds ``concur_count``, ``dissent_reasons`` (per-scorer
+    one-line rationales for disagreement), and ``evidence_quality``
+    (H/M/L bucket of the mean score) so the renderer can emit
+    "N/M members concur; X dissented citing …; mean evidence-quality H"
+    without needing the underlying FindingScore list.
+    """
 
     finding_id: str
     consensus_strength: float  # 0..1
     dissent_count: int
     scorers: tuple[str, ...]
     mean_score: float
+    concur_count: int = 0
+    dissent_reasons: tuple[tuple[str, str], ...] = ()  # (scorer, reason)
+    evidence_quality: str = "L"
 
 
 @dataclass(frozen=True)
@@ -103,17 +130,28 @@ def aggregate_scores(
             out[fid] = ConsensusMetadata(
                 finding_id=fid, consensus_strength=0.0,
                 dissent_count=0, scorers=(), mean_score=0.0,
+                concur_count=0, dissent_reasons=(), evidence_quality="L",
             )
             continue
         mean = sum(s.score for s in fs) / len(fs)
         agree_rate = sum(1 for s in fs if s.agree) / len(fs)
         strength = (mean / 10.0) * agree_rate
         dissent = sum(1 for s in fs if not s.agree)
+        concur = sum(1 for s in fs if s.agree)
         scorers = tuple(s.scorer for s in fs)
+        # Phase 9 — collect (scorer, reason) pairs for dissenters only,
+        # in scoring order, so the renderer surfaces who pushed back
+        # and why without re-walking the FindingScore list.
+        dissent_reasons = tuple(
+            (s.scorer, s.reason) for s in fs if not s.agree
+        )
+        mean_rounded = round(mean, 2)
         out[fid] = ConsensusMetadata(
             finding_id=fid, consensus_strength=round(strength, 3),
             dissent_count=dissent, scorers=scorers,
-            mean_score=round(mean, 2),
+            mean_score=mean_rounded,
+            concur_count=concur, dissent_reasons=dissent_reasons,
+            evidence_quality=evidence_quality(mean_rounded),
         )
     return out
 
@@ -143,6 +181,7 @@ def bucket_by_threshold(
             m = ConsensusMetadata(
                 finding_id=f.id, consensus_strength=0.0,
                 dissent_count=0, scorers=(), mean_score=0.0,
+                concur_count=0, dissent_reasons=(), evidence_quality="L",
             )
         if m.consensus_strength > strong:
             bucket.strong.append((f, m))

package/scripts/ai_council/events_log.py

@@ -0,0 +1,137 @@
+"""Persistent council events log (step-8 phase 3).
+
+Single-function module that appends one JSON line per council event to
+``<project_root>/agents/council-events.log``. Schema v1 carries the
+minimum needed to answer the "why did the council skip / block this?"
+question at retro time without leaking prompt content.
+
+Privacy floor:
+    ``original_ask`` is never written verbatim — the caller passes the
+    raw string, and :func:`append_event` writes ``sha256(value)[:12]``
+    as ``original_ask_hash``. Mirrors the privacy floor in
+    ``agents/low-impact-decisions.md``.
+
+Kill-switch:
+    ``AGENT_CONFIG_NO_EVENTS_LOG=1`` short-circuits :func:`append_event`
+    to a no-op. Mirrors Step 7's ``AGENT_CONFIG_LEGACY_ANCHOR=1``
+    pattern. Tested via env-var override; the agent never reads or
+    parses the log itself.
+
+See: ``agents/roadmaps/step-8-quota-necessity-transparency.md`` (D3,
+D5) and ``docs/contracts/ai-council-config.md``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+SCHEMA_VERSION = 1
+
+EventAction = Literal["proceed", "skip_necessity", "block_quota"]
+
+_VALID_ACTIONS: frozenset[str] = frozenset(
+    {"proceed", "skip_necessity", "block_quota"},
+)
+
+#: Environment-variable kill-switch. Truthy values disable all writes;
+#: the function silently returns. Designed for CI / sandboxed runs and
+#: privacy-conscious power users.
+_KILL_SWITCH_ENV = "AGENT_CONFIG_NO_EVENTS_LOG"
+
+#: Default log path, resolved relative to the package root (two levels
+#: above ``scripts/ai_council/``). Callers can override via
+#: ``log_path=`` for tests.
+_DEFAULT_LOG_PATH = (
+    Path(__file__).resolve().parents[2] / "agents" / "council-events.log"
+)
+
+
+def _hash_original_ask(original_ask: str) -> str:
+    """Return sha256(original_ask)[:12] — the privacy-floor hash.
+
+    Empty / missing input maps to a stable sentinel so the schema field
+    is always populated.
+    """
+    if not original_ask:
+        return "0" * 12
+    return hashlib.sha256(
+        original_ask.encode("utf-8", errors="replace"),
+    ).hexdigest()[:12]
+
+
+def _kill_switch_active() -> bool:
+    value = os.environ.get(_KILL_SWITCH_ENV, "")
+    return value not in ("", "0", "false", "False")
+
+
+def append_event(
+    event: dict[str, Any], *, log_path: Path | None = None,
+) -> bool:
+    """Append a single JSON event line to the council events log.
+
+    Args:
+        event: Mapping with the v1 schema fields. Required keys:
+            ``lens``, ``invocation``, ``action``, ``verdict``,
+            ``provider_caps``, ``original_ask``. The function injects
+            ``schema_version``, ``ts_utc``, and replaces
+            ``original_ask`` with ``original_ask_hash``. Unknown keys
+            pass through verbatim — callers should not abuse this for
+            free-form payloads (privacy floor).
+        log_path: Override for tests. Defaults to
+            ``<project_root>/agents/council-events.log``.
+
+    Returns:
+        ``True`` when a line was written; ``False`` when the kill-switch
+        suppressed the write. Never raises on missing parent dir — the
+        function creates it on demand.
+
+    Raises:
+        ValueError: ``action`` not in :data:`_VALID_ACTIONS`.
+    """
+    if _kill_switch_active():
+        return False
+
+    action = event.get("action")
+    if action not in _VALID_ACTIONS:
+        raise ValueError(
+            f"events_log: action={action!r} not in "
+            f"{sorted(_VALID_ACTIONS)}.",
+        )
+
+    raw_ask = event.pop("original_ask", "") if "original_ask" in event else ""
+    record = {
+        "schema_version": SCHEMA_VERSION,
+        "ts_utc": datetime.now(timezone.utc).isoformat(
+            timespec="seconds",
+        ).replace("+00:00", "Z"),
+        "lens": event.get("lens", ""),
+        "invocation": event.get("invocation", ""),
+        "action": action,
+        "verdict": event.get("verdict", ""),
+        "provider_caps": event.get("provider_caps", {}),
+        "original_ask_hash": _hash_original_ask(raw_ask),
+    }
+    # Pass-through for any caller-supplied diagnostic fields that are
+    # not in the schema-v1 reserved set (e.g. `category`, `rationale`).
+    # The schema-v1 fields above always win on collision.
+    reserved = set(record) | {"original_ask"}
+    for k, v in event.items():
+        if k not in reserved:
+            record[k] = v
+
+    target = Path(log_path) if log_path is not None else _DEFAULT_LOG_PATH
+    target.parent.mkdir(parents=True, exist_ok=True)
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":"))
+    with target.open("a", encoding="utf-8") as fh:
+        fh.write(line + "\n")
+    return True
+
+
+def default_log_path() -> Path:
+    """Return the canonical events-log path (callers / tests)."""
+    return _DEFAULT_LOG_PATH

package/scripts/ai_council/learn_low_impact_preview.py

@@ -0,0 +1,252 @@
+"""Preview builder for ``/memory learn-low-impact`` (step-9 Phase 7).
+
+Default invocation is ``--preview``: build a structured plan describing
+which Validated entries would be upstreamed to the package seed without
+opening a PR. ``--apply`` (handled by the agent, not this module) is the
+explicit opt-in that triggers the actual upstream-contribute PR flow.
+
+The module is import-light by design — pure parsing + redaction + diff
+rendering. PR creation lives in the ``upstream-contribute`` skill;
+this module only hands the agent the material to surface.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+from scripts.ai_council.low_impact_corpus import (
+    CorpusEntry,
+    parse_corpus_strict,
+)
+from scripts.ai_council.redact_low_impact_entry import (
+    RedactionViolation,
+    redact_low_impact_entry,
+)
+
+
+_PROVENANCE_RE = re.compile(r"^last-upstreamed:\s*([0-9a-f]{6,40}|0+)\s*$",
+                            re.IGNORECASE | re.MULTILINE)
+
+
+@dataclass(frozen=True)
+class PreviewEntry:
+    """One Validated bullet that would be upstreamed."""
+    phrase: str
+    normalised: str
+    line_no: int
+
+
+@dataclass(frozen=True)
+class RefusedEntry:
+    """A Validated bullet the redactor refused — never upstreams."""
+    phrase: str
+    line_no: int
+    violations: tuple[RedactionViolation, ...]
+
+    def reason(self) -> str:
+        return "; ".join(f"{v.category}: {v.snippet}" for v in self.violations)
+
+
+@dataclass(frozen=True)
+class LearnLowImpactPreview:
+    """Structured preview for ``/memory learn-low-impact --preview``.
+
+    Consumed by the agent which renders the human-facing preview block,
+    then waits for explicit ``--apply`` before invoking
+    :doc:`upstream-contribute </skills/upstream-contribute/SKILL>`.
+    """
+    promoted: tuple[PreviewEntry, ...]
+    refused: tuple[RefusedEntry, ...]
+    already_seeded: tuple[str, ...]
+    last_upstreamed_sha: str
+    seed_path: str
+    corpus_path: str
+    repo_slug: str = ""
+    warnings: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def has_work(self) -> bool:
+        return bool(self.promoted) or bool(self.refused)
+
+    @property
+    def would_open_pr(self) -> bool:
+        """True when ``--apply`` would actually open a PR.
+
+        Iron Law: any redactor refusal blocks the PR — the author must
+        rephrase or drop the offending entry locally and re-run.
+        """
+        return bool(self.promoted) and not self.refused
+
+    def render(self) -> str:
+        """Human-readable preview block.
+
+        Mirrors the rendering convention from ``/memory mine-session``:
+        a leading title line, then bucketed entries.
+        """
+        lines: list[str] = []
+        lines.append(
+            "## learn-low-impact preview"
+            + (f" — repo={self.repo_slug}" if self.repo_slug else "")
+        )
+        lines.append(f"last-upstreamed: {self.last_upstreamed_sha}")
+        lines.append(f"seed: {self.seed_path}")
+        lines.append("")
+        if self.promoted:
+            lines.append(f"### Promoted ({len(self.promoted)})")
+            for e in self.promoted:
+                lines.append(f"- \"{e.phrase}\"  (line {e.line_no})")
+            lines.append("")
+        if self.refused:
+            lines.append(f"### Refused ({len(self.refused)}) — redactor blocked")
+            for r in self.refused:
+                lines.append(
+                    f"- \"{r.phrase}\"  (line {r.line_no}) — {r.reason()}"
+                )
+            lines.append("")
+        if self.already_seeded:
+            lines.append(f"### Already seeded ({len(self.already_seeded)})")
+            for phrase in self.already_seeded:
+                lines.append(f"- \"{phrase}\"")
+            lines.append("")
+        if not self.has_work:
+            lines.append("> No new validated entries to upstream.")
+            lines.append("")
+        if self.refused:
+            lines.append(
+                "> Refusals block the PR. Rephrase the entries locally"
+                " (or drop them) and re-run."
+            )
+        elif self.promoted:
+            lines.append(
+                "> Re-run with `--apply` to open the draft PR via"
+                " `upstream-contribute`."
+            )
+        return "\n".join(lines).rstrip() + "\n"
+
+    def render_diff(self) -> str:
+        """Source-project-stripped diff that ``--apply`` would propose.
+
+        Emits unified-diff-style ``+`` lines for each promoted phrase
+        under the seed file's ``## Validated`` section. The agent uses
+        this as the ``upstream-contribute`` patch body.
+        """
+        if not self.promoted:
+            return ""
+        lines = [f"--- {self.seed_path}", f"+++ {self.seed_path}"]
+        for e in self.promoted:
+            lines.append(f'+- "{e.phrase}"')
+        return "\n".join(lines) + "\n"
+
+    def render_pr_body(self) -> str:
+        """Draft PR body for the upstream contribute flow."""
+        n = len(self.promoted)
+        slug = self.repo_slug or "<repo-slug>"
+        title = f"feat(low-impact-seed): add {n} validated entries from {slug}"
+        body_lines: list[str] = [
+            f"# {title}",
+            "",
+            "Upstream from `/memory learn-low-impact --apply`.",
+            "",
+            "## Entries",
+            "",
+        ]
+        for e in self.promoted:
+            body_lines.append(f'- "{e.phrase}"')
+        body_lines.append("")
+        body_lines.append(
+            f"Provenance baseline: `{self.last_upstreamed_sha}`."
+        )
+        body_lines.append("")
+        body_lines.append(
+            "Per `low-impact-corpus-privacy-floor`, every entry above"
+            " cleared the redactor on intake and again at upstream."
+        )
+        return "\n".join(body_lines) + "\n"
+
+
+def _read_seed_phrases(seed_path: Path) -> set[str]:
+    """Return the set of normalised phrases already in the seed file.
+
+    Missing seed file is not an error — it returns an empty set so the
+    first-ever upstream PR can seed the whole corpus. Reuses the
+    strict parser so the seed itself is contract-validated.
+    """
+    if not seed_path.exists():
+        return set()
+    result = parse_corpus_strict(seed_path)
+    return {e.normalised for e in result.validated}
+
+
+def _read_provenance(corpus_path: Path) -> str:
+    if not corpus_path.exists():
+        return "0" * 40
+    text = corpus_path.read_text(encoding="utf-8")
+    m = _PROVENANCE_RE.search(text)
+    return m.group(1).lower() if m else "0" * 40
+
+
+def build_preview(
+    corpus_path: "object",
+    seed_path: "object",
+    *,
+    repo_root: str | None = None,
+    private_domains: Iterable[str] = (),
+    customer_names: Iterable[str] = (),
+    sql_identifiers: Iterable[str] = (),
+    repo_slug: str = "",
+) -> LearnLowImpactPreview:
+    """Build the preview plan without performing any PR side-effects.
+
+    Steps mirror the command doc:
+
+    1. Parse the local corpus (strict — drift surfaces as ParseError).
+       Step-10: the preview deliberately stays on the Markdown parser
+       (not the YAML lockfile) because it runs *before* ``task sync``
+       rebuilds the lockfile from a user's local corpus edits.
+    2. Diff Validated entries against the upstream seed.
+    3. Run the redactor on every candidate.
+    4. Bucket into promoted / refused / already-seeded.
+    """
+    corpus_p = Path(str(corpus_path))
+    seed_p = Path(str(seed_path))
+    parsed = parse_corpus_strict(corpus_p)
+    seeded = _read_seed_phrases(seed_p)
+    promoted: list[PreviewEntry] = []
+    refused: list[RefusedEntry] = []
+    already: list[str] = []
+    for entry in parsed.validated:
+        if entry.normalised in seeded:
+            already.append(entry.phrase)
+            continue
+        result = redact_low_impact_entry(
+            entry.phrase,
+            repo_root=repo_root,
+            private_domains=private_domains,
+            customer_names=customer_names,
+            sql_identifiers=sql_identifiers,
+        )
+        if result.ok:
+            promoted.append(PreviewEntry(
+                phrase=entry.phrase,
+                normalised=entry.normalised,
+                line_no=entry.line_no,
+            ))
+        else:
+            refused.append(RefusedEntry(
+                phrase=entry.phrase,
+                line_no=entry.line_no,
+                violations=result.violations,
+            ))
+    return LearnLowImpactPreview(
+        promoted=tuple(promoted),
+        refused=tuple(refused),
+        already_seeded=tuple(already),
+        last_upstreamed_sha=_read_provenance(corpus_p),
+        seed_path=str(seed_p),
+        corpus_path=str(corpus_p),
+        repo_slug=repo_slug,
+        warnings=parsed.warnings,
+    )