@event4u/agent-config 3.1.1 → 3.3.0

package/scripts/_lib/changelog_eras.py

@@ -0,0 +1,330 @@
+"""Shared constants + helpers for CHANGELOG.md era discipline.
+
+The drift gate (``tests/test_changelog_eras.py``) and the release
+automation (``scripts/release.py``) both reason about the same era
+shape: a single ``# Era: X.Y.x — current`` header followed by inline
+entries, then ``# Era: pre-X.Y.0 — archived`` pointers to files under
+``docs/archive/``. Keeping the regex / cap / path constants in one
+place prevents drift between the gate and the auto-split logic.
+
+Normative source: ``docs/contracts/CHANGELOG-conventions.md § Era splits``.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+CHANGELOG = REPO_ROOT / "CHANGELOG.md"
+CONVENTIONS = REPO_ROOT / "docs" / "contracts" / "CHANGELOG-conventions.md"
+ARCHIVE_DIR = REPO_ROOT / "docs" / "archive"
+
+# Drift cap — entries between the current era header and the next era
+# header may not exceed this many lines. Raising the cap is a contract
+# change (see CHANGELOG-conventions.md § Era splits).
+CURRENT_ERA_BODY_CAP = 250
+
+ERA_HEADER_RE = re.compile(
+    r"^# Era: (?P<label>[^\n]+?)(?: — (?P<state>current|archived))?\s*$"
+)
+ARCHIVE_LINK_RE = re.compile(r"\(docs/archive/(CHANGELOG-pre-[^)\s]+\.md)\)")
+VERSION_HEADING_RE = re.compile(r"^## \[?(?P<version>\d+\.\d+\.\d+)")
+ERA_LABEL_RE = re.compile(r"^(?P<major>\d+)\.(?P<minor>\d+)\.x$")
+
+
+@dataclass(frozen=True)
+class EraSpan:
+    """One era header in CHANGELOG.md, with its line index."""
+
+    line_index: int
+    label: str
+    state: str  # "current" | "archived" | ""
+
+
+def read_changelog_lines() -> list[str]:
+    """Return CHANGELOG.md split into lines (no trailing newlines)."""
+    return CHANGELOG.read_text(encoding="utf-8").splitlines()
+
+
+def era_spans(lines: list[str]) -> list[EraSpan]:
+    """Return every era header in line-order."""
+    spans: list[EraSpan] = []
+    for i, line in enumerate(lines):
+        m = ERA_HEADER_RE.match(line)
+        if m:
+            spans.append(
+                EraSpan(
+                    line_index=i,
+                    label=m.group("label"),
+                    state=m.group("state") or "",
+                )
+            )
+    return spans
+
+
+def current_era_index(spans: list[EraSpan]) -> int | None:
+    """Return the line index of the ``— current`` era header, or None."""
+    for span in spans:
+        if span.state == "current":
+            return span.line_index
+    return None
+
+
+def current_era_body_size(lines: list[str] | None = None) -> int:
+    """Return the number of lines between the current era header and
+    the next era header (exclusive of both)."""
+    if lines is None:
+        lines = read_changelog_lines()
+    spans = era_spans(lines)
+    current_idx = current_era_index(spans)
+    if current_idx is None:
+        return 0
+    next_era_line = len(lines)
+    for span in spans:
+        if span.line_index > current_idx:
+            next_era_line = span.line_index
+            break
+    return next_era_line - current_idx - 1
+
+
+def parse_era_label(label: str) -> tuple[int, int] | None:
+    """Parse ``M.N.x`` into ``(M, N)``; return None for archived labels."""
+    m = ERA_LABEL_RE.match(label.strip())
+    if not m:
+        return None
+    return int(m.group("major")), int(m.group("minor"))
+
+
+def archive_path_for_boundary(boundary: str) -> Path:
+    """Return ``docs/archive/CHANGELOG-pre-<boundary>.md``."""
+    return ARCHIVE_DIR / f"CHANGELOG-pre-{boundary}.md"
+
+
+def collapsed_era_block(boundary: str) -> str:
+    """Render the standard ``# Era: pre-<boundary> — archived`` pointer
+    block that replaces archived entries in CHANGELOG.md.
+
+    Mirrors the wording the manual splits already used (verified against
+    every existing collapsed era as of 3.2.x).
+    """
+    archive_rel = f"docs/archive/CHANGELOG-pre-{boundary}.md"
+    return (
+        f"# Era: pre-{boundary} — archived\n"
+        "\n"
+        f"> All entries before `{boundary}` live in\n"
+        f"> [`{archive_rel}`]({archive_rel}).\n"
+        "> The archive is read-only; git tags remain the canonical\n"
+        "> source for what shipped. Splitting them out of the main file\n"
+        "> keeps the active era under the 250-line drift cap enforced by\n"
+        "> `tests/test_changelog_eras.py`.\n"
+    )
+
+
+def archive_file_header(boundary: str) -> str:
+    """Return the standard prologue for ``docs/archive/CHANGELOG-pre-<boundary>.md``."""
+    return (
+        f"# Changelog Archive — pre-{boundary}\n"
+        "\n"
+        f"> Frozen snapshot of `event4u/agent-config` changelog entries\n"
+        f"> released before `{boundary}`, split out of the main\n"
+        "> [`CHANGELOG.md`](../../CHANGELOG.md) by `scripts/release.py`\n"
+        "> once the active era's body crossed the drift cap enforced by\n"
+        "> `tests/test_changelog_eras.py`.\n"
+        ">\n"
+        "> **Read-only.** New entries land in `CHANGELOG.md`. Entries\n"
+        "> here are not amended — git tags remain the canonical source\n"
+        "> for what shipped.\n"
+        ">\n"
+        "> Entry shape follows\n"
+        "> [`../contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md).\n"
+        "\n"
+    )
+
+
+# ─── split planning + execution ────────────────────────────────────────────────
+
+
+_RELEASE_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+
+
+@dataclass(frozen=True)
+class SplitPlan:
+    """Recipe for an era split during release of ``release_version``."""
+
+    release_version: str  # e.g. "3.3.0"
+    boundary: str  # e.g. "3.3.0" — used in archive filename + pointer
+    new_era_label: str  # e.g. "3.3.x"
+    old_era_label: str  # e.g. "3.2.x"
+    archive_path: Path
+
+    @property
+    def commit_subject(self) -> str:
+        return (
+            f"chore(changelog): split era {self.old_era_label} "
+            f"→ pre-{self.boundary}"
+        )
+
+
+def plan_split(release_version: str) -> SplitPlan | None:
+    """Plan an era split when releasing ``release_version``.
+
+    Returns None when no split is needed (release is a patch within the
+    current era, or no current era header exists). Returns a SplitPlan
+    when the release crosses a minor or major boundary; the caller
+    decides whether to invoke ``perform_split`` based on era body size.
+
+    Raises ValueError when ``release_version`` is not bare semver, or
+    when it would move backward relative to the current era label.
+    """
+    m = _RELEASE_VERSION_RE.match(release_version.strip())
+    if not m:
+        raise ValueError(f"not a bare semver (X.Y.Z): {release_version!r}")
+    rel_major, rel_minor, _rel_patch = (int(m.group(i)) for i in (1, 2, 3))
+
+    lines = read_changelog_lines()
+    spans = era_spans(lines)
+    current = next((s for s in spans if s.state == "current"), None)
+    if current is None:
+        return None
+
+    parsed = parse_era_label(current.label)
+    if parsed is None:
+        return None
+    era_major, era_minor = parsed
+
+    if (rel_major, rel_minor) < (era_major, era_minor):
+        raise ValueError(
+            f"release {release_version!r} is older than current era "
+            f"{current.label!r}; refusing to plan a backwards split"
+        )
+    if (rel_major, rel_minor) == (era_major, era_minor):
+        # Patch release within the current era — no era boundary crossed,
+        # so an auto-split would create a nonsensical archive name. The
+        # caller is expected to die() with the manual-intervention message.
+        return None
+
+    boundary = f"{rel_major}.{rel_minor}.0"
+    return SplitPlan(
+        release_version=release_version,
+        boundary=boundary,
+        new_era_label=f"{rel_major}.{rel_minor}.x",
+        old_era_label=current.label,
+        archive_path=archive_path_for_boundary(boundary),
+    )
+
+
+def new_era_intro_block(new_era_label: str, boundary: str) -> str:
+    """Render the header + blockquote intro for a freshly-split current era."""
+    parsed = parse_era_label(new_era_label)
+    if parsed is None:
+        next_example = "# Era: <next>.x"
+    else:
+        m, n = parsed
+        next_example = f"# Era: {m}.{n + 1}.x"
+    return (
+        f"# Era: {new_era_label} — current\n"
+        "\n"
+        f"> Started at `{boundary}`. Full entries live inline below.\n"
+        "> The drift test caps this era at 250 lines of entry body; growth past\n"
+        f"> that forces a new era split (`{next_example}`, etc.) — see\n"
+        "> [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).\n"
+    )
+
+
+def _era_body_bounds(
+    lines: list[str], current_idx: int
+) -> tuple[int, int, int]:
+    """Return ``(body_start, body_end, next_era_line)`` for the era at
+    ``current_idx``.
+
+    * ``body_start`` — first line after the header + leading blockquote
+      intro + the blank line that follows.
+    * ``body_end`` — exclusive; one line before the next era marker (or
+      end of file). Trailing blank lines are NOT trimmed; the caller
+      reattaches them on splice.
+    * ``next_era_line`` — index of the next ``# Era:`` line, or
+      ``len(lines)`` when none follows.
+    """
+    next_era_line = len(lines)
+    for i in range(current_idx + 1, len(lines)):
+        if ERA_HEADER_RE.match(lines[i]):
+            next_era_line = i
+            break
+
+    cursor = current_idx + 1
+    # Skip leading blank lines between header and blockquote intro.
+    while cursor < next_era_line and lines[cursor].strip() == "":
+        cursor += 1
+    # Skip the leading blockquote intro (consecutive `>`-prefixed lines).
+    while cursor < next_era_line and lines[cursor].startswith(">"):
+        cursor += 1
+    # Skip the blank separator between intro and entries.
+    while cursor < next_era_line and lines[cursor].strip() == "":
+        cursor += 1
+
+    return cursor, next_era_line, next_era_line
+
+
+def current_era_insertion_point(lines: list[str]) -> int | None:
+    """Return the line index at which a new release entry should be
+    prepended within the current era.
+
+    Strategy:
+    * If the current era body contains one or more ``## [X.Y.Z]``
+      headings, return the line of the topmost (newest) one.
+    * Otherwise, return the first line after the era intro blockquote.
+
+    Returns None when no current era header exists.
+    """
+    spans = era_spans(lines)
+    current_idx = current_era_index(spans)
+    if current_idx is None:
+        return None
+    body_start, body_end, _ = _era_body_bounds(lines, current_idx)
+    for i in range(body_start, body_end):
+        if VERSION_HEADING_RE.match(lines[i]):
+            return i
+    return body_start
+
+
+def perform_split(plan: SplitPlan) -> None:
+    """Execute ``plan`` against the on-disk CHANGELOG.md.
+
+    * Refuses to overwrite an existing archive file.
+    * Moves every entry in the current era body into the new archive.
+    * Replaces the current era block with the collapsed pointer + the
+      freshly-labelled new current era header (empty body).
+    """
+    if plan.archive_path.exists():
+        raise FileExistsError(
+            f"archive already exists at {plan.archive_path} — "
+            "likely a previous --resume run; inspect manually"
+        )
+
+    lines = read_changelog_lines()
+    spans = era_spans(lines)
+    current_idx = current_era_index(spans)
+    if current_idx is None:
+        raise RuntimeError("no current era header found in CHANGELOG.md")
+
+    body_start, _, next_era_line = _era_body_bounds(lines, current_idx)
+    entries = lines[body_start:next_era_line]
+    # Trim trailing blank lines so the archive doesn't accumulate them.
+    while entries and entries[-1].strip() == "":
+        entries.pop()
+
+    collapsed = collapsed_era_block(plan.boundary).rstrip("\n").splitlines()
+    new_era = new_era_intro_block(plan.new_era_label, plan.boundary).rstrip("\n").splitlines()
+
+    head = lines[:current_idx]
+    tail = lines[next_era_line:]
+    new_lines = head + collapsed + [""] + new_era + [""] + tail
+    new_text = "\n".join(new_lines).rstrip() + "\n"
+
+    archive_body = "\n".join(entries).rstrip() + "\n" if entries else ""
+    archive_text = archive_file_header(plan.boundary) + archive_body
+
+    plan.archive_path.parent.mkdir(parents=True, exist_ok=True)
+    plan.archive_path.write_text(archive_text, encoding="utf-8")
+    CHANGELOG.write_text(new_text, encoding="utf-8")

package/scripts/audit_mcp_tools.py

@@ -105,7 +105,7 @@ def _render(catalog: dict, handlers: dict[str, int], cat_lines: dict[str, int])
     lines.append("## Glossary")
     lines.append("")
     lines.append("- **Side-effect** — `ro` (read-only) · `fs-write` (filesystem write) · `shell` (spawns processes).")
-    lines.append("- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`workers/mcp/`). A tool may live on both.")
+    lines.append("- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`internal/workers/mcp/`). A tool may live on both.")
     lines.append("- **Stub** — catalog-listed for discovery; returns the `not_implemented` envelope from")
     lines.append("  [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) until promoted.")
     lines.append("")

package/scripts/bench_baseline_ready.py

@@ -2,7 +2,7 @@
 """Baseline-closure check — step-4 Phase 3 Step 4.
 
 Returns exit 0 iff the 60-day clock has elapsed since
