@event4u/agent-config 2.11.0 → 2.13.0

package/scripts/ai_council/prompts.py

@@ -122,6 +122,42 @@ MUST:
    evidence in the artefact).
 """.strip()
 
+ANALYSIS_MODE = """\
+The artefact is a local analysis output (from a project analyzer,
+audit script, or codebase scan). Critique the **analysis itself**, not
+the underlying codebase. You MUST:
+1. Flag findings that are restated under different headings —
+   deduplicate aggressively. The downstream consumer wants a unique
+   Top-N, not a long list with overlap.
+2. Score the evidence quality of each finding: confirmed (the
+   analysis cites file:line / metric), inferred (plausible from
+   stated context), or speculative (no citation, vibes-only).
+   Speculative findings must be called out by name.
+3. Identify findings that are roadmap-ready (concrete enough to land
+   as a phase step) vs ones that need a discovery loop first.
+4. Propose 3–5 follow-up actions ranked by leverage — what the next
+   roadmap should attack first. Cite the supporting finding(s) by id
+   or heading.
+End with: a Top-N consensus list (one bullet per finding the
+analysis surfaces) plus a single sentence on the strongest blind
+spot the analysis itself has.
+""".strip()
+
+
+DEBATE_MODE = """\
+The artefact is the topic of a structured multi-round debate. You are
+one of several independent reviewers. Round-specific instructions:
+1. Round 1 — state your strongest, most defensible position on the
+   topic. Argue from evidence and first principles. Do not hedge.
+2. Round 2+ — read the anonymised positions from the previous round.
+   Identify the SINGLE strongest opposing position and write a
+   rebuttal addressed at its strongest steel-manned form. Your task
+   is to find the load-bearing flaw the opposing reviewer missed —
+   do NOT search for common ground.
+End each round with: a one-line position summary and the single
+piece of evidence that would change your mind.
+""".strip()
+
 
 _MODE_TABLE = {
     "prompt": PROMPT_MODE,
@@ -131,9 +167,185 @@ _MODE_TABLE = {
     "pr": PR_MODE,
     "design": DESIGN_MODE,
     "optimize": OPTIMIZE_MODE,
+    "analysis": ANALYSIS_MODE,
+    "debate": DEBATE_MODE,
+}
+
+
+# ── Consensus-scoring prompts (Phase 4 / F3) ──────────────────────────
+#
+# Two-step extraction + scoring round used by the analysis lens. The
+# extraction pass asks each member to surface its own top findings in
+# a strict JSON shape; the scoring pass asks each member to rate
+# anonymised findings produced by the *other* members.
+#
+# Iron Law of Neutrality applies to both: the extraction prompt never
+# names other reviewers, and the scoring prompt strips the source
+# author by using `Finding-A` / `Finding-B` labels (see
+# `consensus.anonymize_findings`).
+
+FINDING_EXTRACTION_PROMPT = """\
+You have just produced an analysis. Re-emit your top findings as a
+strict JSON array suitable for downstream tooling. Each item MUST
+have:
+
+    {"id": "<short-slug>", "text": "<one-sentence finding>"}
+
+Rules:
+- 3-7 findings, ordered by importance (most important first).
+- `id` is a 1-3 word kebab-case slug, unique within your array.
+- `text` is a single sentence, no markdown, no reviewer self-reference.
+- Wrap the array in a ```json``` fenced block. No commentary outside it.
+""".strip()
+
+FINDING_SCORING_PROMPT = """\
+Below are findings from other independent reviewers, presented with
+neutral labels (Finding-A, Finding-B, …). Score each one on its
+merits. You MUST emit a strict JSON array, one entry per finding,
+in this shape:
+
+    {"finding_id": "Finding-A", "score": 1-10, "agree": true|false,
+     "reason": "<one-sentence justification>"}
+
+Rules:
+- `score` is an integer 1 (weak / irrelevant) to 10 (load-bearing /
+  must-address).
+- `agree=true` means you would surface this same finding yourself;
+  `agree=false` means you think it is wrong, overstated, or off-topic.
+- `reason` is a single sentence, no markdown.
+- Wrap the array in a ```json``` fenced block. No commentary outside it.
+
+You may not see your own findings in the list — that is by design.
+""".strip()
+
+
+# ── Synthesis templates (Phase 3 / F2) ────────────────────────────────
+#
+# Lens-aware synthesis prompts. Each entry maps a lens key onto the
+# block the host agent should produce when summarising member responses.
+# R4 Q4 split: decision lenses get a Karpathy-structured template;
+# creative lenses (design / optimize) stay open-ended prose (empty
+# string → renderer falls back to the bare "Convergence / Divergence"
+# slot). Input modes (prompt / roadmap / diff / files) map onto the
+# `default` decision template via `synthesis_template()`.
+
+DEFAULT_SYNTHESIS = """\
+Summarise the council using the structured shape below. Be terse,
+cite reviewers by label, and refuse to invent agreement that is not
+in the responses.
+
+### Agreement
+Points that two or more reviewers converged on, each as a single line.
+
+### Clashes
+Points where reviewers disagreed. State both sides with a one-line
+reviewer-label citation per side.
+
+### Blind spots
+Items that none of the reviewers raised but that the artefact's
+context suggests are load-bearing. Maximum three. Mark each as
+`needs-verification` when the host agent inferred it rather than
+read it directly from a response.
+
+### Recommendation
+A single sentence: which course the host agent should advise the
+user to take, grounded in the strongest converged point.
+
+### Next step
+One concrete next action the user can take in their current turn.
+""".strip()
+
+PR_SYNTHESIS = """\
+Summarise the council with the PR-review shape below.
+
+### Consensus
+Findings where two or more reviewers agreed, each one a single line.
+
+### Conflicts
+Findings where reviewers disagreed. State both sides with reviewer
+labels; do not pick a winner here — that lives in the recommendation.
+
+### Must-fix before merge
+Items at least one reviewer marked `REQUEST_CHANGES` or `REJECT`
+and the host agent confirms are load-bearing. Maximum five.
+
+### Recommendation
+APPROVE / REQUEST_CHANGES / REJECT and a single sentence justifying
+the verdict, anchored on the strongest consensus or must-fix line.
+""".strip()
+
+ANALYSIS_SYNTHESIS = """\
+Summarise the council with the analysis-lens shape below.
+
+### Top-10 by consensus
+Findings ranked by how many reviewers surfaced them. Format each
+line as: `N. <finding> — cited by <reviewer labels> · evidence:
+confirmed | inferred | speculative · roadmap-ready: yes | needs-discovery`.
+Stop at ten or when only single-reviewer items remain, whichever
+comes first.
+
+### Supporting
+Findings that one reviewer raised and at least one other treated as
+plausible but did not independently surface. One line each, same
+metadata shape as Top-10.
+
+### Outliers
+Single-reviewer findings the others did not engage with. Keep them
+— they are signal for a future deeper analysis pass — but mark each
+as `unverified-by-council`.
+""".strip()
+
+# Creative lenses — open-ended prose, no template. The renderer keeps
+# the bare "Convergence / Divergence" slot so the host agent can write
+# free-form synthesis.
+_CREATIVE_PASSTHROUGH = ""
+
+_SYNTHESIS_TABLE = {
+    "default": DEFAULT_SYNTHESIS,
+    "pr": PR_SYNTHESIS,
+    "analysis": ANALYSIS_SYNTHESIS,
+    "design": _CREATIVE_PASSTHROUGH,
+    "optimize": _CREATIVE_PASSTHROUGH,
+}
+
+# Input modes inherit the `default` decision template. Lens overrides
+# (`pr`/`design`/`optimize`/`analysis`) pick their own row.
+_INPUT_MODE_TO_SYNTHESIS_KEY = {
+    "prompt": "default",
+    "roadmap": "default",
+    "diff": "default",
+    "files": "default",
 }
 
 
+def synthesis_template(mode: str | None) -> str:
+    """Return the synthesis-prompt body for a given mode.
+
+    `mode=None` collapses to the `default` decision template (back-
+    compat for callers that do not thread the lens through). Unknown
+    modes raise ValueError — fail closed, never silently passthrough.
+
+    Returns an empty string for creative lenses (`design`/`optimize`)
+    so callers can detect "no template, render bare" without a magic
+    sentinel.
+    """
+    if mode is None:
+        return _SYNTHESIS_TABLE["default"]
+    if mode in _SYNTHESIS_TABLE:
+        return _SYNTHESIS_TABLE[mode]
+    if mode in _INPUT_MODE_TO_SYNTHESIS_KEY:
+        return _SYNTHESIS_TABLE[_INPUT_MODE_TO_SYNTHESIS_KEY[mode]]
+    raise ValueError(
+        f"Unknown synthesis mode {mode!r}. "
+        f"Expected one of: {sorted(set(_SYNTHESIS_TABLE) | set(_INPUT_MODE_TO_SYNTHESIS_KEY))}"
+    )
+
+
+def all_synthesis_modes() -> list[str]:
+    """Return the lens keys that have explicit synthesis templates."""
+    return sorted(_SYNTHESIS_TABLE)
+
+
 def _strip_host_identity(text: str) -> str:
     """Drop any *whole line* containing a host-agent identity substring.
 
