docs(agents): 증거 기반 작업 절차 정리

.agents/skills/github-robot-review-gate/SKILL.md

@@ -68,12 +68,16 @@ context successfully on the protected branch.
 
 ## Safe temporary handling
 
+- Require explicit maintainer authorization for the exact ruleset change and
+  substitute evidence; a delivery request alone is not authorization.
 - Prefer rerunning or updating the branch before touching rulesets.
 - If temporary removal is unavoidable, capture before/after ruleset JSON, owner,
   expiry, current head SHA, equivalent temporary evidence, and a dated rollback
   note in the PR.
 - Restore required contexts and confirm `gh pr checks --required` shows the
   hardened context before declaring the gate resolved.
+- Restore the captured configuration on success, failure, cancellation, or
+  expiry. Block further landing until restoration is verified.
 
 ## Common mistakes
 

ARCHITECTURE.md

@@ -6,7 +6,7 @@
 flowchart LR
   UI[Next.js frontend] --> API[FastAPI backend / Naruon control plane]
   API --> DB[(Postgres + pgvector)]
-  API --> LLM[OpenAI APIs when configured]
+  API --> CO[contextual-orchestrator released gateway]
   API --> CONN[Outbound-only self-hosted connector]
   CONN --> MAIL[Customer IMAP/POP3/SMTP]
   CONN --> DAV[Customer CalDAV/CardDAV/WebDAV]
@@ -227,6 +227,10 @@ URL must be HTTPS and exact-host allowlisted by `ALLOWED_LLM_BASE_URL_HOSTS`;
 an unset or rejected endpoint fails closed to the deterministic extractor. Design
 and grounding: [`docs/architecture/kg-extractor-seam.md`](docs/architecture/kg-extractor-seam.md).
 
+Provider discovery, capability routing, and fallback belong to
+`contextual-orchestrator`. Production adoption requires an immutable released
+owner API/client/schema; an unavailable or incompatible release fails closed.
+
 ## CI security boundary
 
 OpenCode Review, Strix Security Scan, and PR Review Merge Scheduler are supplied

CLAUDE.md

@@ -110,11 +110,23 @@ indexes, and auditable writeback intent. `ARCHITECTURE.md` and
 ```
 Next.js frontend ──> FastAPI backend (control plane) ──> Postgres + pgvector
                             │
-                            ├──> OpenAI-compatible LLM providers (Ollama locally)
+                            ├──> contextual-orchestrator consumer boundary
+                            │      └──> provider/model routing owned by contextual-orchestrator
                             └──> outbound-only self-hosted connector (connector/)
                                      └──> customer IMAP/POP3/SMTP + CalDAV/CardDAV/WebDAV
 ```
 
+Naruon owns product behavior and model-call authorization, but not provider/model
+routing. Production model work requires an immutable released
+`contextual-orchestrator` API/client/schema; a missing or incompatible owner
+contract fails closed instead of falling back to a direct provider. The
+Ollama/MLX paths in local Compose are explicit non-production development
+fixtures. Central model-backed GitHub Actions are owned by
+`ContextualWisdomLab/.github` and use `orchestrator/free`; do not copy that pool
+selection into Naruon runtime. Verify protected release evidence before claiming
+the owner contract is available; an open PR or unreleased branch is only proposed
+evidence.
+
 - `backend/` — FastAPI app (`main.py`, routers in `api/`, domain logic in
   `services/`, SQLAlchemy models in `db/`, Alembic in `alembic/`). Owns
   persistence, canonical email threading
@@ -140,8 +152,12 @@ Next.js frontend ──> FastAPI backend (control plane) ──> Postgres + pgve
   ETag/If-Match); intents are the default response.
 - Auth: signed HS256 bearer sessions (HMAC via `AUTH_SESSION_HMAC_SECRET`) or
   enterprise OIDC/JWKS; private `/api/*` routers register the default