-`bench/baseline-start.txt` AND `bench/reports/` contains at least
+`internal/bench/baseline-start.txt` AND `internal/bench/reports/` contains at least
 `--min-reports` complete runs for the named corpus (default 30).
 
 Read by P2 enforcement roadmaps as their precondition (G1 gate in
@@ -50,8 +50,8 @@ def main(argv: list[str] | None = None) -> int:
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     ap.add_argument("--corpus", default="dev")
-    ap.add_argument("--reports-dir", default="bench/reports")
-    ap.add_argument("--baseline-file", default="bench/baseline-start.txt")
+    ap.add_argument("--reports-dir", default="internal/bench/reports")
+    ap.add_argument("--baseline-file", default="internal/bench/baseline-start.txt")
     ap.add_argument("--min-days", type=int, default=60)
     ap.add_argument("--min-reports", type=int, default=30)
     ap.add_argument("--json", action="store_true")

package/scripts/bench_compress_memory.py

@@ -3,10 +3,10 @@
 
 Runs `compress_memory.py` over a fixed corpus of memory-target files, records
 pre/post char counts, approximates input-token savings (chars / 4 — the
-GPT-4 / Claude rule of thumb), and emits `bench/reports/caveman-v2.{json,md}`.
+GPT-4 / Claude rule of thumb), and emits `internal/bench/reports/caveman-v2.{json,md}`.
 
 Offline (no API calls). Cadence-aligned with `docs/benchmarks.md`. Citation
