cortex-loop 0.1.0a1__py3-none-any.whl

cortex_ops_cli/_runtime_profile_templates.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+
+
+def render_claude_settings_json(*, python_executable: str | None, schema_version: str) -> str:
+    text = _load_repo_template(
+        "claude/settings.json",
+        f"""{{
+  "hooks": {{
+    "PreToolUse": [
+      {{
+        "hooks": [
+          {{
+            "type": "command",
+            "command": "python3 -m cortex.hooks.pre_tool_use --schema-version {schema_version}"
+          }}
+        ]
+      }}
+    ],
+    "PostToolUse": [
+      {{
+        "hooks": [
+          {{
+            "type": "command",
+            "command": "python3 -m cortex.hooks.post_tool_use --schema-version {schema_version}"
+          }}
+        ]
+      }}
+    ],
+    "Stop": [
+      {{
+        "hooks": [
+          {{
+            "type": "command",
+            "command": "python3 -m cortex.hooks.stop --schema-version {schema_version}"
+          }}
+        ]
+      }}
+    ]
+  }}
+}}
+""",
+    )
+    if not python_executable:
+        return text
+    exe = shlex.quote(str(Path(python_executable)))
+    return text.replace("python3 -m cortex.hooks.", f"{exe} -m cortex.hooks.")
+
+
+def render_gemini_settings_json(*, python_executable: str | None) -> str:
+    text = _load_repo_template(
+        "gemini/settings.json",
+        """{
+  "hooksConfig": {
+    "enabled": true
+  },
+  "model": {
+    "maxSessionTurns": 50,
+    "compressionThreshold": 0.35
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -m cortex_ops_cli.gemini_hooks SessionStart",
+            "name": "cortex-session-start",
+            "timeout": 30000
+          }
+        ]
+      }
+    ],
+    "BeforeTool": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -m cortex_ops_cli.gemini_hooks BeforeTool",
+            "name": "cortex-before-tool",
+            "timeout": 30000
+          }
+        ]
+      }
+    ],
+    "AfterTool": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -m cortex_ops_cli.gemini_hooks AfterTool",
+            "name": "cortex-after-tool",
+            "timeout": 30000
+          }
+        ]
+      }
+    ],
+    "BeforeAgent": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -m cortex_ops_cli.gemini_hooks BeforeAgent",
+            "name": "cortex-before-agent",
+            "timeout": 30000
+          }
+        ]
+      }
+    ],
+    "AfterAgent": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -m cortex_ops_cli.gemini_hooks AfterAgent",
+            "name": "cortex-after-agent",
+            "timeout": 60000
+          }
+        ]
+      }
+    ]
+  }
+}
+""",
+    )
+    if not python_executable:
+        return text
+    exe = shlex.quote(str(Path(python_executable)))
+    return text.replace("python3 -m cortex_ops_cli.gemini_hooks", f"{exe} -m cortex_ops_cli.gemini_hooks")
+
+
+def render_claude_md() -> str:
+    return _load_repo_template(
+        "claude/CLAUDE.md",
+        """# Cortex Runtime Instructions (Claude Code)
+
+## Purpose
+
+Cortex is enforcing completion-time quality gates on this project through Claude Code hooks.
+
+## Files Written by `cortex runtime install --profile claude`
+
+- `.claude/settings.json`
+- `.claude/CLAUDE.md`
+
+## Enforcement Expectations
+
+- Treat hook output as policy, not optional advice.
+- Keep changes small and load-bearing.
+- Prefer structured stop payload fields (or a `stop_fields` object) over message-trailer fallback.
+
+Cortex expects challenge coverage at stop:
+- `null_inputs`
+- `boundary_values`
+- `error_handling`
+- `graveyard_regression`
+
+In strict mode, invariant failure should be treated as a revert signal.
+
+If an approach failed, include `failed_approach` with:
+- `summary`
+- `reason`
+- `files`
+
+If requirement traceability is configured, include `requirement_audit` and all required IDs.
+
+When claiming completion facts, include `truth_claims`:
+- `modified_files`: files you actually changed
+- `tests_ran`: test commands you actually ran
+
+Fallback trailer format:
+
+`STOP_FIELDS_JSON: {"challenge_coverage":{"null_inputs":true,"boundary_values":true,"error_handling":true,"graveyard_regression":true},"truth_claims":{"modified_files":["src/app.py"],"tests_ran":["pytest -q"]},"failed_approach":{"summary":"...","reason":"...","files":["path/to/file"]}}`
+
+Use valid one-line JSON.
+
+## Adapter Contract
+
+- Adapter path in `cortex.toml`: `cortex.adapters.claude:ClaudeAdapter`
+- Required hook commands: `PreToolUse`, `PostToolUse`, `Stop`
+- Runtime hook schema is pinned in `.claude/settings.json` (`claude_native_v1`, rollback `legacy_json_v0`)
+
+## Known Caveats
+
+- `SessionStart` is not consistently emitted by every Claude Code build.
+- If `SessionStart` is unavailable, rely on `PreToolUse`, `PostToolUse`, and `Stop`, and run `cortex repomap --root .` explicitly when needed.
+- Each hook module also accepts `--root` and `--config` for manual testing.
+""",
+    )
+
+
+def render_gemini_md() -> str:
+    return _load_repo_template(
+        "gemini/GEMINI.md",
+        """# Cortex Runtime Instructions (Gemini CLI)
+
+## Purpose
+
+Cortex is enforcing completion-time quality gates on this project through Gemini CLI hooks.
+
+## Files Written by `cortex runtime install --profile gemini`
+
+- `.gemini/settings.json`
+- `.gemini/GEMINI.md`
+
+## Enforcement Expectations
+
+When producing final responses (`AfterAgent`), include Cortex stop markers
+directly in the final response body using one-line `STOP_FIELDS_JSON:` with
+valid JSON. Do not emit the marker through a shell command or by writing it to
+another file.
+
+In strict mode, each `challenge_coverage` category must be an object with
+`covered: true` and a non-empty `evidence` list. Bare booleans are not enough.
+For passing `requirement_audit.items`, use exact `status: "pass"` or
+`status: "fail"` and include `evidence` for every pass item.
+
+Example:
+
+`STOP_FIELDS_JSON: {"challenge_coverage":{"null_inputs":{"covered":true,"evidence":["src/module.py"]},"boundary_values":{"covered":true,"evidence":["cmd:python -m pytest -q tests/test_normalize_port.py"]},"error_handling":{"covered":true,"evidence":["cmd:python -m pytest -q tests/test_normalize_port.py"]},"graveyard_regression":{"covered":true,"evidence":["tests/test_normalize_port.py"]}},"truth_claims":{"tests_ran":["python -m pytest -q tests/test_normalize_port.py"],"modified_files":["src/module.py"]},"requirement_audit":{"items":[{"id":"BUGFIX","status":"pass","evidence":["src/module.py"]},{"id":"TEST","status":"pass","evidence":["cmd:python -m pytest -q tests/test_normalize_port.py"]}],"completeness_verdict":"pass"}}`
+
+If markers are omitted or malformed, Cortex will treat the completion claim as incomplete and return correction feedback.
+
+## Adapter And Bridge Contract
+
+- Hook bridge entrypoint: `python3 -m cortex_ops_cli.gemini_hooks <HookEvent>`
+- Required hook events: `SessionStart`, `BeforeTool`, `AfterTool`, `BeforeAgent`, `AfterAgent`
+- Adapter path in `cortex.toml`: `cortex.adapters.gemini:GeminiAdapter`
+
+## Known Caveats And Status
+
+- Non-blocking Cortex warnings are surfaced back to Gemini as `systemMessage` text.
+- Blocking outcomes return hook `decision=deny` with a reason.
+- Per-turn executive anchor delivery is handled by the `BeforeAgent` hook (`hookSpecificOutput.additionalContext`).
+- Runtime-specific watchlist details are tracked in `docs/ADAPTERS.md`.
+""",
+    )
+
+
+def render_openai_bridge_profile_json(*, python_executable: str | None, schema_version: str) -> str:
+    text = _load_repo_template(
+        "openai/cortex_openai_bridge.json",
+        f"""{{
+  "schema_version": "{schema_version}",
+  "bridge": {{
+    "command": "python3 -m cortex_ops_cli.openai_app_server_bridge run --schema-version {schema_version}",
+    "codex_bin": "codex",
+    "listen": "stdio://"
+  }}
+}}
+""",
+    )
+    if not python_executable:
+        return text
+    exe = shlex.quote(str(Path(python_executable)))
+    return text.replace(
+        "python3 -m cortex_ops_cli.openai_app_server_bridge",
+        f"{exe} -m cortex_ops_cli.openai_app_server_bridge",
+    )
+
+
+def render_openai_md() -> str:
+    return _load_repo_template(
+        "openai/OPENAI.md",
+        """# Cortex Runtime Instructions (OpenAI/Codex App Server)
+
+## Purpose
+
+Cortex uses the OpenAI App Server bridge to enforce pre-tool, post-tool, and stop gates.
+
+## Files Written by `cortex runtime install --profile openai`
+
+- `.codex/cortex_openai_bridge.json`
+- `.codex/OPENAI.md`
+
+## Enforcement Expectations
+
+When producing final responses through Codex App Server, include Cortex stop
+markers directly in the final response body using the exact one-line literal
+prefix `STOP_FIELDS_JSON:` followed by valid JSON. Do not emit the marker
+through a shell command or by writing it to another file.
+
+In strict mode, each `challenge_coverage` category must be an object with
+`covered: true` and a non-empty `evidence` list. Bare booleans are not enough.
+Use repo-verifiable evidence tokens such as repo-relative file paths with line
+references (`src/module.py:8`, `tests/test_module.py:12`) or executed-command
+markers (`cmd:python -m pytest -q tests/test_normalize_port.py`). Do not use pytest node ids,
+narrative summaries, or other evidence strings the kernel cannot verify from
+the workspace.
+For every `requirement_audit.items` entry, use exact `status: "pass"` or
+`status: "fail"`. Do not use custom statuses such as `blocked` or `not_done`.
+Include `evidence` for every pass item, and for any fail item used to justify a
+truthful incomplete outcome.
+
+If completion cannot be claimed honestly, still end with one-line
+`STOP_FIELDS_JSON` carrying a structured truthful failure such as
+`stuck_declaration`, `failed_approach`, real `truth_claims` gaps, or real
+`requirement_audit` gaps. Do not rely on prose-only refusal text.
+
+Example:
+
+`STOP_FIELDS_JSON: {"challenge_coverage":{"null_inputs":{"covered":true,"evidence":["src/module.py"]},"boundary_values":{"covered":true,"evidence":["cmd:python -m pytest -q tests/test_normalize_port.py"]},"error_handling":{"covered":true,"evidence":["cmd:python -m pytest -q tests/test_normalize_port.py"]},"graveyard_regression":{"covered":true,"evidence":["tests/test_normalize_port.py"]}},"truth_claims":{"tests_ran":["python -m pytest -q tests/test_normalize_port.py"],"modified_files":["src/module.py"]},"requirement_audit":{"items":[{"id":"BUGFIX","status":"pass","evidence":["src/module.py"]},{"id":"TEST","status":"pass","evidence":["cmd:python -m pytest -q tests/test_normalize_port.py"]}],"completeness_verdict":"pass"}}`
+
+## Enforcement-Ready Mode
+
+- `cortex init` starts with advisory hooks because that is the safe starter state.
+- A user who wants blocking enforcement can opt in through the shipped `cortex.toml` hooks surface after `cortex runtime install --profile openai`:
+
+```toml
+[hooks]
+mode = "strict"
+fail_on_missing_challenge_coverage = true
+require_requirement_audit = true
+fail_on_requirement_audit_gap = true
+require_structured_stop_payload = true
+allow_message_stop_fallback = false
+```
+
+## Adapter And Bridge Contract
+
+- Bridge entrypoint: `python3 -m cortex_ops_cli.openai_app_server_bridge run`
+- Schema pin: `--schema-version openai_app_server_v1`
+- Profile file: `.codex/cortex_openai_bridge.json`
+- Adapter path in `cortex.toml`: `cortex.adapters.openai:OpenAIAdapter`
+
+## Known Caveats And Status
+
+- If command approval decline cannot be proven to block execution, the bridge must report `pre_tool_use_nonblocking_approval`.
+- Runs with unresolved coverage gaps are diagnostic and non-promotable.
+- OpenAI remains an experimental runtime surface until current live gates prove the boundary-critical lanes on the tested stable release.
+""",
+    )
+
+
+def _load_repo_template(rel_path: str, fallback: str) -> str:
+    repo_template = Path(__file__).resolve().parents[1] / rel_path
+    if repo_template.exists():
+        return repo_template.read_text(encoding="utf-8")
+    return fallback