-  `get_auth_context` dependency. LLM `base_url` and OIDC/SMTP/IMAP/POP3 hosts
-  are strict egress allowlists that resolve only to pinned global addresses.
+  `get_auth_context` dependency. Naruon owns domain tools, authorization, and
+  context assembly; provider/model routing belongs to `contextual-orchestrator`.
+  Existing direct-provider `base_url` surfaces are legacy migration debt and
+  must not be extended as production routing authority; keep their SSRF controls
+  until they are removed. OIDC/SMTP/IMAP/POP3 hosts remain strict egress
+  allowlists that resolve only to pinned global addresses.
 - CI (`.github/workflows/`): `app-ci.yml` (backend ruff+pytest, frontend
   test/lint/build), plus `bandit`, `codeql`, `trivy`, `scorecard`,
   `pr-governance`, `docker-publish` (GHCR on `v*` tags matching `VERSION`), and

backend/tests/test_agent_llm_authority_docs.py

@@ -0,0 +1,171 @@
+"""Regression contracts for current LLM-routing authority guidance."""
+
+import json
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _read(path: str) -> str:
+    """Read repository guidance as UTF-8 text."""
+    return (REPO_ROOT / path).read_text(encoding="utf-8")
+
+
+def test_agent_guidance_does_not_reintroduce_direct_model_routing_authority() -> None:
+    """Current agent and architecture guidance must not prescribe direct routing."""
+    agents = _read("AGENTS.md")
+    claude = _read("CLAUDE.md")
+    architecture = _read("ARCHITECTURE.md")
+
+    forbidden_current_guidance = (
+        "STRIX_GITHUB_MODELS_TOKEN",
+        "https://models.github.ai/inference",
+        "Direct OpenAI GPT-5.4-or-newer",
+        "OpenAI-compatible LLM providers",
+        "API --> LLM[OpenAI APIs when configured]",
+    )
+    combined = f"{agents}\n{claude}\n{architecture}"
+    for phrase in forbidden_current_guidance:
+        assert phrase not in combined
+
+
+def test_agent_guidance_names_canonical_llm_owner_and_fail_closed_boundary() -> None:
+    """Guidance must preserve product ownership while delegating LLM routing."""
+    agents = _read("AGENTS.md")
+    claude = _read("CLAUDE.md")
+    architecture = _read("ARCHITECTURE.md")
+    normalized_architecture = " ".join(architecture.lower().split())
+
+    assert "ContextualWisdomLab/.github" in agents
+    assert "contextual-orchestrator" in agents
+    assert "orchestrator/free" in agents
+    assert "fail closed" in agents.lower()
+    assert "contextual-orchestrator" in claude
+    assert "Naruon owns" in claude
+    assert "provider/model routing" in claude
+    assert "gateway token" in agents
+    assert "provider names, model" in agents
+    assert "immutable released owner API/client/schema" in agents
+    assert "open pr or unreleased branch" in " ".join(agents.lower().split())
+    assert "shared application/agent/gateway wall-clock timeout" in agents
+    assert "contextual-orchestrator" in normalized_architecture
+    assert "provider discovery" in normalized_architecture
+    assert "immutable released" in normalized_architecture
+    assert "fails closed" in normalized_architecture
+
+
+def test_agent_guidance_preserves_product_contract_recurrence_rules() -> None:
+    """Canonical guidance must retain product contracts repaired in owner lanes."""
+    agents = _read("AGENTS.md")
+    normalized_agents = " ".join(agents.lower().split())
+
+    assert "/api/llm/summarize" in agents
+    assert "integer percentage in `0..100`" in normalized_agents
+    assert "frontend consumers must reject fractional" in normalized_agents
+    assert "without rounding, coercion, or unit inference" in normalized_agents
+    assert "dynamic tool registration (`post /api/tools`)" in normalized_agents
+    assert "update (`patch /api/tools/{code}`)" in normalized_agents
+    assert "deletion (`delete /api/tools/{code}`)" in normalized_agents
+    assert "built-in immutability" in normalized_agents
+    assert "real provider/adapter execution target" in normalized_agents
+    assert "do not substitute a process-global registry or placeholder success" in normalized_agents
+
+
+def test_agent_guidance_requires_physical_lease_ownership_and_interruption_checks() -> None:
+    """Keep the concurrency repair procedure discoverable without claiming runtime proof."""
+    normalized_agents = " ".join(_read("AGENTS.md").lower().split())
+    for required_phrase in (
+        "session-level advisory lock",
+        "held physical connection",
+        "one-slot pool",
+        "invalidate before session-close rollback",
+        "reconnecting without a lease",
+        "last completed item",
+        "independent replica",
+        "actual task cancellation",
+        "source-only checks do not prove these runtime outcomes",
+    ):
+        assert required_phrase in normalized_agents
+
+
+def test_agent_guidance_separates_runtime_evidence_from_authorization() -> None:
+    """Retain the operating procedure without treating prose as a live gate test."""
+    normalized_agents = " ".join(_read("AGENTS.md").lower().split())
+    for required_phrase in (
+        "protected source sha, actual consumer pin",
+        "configuration scope and revision",
+        "api readback",
+        "schema or parser support is not authorization",
+        "explicit authorization for the exact principal and resource",
+        "test fixtures or a known bot sender",
+        "compare the current value and revision",
+        "preserve the restoration receipt",
+        "original `github.actor` privileges",
+        "`github.triggering_actor` can differ",
+        "do not blindly rerun",
+    ):
+        assert required_phrase in normalized_agents
+
+
+def test_agent_guidance_separates_schema_reproduction_and_resource_ownership() -> None:
+    """Keep diagnostic boundaries discoverable; prose checks are not runtime evidence."""
+    normalized_agents = " ".join(_read("AGENTS.md").lower().split())
+    for required_phrase in (
+        "general json schema validation",
+        "provider's supported subset",
+        "original model response",
+        "counterexample, not the proven cause",
+        "resource-owning transport boundary",
+        "borrowed streams",
+        "ownership transfer",
+        "garbage collection",
+        "resourcewarning",
+    ):
+        assert required_phrase in normalized_agents
+
+
+def test_agent_guidance_requires_safe_negative_probes_and_real_ci_outcomes() -> None:
+    """Text conformance preserves the procedure, not executed CI evidence."""
+    normalized_agents = " ".join(_read("AGENTS.md").lower().split())
+    for required_phrase in (
+        "collection skips and expected failures",
+        "actual process exit status",
+        "task-owned decoy files",
+        "key-only assertions",
+        "inherited provider and replica settings",
+        "sanitize reports before potentially blocking teardown",
+        "task-owned process groups",
+        "trivy image --download-db-only",
+    ):
+        assert required_phrase in normalized_agents
+
+
+def test_opencode_config_uses_only_contextual_orchestrator_free() -> None:
+    """Repository OpenCode model work must use only the canonical logical pool."""
+    raw_config = _read("opencode.jsonc")
+    config = json.loads(raw_config)
+
+    assert config["model"] == "contextual-orchestrator/orchestrator/free"
+    assert config["small_model"] == "contextual-orchestrator/orchestrator/free"
+    assert config["enabled_providers"] == ["contextual-orchestrator"]
+    assert set(config["provider"]) == {"contextual-orchestrator"}
+
+    provider = config["provider"]["contextual-orchestrator"]
+    assert provider["options"] == {
+        "baseURL": "http://127.0.0.1:8100/v1",
+        "headers": {"Authorization": "Bearer {env:CONTEXTUAL_ORCHESTRATOR_TOKEN}"},
+        "timeout": False,
+    }
+    assert set(provider["models"]) == {"orchestrator/free"}
+
+    forbidden_direct_routing = (
+        "github-models",
+        "STRIX_GITHUB_MODELS_TOKEN",
+        "https://models.github.ai/inference",
+        '"openai/gpt-5"',
+        '"deepseek/deepseek-r1-0528"',
+        '"deepseek/deepseek-v3-0324"',
+    )
+    for phrase in forbidden_direct_routing:
+        assert phrase not in raw_config