-in `bench/reports/caveman-v2.md` notes the chars→tokens approximation and
+in `internal/bench/reports/caveman-v2.md` notes the chars→tokens approximation and
 points at upstream tiktoken / claude-tokenizer if a calibrated number is
 later needed.
 """
@@ -23,8 +23,8 @@ from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 COMPRESS_SCRIPT = REPO_ROOT / "scripts" / "compress_memory.py"
-REPORT_JSON = REPO_ROOT / "bench" / "reports" / "caveman-v2.json"
-REPORT_MD = REPO_ROOT / "bench" / "reports" / "caveman-v2.md"
+REPORT_JSON = REPO_ROOT / "internal" / "bench" / "reports" / "caveman-v2.json"
+REPORT_MD = REPO_ROOT / "internal" / "bench" / "reports" / "caveman-v2.md"
 
 CORPUS: list[tuple[str, str]] = [
     ("AGENTS.md", "thin-root-package"),

package/scripts/bench_drift_check.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Drift detector for the bench corpus — step-4 Phase 3 Step 2.
 
-Compares the latest `bench/reports/<stamp>-<corpus>.json` against the
+Compares the latest `internal/bench/reports/<stamp>-<corpus>.json` against the
 previous N reports (default 5) for the same corpus. Drift defined as:
 
     - selection-accuracy: latest is more than `accuracy_drop_pp` below
@@ -99,7 +99,7 @@ def _check(latest: dict[str, Any], baseline: list[dict[str, Any]],
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--corpus", default="dev")
-    ap.add_argument("--reports-dir", default="bench/reports")
+    ap.add_argument("--reports-dir", default="internal/bench/reports")
     ap.add_argument("--window", type=int, default=5, help="rolling window size (default 5)")
     ap.add_argument("--accuracy-drop-pp", type=float, default=5.0)
     ap.add_argument("--cost-increase-pct", type=float, default=20.0)

package/scripts/bench_per_tool.py

@@ -43,7 +43,7 @@ from bench_runner import rank_skills  # type: ignore  # noqa: E402
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 CORPUS_DIR = REPO_ROOT / "tests" / "eval"
-REPORTS_DIR = REPO_ROOT / "bench" / "reports"
+REPORTS_DIR = REPO_ROOT / "internal" / "bench" / "reports"
 
 # tool_id -> (skills_root, kind). kind = "skills" | "rules_only" | "single_file".
 SURFACES: dict[str, tuple[Path, str]] = {
@@ -185,7 +185,7 @@ def main(argv=None) -> int:
     ap.add_argument("--threshold", type=float, default=0.85)
     ap.add_argument("--json", action="store_true")
     ap.add_argument("--write-report", action="store_true",
-                    help="emit bench/reports/<ts>-<corpus>-projection.{json,md}")
+                    help="emit internal/bench/reports/<ts>-<corpus>-projection.{json,md}")
     args = ap.parse_args(argv)
 
     corpus_path = CORPUS_DIR / f"corpus-{args.corpus}.yaml"

package/scripts/bench_run.py

@@ -5,7 +5,7 @@ Wraps the selection-accuracy baseline collector (`scripts/bench_runner.py`),
 captures token / cost data from `agents/cost-tracking/sessions.jsonl` if
 present (per ruflo pattern, external-findings § 2), runs structural
 quality assertions per prompt, and emits a versioned JSON + Markdown
-report under `bench/reports/` per
+report under `internal/bench/reports/` per
 `docs/contracts/benchmark-report-schema.md`.
 
 Usage:
@@ -46,11 +46,11 @@ except ImportError:
     sys.exit(2)
 
 BENCH_RUN_VERSION = "0.2.0"
-PRICING_PATH = REPO_ROOT / "bench" / "pricing.yaml"
+PRICING_PATH = REPO_ROOT / "internal" / "bench" / "pricing.yaml"
 SESSIONS_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
-REPORTS_DIR = REPO_ROOT / "bench" / "reports"
+REPORTS_DIR = REPO_ROOT / "internal" / "bench" / "reports"
 CORPUS_DIR = REPO_ROOT / "tests" / "eval"
-CAVEMAN_CORPUS = REPO_ROOT / "bench" / "corpora" / "caveman" / "prompts.yaml"
+CAVEMAN_CORPUS = REPO_ROOT / "internal" / "bench" / "corpora" / "caveman" / "prompts.yaml"
 BASELINE_COLLECTOR = REPO_ROOT / "scripts" / "bench_runner.py"
 
 

package/scripts/build_mcp_registry_manifest.py

@@ -4,7 +4,7 @@
 Reads three on-disk sources:
   * `package.json`                          — name, version, description, homepage, repository
   * `.github/topics.yml`                    — topics list (for registries that accept tags)
-  * `workers/mcp/content.json`              — `tool_catalog` (tools_count, install_hint_stdio)
+  * `internal/workers/mcp/content.json`     — `tool_catalog` (tools_count, install_hint_stdio)
   * `dist/discovery/discovery-manifest.json` — artefact_count + scanner_version (HARD prereq per AI-Council R5)
 
 Emits:
@@ -37,7 +37,7 @@ import yaml
 ROOT = Path(__file__).resolve().parents[1]
 PKG_FILE = ROOT / "package.json"
 TOPICS_FILE = ROOT / ".github" / "topics.yml"
-CONTENT_FILE = ROOT / "workers" / "mcp" / "content.json"
+CONTENT_FILE = ROOT / "internal" / "workers" / "mcp" / "content.json"
 DISCOVERY_FILE = ROOT / "dist" / "discovery" / "discovery-manifest.json"
 OUT_DIR = ROOT / "dist" / "mcp"
 OUT_MANIFEST = OUT_DIR / "registry-manifest.json"

package/scripts/mcp_server/__init__.py

@@ -2,7 +2,7 @@
 
 mcp_scope: full — local stdio access can be extended to tool execution
 under the Phase 7 wake-up triggers in `docs/contracts/mcp-cloud-scope.md`.
-The hosted Worker (`workers/mcp/`) is `mcp_scope: lite` and is
+The hosted Worker (`internal/workers/mcp/`) is `mcp_scope: lite` and is
 intentionally narrower.
 
 Exposes a hand-picked subset of `.agent-src/skills/` as MCP `prompts`

package/scripts/mcp_server/catalog.py

@@ -108,7 +108,7 @@ def not_implemented_envelope(
 ) -> dict[str, Any]:
     """Wire-shape error envelope used when a stub is invoked.
 