@@ -230,3 +442,126 @@ def system_prompt_for(
 
 def all_modes() -> list[str]:
     return sorted(_MODE_TABLE)
+
+
+def advisor_system_prompt(
+    persona_text: str,
+    *,
+    project: ProjectContext | None = None,
+    original_ask: str = "",
+) -> str:
+    """Build the system prompt for an advisor-mode call (Phase 6).
+
+    Layout: neutral handoff preamble (same shape every council member
+    sees, regardless of mode) + the advisor's persona body. The
+    mode-specific addendum from ``_MODE_TABLE`` is intentionally
+    replaced — the persona file owns the full instructional surface
+    for an advisor call.
+    """
+    head = handoff_preamble(project, original_ask)
+    body = (persona_text or "").strip()
+    if not body:
+        raise ValueError("advisor_system_prompt: persona_text is empty.")
+    return f"{head}\n\n{body}"
+
+
+
+def build_extraction_user_prompt(original_analysis: str) -> str:
+    """User-message body for the finding-extraction pass.
+
+    Pairs the prior analysis text with the extraction-prompt rules so
+    the member re-emits its own findings in machine-readable form.
+    """
+    cleaned = _strip_host_identity(original_analysis or "").strip()
+    return f"{FINDING_EXTRACTION_PROMPT}\n\n---\n\n{cleaned}"
+
+
+def build_scoring_user_prompt(anonymised: dict[str, str]) -> str:
+    """User-message body for the scoring pass.
+
+    `anonymised` maps `Finding-A`/`Finding-B`/… → finding text. Author
+    identities MUST already be stripped — this function does NOT
+    re-anonymise, it just renders.
+    """
+    lines = [FINDING_SCORING_PROMPT, "", "---", ""]
+    for label, text in anonymised.items():
+        lines.append(f"### {label}\n\n{text}")
+    return "\n\n".join(lines)
+
+
+# ── Peer-review (Phase 5 / F1, Karpathy anonymous review) ────────────
+#
+# After the final deliberation round, each member sees the OTHER
+# members' deliberation outputs under neutral `Response-A` / `Response-B`
+# labels and produces a Karpathy-style critique: strongest response,
+# weakest blind spot, what all of them missed. Provider identity is
+# stripped (Iron Law of Neutrality § peer-review); advisor persona
+# labels (Phase 6) are preserved by the caller via `anonymize_responses`.
+#
+# Reviewers never see their own response — that is by design (the
+# orchestrator filters self before calling `build_peer_review_user_prompt`).
+
+PEER_REVIEW_PROMPT = """\
+Below are responses from other independent reviewers to the same
+artefact you just reviewed. Each is labelled with a neutral identifier
+(`Response-A`, `Response-B`, …). You do NOT know which model produced
+which response. Critique them as a peer — your goal is to surface
+signal the round-1 deliberation may have missed.
+
+Respond in plain prose under exactly these four headings:
+
+### Strongest response
+Name the single response whose argument or evidence is most
+load-bearing. Cite the label. One paragraph.
+
+### Weakest blind spot
+The single most important thing one specific response missed,
+glossed over, or got wrong. Cite the label. One paragraph.
+
+### What everyone missed
+A point none of the responses raised but that the artefact's context
+suggests is load-bearing. One paragraph. Mark as `needs-verification`
+when you inferred it rather than read it directly from the artefact.
+
+### Refinement
+One sentence: which course the synthesizer should prefer in light of
+the above, grounded in the strongest converged signal.
+
+Rules:
+- Cite labels exactly as given (`Response-A`, not `A` or `the first one`).
+- Do not invent agreement or disagreement that is not visible in the
+  responses themselves.
+- You may NOT see your own response in the list — that is by design.
+""".strip()
+
+PEER_REVIEW_SYNTHESIS_ADDENDUM = """\
+
+### Peer-Review-Surfaced Blind Spots
+Items the peer-review round surfaced that the round-1 responses did
+not. Cite the peer-reviewer label and the targeted response label
+(`Reviewer A on Response-B: <one-line summary>`). Maximum three.
+""".rstrip()
+
+
+def build_peer_review_user_prompt(anonymised: dict[str, str]) -> str:
+    """User-message body for the peer-review pass.
+
+    `anonymised` maps `Response-A` / `Response-B` / … → response text.
+    Provider identities MUST already be stripped by the caller (see
+    `consensus.anonymize_responses`); this function does NOT re-anonymise,
+    it just renders.
+    """
+    lines = [PEER_REVIEW_PROMPT, "", "---", ""]
+    for label, text in anonymised.items():
+        lines.append(f"### {label}\n\n{text}")
+    return "\n\n".join(lines)
+
+
+def peer_review_synthesis_addendum() -> str:
+    """Return the synthesis-template addendum used when peer-review fired.
+
+    Appended to the lens-specific synthesis template by the renderer.
+    Creative-lens (prose) runs receive only the bare section header so
+    the host agent can write free-form synthesis underneath it.
+    """
+    return PEER_REVIEW_SYNTHESIS_ADDENDUM

package/scripts/check_compressed_paths.py

@@ -58,10 +58,15 @@ _LINK_RE = re.compile(r'\[[^\]]*\]\(([^)#\s]+)(?:#[^)]*)?\)')
 # Body-link prefixes whose resolution is intentionally out of scope.
 # Council Decision 2 (2026-05-06): P3.1 was cancelled, so guideline links
 # under `.agent-src/rules/` cannot resolve in the projected tree. Copilot
-# suppression (P6) is the silencer for the noise.
+# suppression (P6) is the silencer for the noise. `docs/contracts/` shares
+# the same shape as `docs/guidelines/` — both live at repo root and the
+# rewriter collapses `../../docs/{contracts,guidelines}/...` to a
+# `../docs/...` form that cannot resolve under `.agent-src/`.
 UNCHECKED_LINK_PREFIXES = (
     "../docs/guidelines/",
     "../../docs/guidelines/",
+    "../docs/contracts/",
+    "../../docs/contracts/",
 )
 
 

package/scripts/check_references.py

@@ -39,6 +39,17 @@ SKIP_DIRS = [
     "agents/council-questions",  # design Q&A trail — forward-refs to planned artifacts
     "agents/analysis",           # plate-comparison working docs — forward-refs to planned artifacts
 ]
+
+# Per-file opt-out marker. When present in the first 10 lines of a .md
+# file, the entire file is skipped. Use for working docs that
+# intentionally reference planned-but-not-yet-existing artifacts
+# (audit bundles, design Q&A, in-flight plans).
+FILE_SKIP_MARKER = "<!-- check-refs: skip -->"
+
+# Per-line opt-out marker. When present anywhere on a line, that line's
+# refs are skipped. Use for isolated forward-refs inside otherwise
+# fully-checked documents.
+LINE_IGNORE_MARKER = "<!-- ref-ignore -->"
 ROOT = Path(".")
 
 # YAML memory files (engineering-memory layer) live under `agents/memory/`.
@@ -219,6 +230,14 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
     except Exception:
         return broken
 
+    # File-level opt-out: working docs that intentionally reference
+    # planned-but-not-yet-existing artifacts mark themselves with
+    # `<!-- check-refs: skip -->` in the first 10 lines. Marker pairs
+    # with the per-line `<!-- ref-ignore -->` below; either suffices.
+    header_lines = text.splitlines()[:10]
+    if any(FILE_SKIP_MARKER in line for line in header_lines):
+        return broken
+
     # Validate `personas:` frontmatter entries against known persona ids.
     for line_no, pid in _extract_personas_frontmatter(text):
         if pid not in artifacts["personas"]:
@@ -241,6 +260,12 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
         if in_code_block:
             continue
 
+        # Per-line opt-out: isolated forward-refs in otherwise checked
+        # documents (e.g. one ref to a planned skill, surrounded by
+        # valid refs). Skip the whole line's path / skill / rule checks.
+        if LINE_IGNORE_MARKER in line:
+            continue
+
         # Unchecked TODO checkboxes document future work — their refs are
         # forward-looking and will not resolve yet. Track multi-line bullets:
         # any `- [ ]` opens a TODO context; a new top-level bullet, heading,

package/scripts/ci_time_ratio.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""CI-time / local-edit-time ratio (council file 07, Phase 2.3).
+
+Samples the last N commits on a branch, classifies each by touched
+paths (doc / skill / test / meta / mixed), and computes:
+
+    ratio = ci_time / local_time
+
+where:
+- `local_time` = delta between author-date of the *previous* commit and
+  author-date of the current commit, capped at 60 min to filter breaks.
+- `ci_time`  = sum of GitHub Actions workflow durations for that commit
+  sha (via `gh run list --commit <sha>`).
+
+Threshold rule (Round-3 Sonnet protocol):
+- Median ratio > 5× for any frequent class → that class needs a cheaper tier
+- Median ratio < 3× across all classes      → structural overhead acceptable
+
+Output: human-readable table on stdout + JSON to
+`agents/reports/ci-time-ratio.json`.
+
+Usage:
+    python3 scripts/ci_time_ratio.py --limit 30
+    python3 scripts/ci_time_ratio.py --branch main --limit 30 --out path.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import subprocess
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_OUT = REPO_ROOT / "agents" / "reports" / "ci-time-ratio.json"
+
+LOCAL_TIME_CAP_S = 60 * 60          # cap a single edit window at 60 min
+THRESHOLD_FAIL = 5.0
+THRESHOLD_PASS = 3.0
+
+
+def run(cmd: list[str]) -> str:
+    return subprocess.check_output(cmd, cwd=REPO_ROOT, text=True)
+
+
+def list_commits(branch: str, limit: int) -> list[dict]:
+    out = run(["git", "log", branch, f"-n{limit + 1}",
+               "--format=%H\t%at\t%s"]).strip().splitlines()
+    rows = []
+    for line in out:
+        sha, ts, subject = line.split("\t", 2)
+        rows.append({"sha": sha, "timestamp": int(ts), "subject": subject})
+    return rows
+
+
+def classify(sha: str) -> str:
+    files = run(["git", "show", "--name-only", "--format=", sha]).strip().splitlines()
+    files = [f for f in files if f]
+    if not files:
+        return "empty"
+    doc = sum(1 for f in files if f.startswith("docs/") or f.endswith(".md"))
+    skill = sum(1 for f in files if "/skills/" in f or f.startswith(".agent-src.uncompressed/skills/"))
+    test = sum(1 for f in files if f.startswith("tests/") or "/tests/" in f)
+    meta = sum(1 for f in files if f.startswith(("Taskfile", "scripts/", ".github/", "pyproject", "package")))
+    total = len(files)
+    # Single-class dominance: 70% of touched files in one bucket
+    for label, n in [("skill", skill), ("test", test), ("doc", doc), ("meta", meta)]:
+        if n >= max(1, int(total * 0.7)):
+            return label
+    return "mixed"
+
+
+def ci_duration_for(sha: str) -> int | None:
+    """Total wall-clock seconds for all completed runs of this commit."""
+    try:
+        out = run(["gh", "run", "list", "--commit", sha, "--limit", "20",
+                   "--json", "createdAt,updatedAt,status,conclusion"])
+    except subprocess.CalledProcessError:
+        return None
+    runs = json.loads(out)
+    if not runs:
+        return None
+    durations = []
+    for r in runs:
+        if r.get("status") != "completed":
+            continue
+        from datetime import datetime
+        c = datetime.fromisoformat(r["createdAt"].replace("Z", "+00:00"))
+        u = datetime.fromisoformat(r["updatedAt"].replace("Z", "+00:00"))
+        durations.append((u - c).total_seconds())
+    if not durations:
+        return None
+    # Workflows run in parallel — wall-clock is the max, not the sum.
+    return int(max(durations))
+
+
+def collect(branch: str, limit: int) -> list[dict]:
+    commits = list_commits(branch, limit)
+    if len(commits) < 2:
+        return []
+    rows = []
+    for i in range(len(commits) - 1):
+        cur, prev = commits[i], commits[i + 1]
+        local_s = min(cur["timestamp"] - prev["timestamp"], LOCAL_TIME_CAP_S)
+        if local_s < 30:
+            continue
+        ci_s = ci_duration_for(cur["sha"])
+        if ci_s is None:
+            continue
+        cls = classify(cur["sha"])
+        rows.append({
+            "sha": cur["sha"][:10], "class": cls,
+            "local_s": local_s, "ci_s": ci_s,
+            "ratio": round(ci_s / local_s, 2) if local_s else None,
+            "subject": cur["subject"][:80],
+        })
+    return rows
+
+
+def summarise(rows: list[dict]) -> dict:
+    by_class: dict[str, list[float]] = defaultdict(list)
+    for r in rows:
+        if r["ratio"] is not None:
+            by_class[r["class"]].append(r["ratio"])
+    summary = {}
+    for cls, ratios in sorted(by_class.items()):
+        m = statistics.median(ratios)
+        if m > THRESHOLD_FAIL:
+            verdict = "optimise"
+        elif m < THRESHOLD_PASS:
+            verdict = "acceptable"
+        else:
+            verdict = "watch"
+        summary[cls] = {"n": len(ratios), "median": round(m, 2),
+                        "min": round(min(ratios), 2), "max": round(max(ratios), 2),
+                        "verdict": verdict}
+    all_ratios = [r["ratio"] for r in rows if r["ratio"] is not None]
+    overall = {"n": len(all_ratios),
+               "median": round(statistics.median(all_ratios), 2) if all_ratios else None,
+               "verdict": ("acceptable" if all_ratios and statistics.median(all_ratios) < THRESHOLD_PASS
+                          else "needs-review" if all_ratios else "no-data")}
+    return {"overall": overall, "by_class": summary}
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--branch", default="HEAD")
+    p.add_argument("--limit", type=int, default=30)
+    p.add_argument("--out", type=Path, default=DEFAULT_OUT)
+    args = p.parse_args()
+    rows = collect(args.branch, args.limit)
+    report = summarise(rows)
+    report["sample"] = rows
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(report, indent=2) + "\n")
+    print(f"✅  Wrote {args.out.relative_to(REPO_ROOT)}  (n={report['overall']['n']})")
+    ov = report["overall"]
+    print(f"   overall median ratio: {ov['median']}×  →  {ov['verdict']}")
+    for cls, s in report["by_class"].items():
+        print(f"   {cls:7}  n={s['n']:2}  median={s['median']:.2f}×  range=[{s['min']}–{s['max']}]  {s['verdict']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())