backend/tests/test_release_governance.py

@@ -72,12 +72,53 @@ def test_agent_lifecycle_governance_artifacts_stay_aligned() -> None:
     assert "owner-issued" in readme
     assert "docs/development/merge-gate-policy.md" in guidance
     assert "prove complete-delta succession" in guidance
+    assert "Superpowers systematic debugging" in guidance
+    assert "Ponytail ladder" in guidance
     assert "Do not use administrative merge bypass" in guidance
     assert "stale-context procedure" in guidance
     assert "successor's exact tree, effective diff, tests, and lineage record" in guidance
     assert research_artifact.read_bytes().startswith(b"%PDF-")
 
 
+@pytest.mark.parametrize(
+    "relative_path",
+    [
+        "AGENTS.md",
+        "docs/development/merge-gate-policy.md",
+        ".agents/skills/github-robot-review-gate/SKILL.md",
+    ],
+)
+def test_gate_guidance_requires_authorized_recoverable_changes(relative_path: str) -> None:
+    """Every linked gate procedure must retain authorization and failure rollback."""
+    guidance_text = " ".join(read_repo_text(relative_path).split())
+    assert "explicit maintainer authorization" in guidance_text
+    assert "success, failure, cancellation, or expiry" in guidance_text
+
+
+def test_agent_playbook_keeps_skill_links_and_safe_execution_boundaries() -> None:
+    """Keep local skill references runnable and prevent known unsafe copy patterns."""
+    guidance_text = read_repo_text("AGENTS.md")
+    skill_paths = re.findall(r"\]\((\.agents/skills/[^)]+/SKILL\.md)\)", guidance_text)
+    assert {
+        ".agents/skills/fix-development-mistakes/SKILL.md",
+        ".agents/skills/github-actions-privileged-pr-scan/SKILL.md",
+        ".agents/skills/github-robot-review-gate/SKILL.md",
+    } <= set(skill_paths)
+    for skill_path in skill_paths:
+        assert read_repo_text(skill_path).startswith("---\nname:")
+    assert "git config --get-all remote.origin.fetch" in guidance_text
+    assert ".headRefOid as $head" in guidance_text
+    assert "select(.commit.oid == $head)" in guidance_text
+    assert "podman system prune --all --volumes --force" not in guidance_text
+    assert "podman system check --repair --force" not in guidance_text
+    assert "--dir frontend test --runInBand" not in guidance_text
+    assert "documentation-only work" in guidance_text
+    assert "closingIssuesReferences" in guidance_text
+    assert "기존 canonical release workflow" in guidance_text
+    assert "레지스트리 게시 성공과 실제 서비스 배포를 구분" in guidance_text
+    assert "`AGENTS.md`에 지속 반영" in guidance_text
+
+
 def assert_dockerfile_stage_from(dockerfile: str, image: str, stage_alias: str) -> None:
     pattern = (
         rf"^FROM {re.escape(image)}@sha256:[0-9a-f]{{64}} AS {re.escape(stage_alias)}$"

docs/development/merge-gate-policy.md

@@ -96,14 +96,18 @@ context before the hardened Strix workflow can emit a valid result.
 
 Handling policy:
 
+This procedure requires explicit maintainer authorization for the exact ruleset
+change and substitute evidence. A delivery request alone is not authorization
+to weaken a required gate; without it, repair or rerun the canonical owner.
+
 1. Prefer branch update or rerun first.
 2. If the required context cannot be emitted until the PR lands, document the
    stale context and use only a temporary, reversible ruleset adjustment.
    Capture equivalent temporary evidence before merge, such as a trusted-base
    rerun, scanner artifact, SARIF output, or manual security review evidence
    tied to the current head SHA.
-3. Restore the `strix` required context after the hardened workflow emits it
-   successfully on the protected branch.
+3. Restore the captured configuration on success, failure, cancellation, or
+   expiry. If repair fails, restore before pursuing a different approach.
 4. Re-run required-check evidence after restore.
 
 ## PR #108/#109 evidence summary
@@ -124,7 +128,8 @@ Handling policy:
 - Any temporary ruleset change must have captured before/after JSON, owner,
   expiry, head SHA, equivalent temporary evidence, and a named restore
   condition.
-- Restore required contexts immediately after the repaired workflow emits them.
+- Restore required contexts on success, failure, cancellation, or expiry;
+  verify restoration before any further landing.
 - If the platform still rejects merge after policy-aligned settings and passing
   checks, record the rejection as an external blocker with the exact command
   output and head SHA.