-    Mirrored verbatim by the Cloud Worker (`workers/mcp/src/stubs.ts`).
+    Mirrored verbatim by the Cloud Worker (`internal/workers/mcp/src/stubs.ts`).
     """
     return {
         "code": NOT_IMPLEMENTED_CODE,

package/scripts/mcp_server/consumer_tool_catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (workers/mcp/). Phase 1 of road-to-mcp-full-coverage: tools without 'implemented' transports return the 'not_implemented' envelope defined in docs/contracts/mcp-tool-stub-envelope.md. The 'implemented_on' field lists transports where the real handler is wired; everything else is a discovery stub. See agents/roadmaps/archive/road-to-mcp-full-coverage.md.",
+  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (internal/workers/mcp/). Phase 1 of road-to-mcp-full-coverage: tools without 'implemented' transports return the 'not_implemented' envelope defined in docs/contracts/mcp-tool-stub-envelope.md. The 'implemented_on' field lists transports where the real handler is wired; everything else is a discovery stub. See agents/roadmaps/archive/road-to-mcp-full-coverage.md.",
   "install_hint_stdio": "pip install agent-config[mcp] && ./agent-config mcp:run",
   "tools": [
     {

package/scripts/mcp_server/tools.py

@@ -43,7 +43,7 @@ from .catalog import (
 from .telemetry import Outcome, record_call
 
 # Stable transport tag for the stub envelope. Mirrored verbatim by
-# `workers/mcp/src/stubs.ts` with ``"worker"``.
+# `internal/workers/mcp/src/stubs.ts` with ``"worker"``.
 STDIO_TRANSPORT = "stdio"
 
 # Allowlisted directories (relative to consumer_root) where tool writes

package/scripts/memory_lookup.py

@@ -39,6 +39,7 @@ from typing import Any, Callable, Iterable, Optional, Union
 
 MEMORY_ROOT = Path("agents/memory")
 INTAKE_ROOT = MEMORY_ROOT / "intake"
+KNOWLEDGE_ROOT = MEMORY_ROOT / "knowledge"
 
 CURATED_TYPES = {
     "ownership",
@@ -49,6 +50,12 @@ CURATED_TYPES = {
     "product-rules",
 }
 
+# `knowledge` is its own type: user-ingested local documents that live
+# under `agents/memory/knowledge/<ingest-id>/chunks/*.md`. They are
+# repo-side (file-backed) but not "curated" and not intake — the
+# conflict rule still treats them as repo entries against operational.
+KNOWLEDGE_TYPE = "knowledge"
+
 
 @dataclass
 class Hit:
@@ -167,6 +174,58 @@ def _iter_intake_entries(mtype: str) -> Iterable[tuple[Path, dict]]:
             yield jsonl, obj
 
 
+def _iter_knowledge_entries() -> Iterable[tuple[Path, dict]]:
+    """Yield (chunk-file, entry) pairs from `agents/memory/knowledge/`.
+
+    Layout (frozen in `docs/contracts/local-knowledge-ingestion.md`):
+
+        agents/memory/knowledge/<ingest-id>/
+            manifest.json
+            chunks/<n>.md
+
+    Each chunk becomes one retrieval entry. The chunk body, the
+    manifest source path, and pinned flag are surfaced into the entry
+    so `_score()` can match on either the source path or the chunk
+    text. The entry id is ``<ingest-id>:<chunk-stem>`` so callers can
+    locate the exact file on disk.
+    """
+    if not KNOWLEDGE_ROOT.is_dir():
+        return
+    for ingest_dir in sorted(KNOWLEDGE_ROOT.iterdir()):
+        if not ingest_dir.is_dir():
+            continue
+        manifest_path = ingest_dir / "manifest.json"
+        manifest: dict = {}
+        if manifest_path.is_file():
+            try:
+                manifest = json.loads(
+                    manifest_path.read_text(encoding="utf-8")
+                )
+            except (ValueError, OSError):
+                manifest = {}
+        ingest_id = str(manifest.get("ingest_id") or ingest_dir.name)
+        source = str(manifest.get("source") or "")
+        pinned = bool(manifest.get("pinned", False))
+        chunks_dir = ingest_dir / "chunks"
+        if not chunks_dir.is_dir():
+            continue
+        for chunk in sorted(chunks_dir.glob("*.md")):
+            try:
+                body = chunk.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            entry = {
+                "id": f"{ingest_id}:{chunk.stem}",
+                "ingest_id": ingest_id,
+                "source": source,
+                "path": source,
+                "body": body,
+                "pinned": pinned,
+                "source_kind": "knowledge",
+            }
+            yield chunk, entry
+
+
 def _score(entry: dict, keys: list[str]) -> float:
     """Naive relevance score: max over keys of (glob-match | substring).
 
@@ -378,6 +437,24 @@ def retrieve(
     """
     repo_hits: list[Hit] = []
     for mtype in types:
+        if mtype == KNOWLEDGE_TYPE:
+            for path, entry in _iter_knowledge_entries():
+                base = _score(entry, keys)
+                # Pinned entries get a slight ranking boost so the
+                # `/knowledge:list --pin` flag has retrieval effect.
+                if entry.get("pinned"):
+                    base = min(1.0, base + 0.05)
+                repo_hits.append(Hit(
+                    id=str(entry.get("id", "")),
+                    type=KNOWLEDGE_TYPE,
+                    source="knowledge",
+                    path=str(path),
+                    # Discount vs curated/intake so hand-reviewed repo
+                    # entries still win on equal relevance.
+                    score=base * 0.85,
+                    entry=entry,
+                ))
+            continue
         if mtype not in CURATED_TYPES:
             continue
         for path, entry in _iter_curated_entries(mtype):
@@ -426,7 +503,7 @@ CONTRACT_VERSION = 1
 
 # Memory types this file-backed backend can answer. Types outside this
 # set map to `unknown_type` per the retrieval contract.
-_KNOWN_TYPES = CURATED_TYPES
+_KNOWN_TYPES = CURATED_TYPES | {KNOWLEDGE_TYPE}
 
 
 def retrieve_v1(

package/scripts/pack_mcp_content.py

@@ -3,12 +3,12 @@
 Walks `.agent-src/skills/`, `.agent-src/commands/`, `.agent-src/rules/`,
 `docs/guidelines/`, `.agent-src/contexts/` via the same Python loaders
 that drive the local stdio kernel, emits one JSON blob and a sidecar
-manifest for `workers/mcp/`.
+manifest for `internal/workers/mcp/`.
 
 Outputs (relative to repo root):
-- `workers/mcp/content.json`      — uncompressed, bundled by `wrangler deploy`.
-- `workers/mcp/content.json.gz`   — gzipped archival copy for R2.
-- `workers/mcp/manifest.json`     — manifest only (RCA / R2 sidecar).
+- `internal/workers/mcp/content.json`      — uncompressed, bundled by `wrangler deploy`.
+- `internal/workers/mcp/content.json.gz`   — gzipped archival copy for R2.
+- `internal/workers/mcp/manifest.json`     — manifest only (RCA / R2 sidecar).
 
 Hard-fail thresholds (Phase 2-5 council verdict D2):
 - Uncompressed JSON > 2 MB         → SystemExit(1).
@@ -262,14 +262,14 @@ def main(argv: list[str] | None = None) -> int:
         "--out",
         type=Path,
         default=None,
-        help="Output directory (defaults to <root>/workers/mcp).",
+        help="Output directory (defaults to <root>/internal/workers/mcp).",
     )
     parser.add_argument(
         "--quiet", action="store_true", help="Suppress success summary."
     )
     args = parser.parse_args(argv)
 
-    out_dir = args.out or (args.root / "workers" / "mcp")
+    out_dir = args.out or (args.root / "internal" / "workers" / "mcp")
     manifest = pack(args.root, out_dir)
 
     if not args.quiet: