diff --git a/agent-pack/CAPABILITY_MATRIX.md b/agent-pack/CAPABILITY_MATRIX.md index babb28a..5a901f2 100644 --- a/agent-pack/CAPABILITY_MATRIX.md +++ b/agent-pack/CAPABILITY_MATRIX.md @@ -14,13 +14,13 @@ | Capability | OpenCode | Codex CLI | |---|---|---| -| **Agents / roles** | SUPPORTED — `builder` (generic implementation), `arch-data-engineer` (specialist, scoped permissions), `reviewer` (read-only, restricted permissions), `planner` (read-only planning and routing), `mechanical` (deterministic low-judgment operations) | NOT YET ASSESSED | -| **Skills / contracts** | SUPPORTED — 5 skills: neuralengine, repository-review, python-project-validation, arch-linux-diagnostics, verification | NOT YET ASSESSED | -| **Global instructions** | SUPPORTED — `neuralengine-usage.md` loaded via `opencode.json` instructions array | NOT YET ASSESSED | -| **Permissions** | SUPPORTED — Agent-level permission blocks with allow/deny/ask for edit, bash, task, tools. Reviewer enforces read-only. | NOT YET ASSESSED | -| **Shell execution** | SUPPORTED — Scoped bash allowlist for `arch-data-engineer` (read-only diagnostics and validation; commit, push, destructive Git/filesystem/partitioning commands, and Ruff auto-fix denied). Restricted allowlist for `reviewer`. | NOT YET ASSESSED | -| **Repository instructions** | SUPPORTED — `AGENTS.md`, `CODEX.md`, `VISION.md`, `CONTEXT.md`, `pyproject.toml` awareness built into agent rules | NOT YET ASSESSED | -| **NeuralEngine CLI** | SUPPORTED — `neural status` and `neural search` available and used in all reviews | NOT YET ASSESSED | +| **Agents / roles** | SUPPORTED — `builder` (generic implementation), `arch-data-engineer` (specialist, scoped permissions), `reviewer` (read-only, restricted permissions), `planner` (read-only planning and routing), `mechanical` (deterministic low-judgment operations) | NOT YET ASSESSED — outside this NeuralEngine-only slice | +| **Skills / contracts** | SUPPORTED — 5 skills: neuralengine, repository-review, python-project-validation, arch-linux-diagnostics, verification | SUPPORTED WITH LIMITATIONS — NeuralEngine contract projection only; other contracts remain unmapped | +| **Global instructions** | SUPPORTED — `neuralengine-usage.md` loaded via `opencode.json` instructions array | SUPPORTED WITH LIMITATIONS — short `AGENTS.md` pointer; Codex CLI runtime discovery not exercised here | +| **Permissions** | SUPPORTED — Agent-level permission blocks with allow/deny/ask for edit, bash, task, tools. Reviewer enforces read-only. | SUPPORTED WITH LIMITATIONS — Codex host sandbox/approval controls remain authoritative; no adapter write authority | +| **Shell execution** | SUPPORTED — Scoped bash allowlist for `arch-data-engineer` (read-only diagnostics and validation; commit, push, destructive Git/filesystem/partitioning commands, and Ruff auto-fix denied). Restricted allowlist for `reviewer`. | SUPPORTED WITH LIMITATIONS — `neural` commands are ordinary host shell commands; executable/PATH/runtime behavior not verified | +| **Repository instructions** | SUPPORTED — `AGENTS.md`, `CODEX.md`, `VISION.md`, `CONTEXT.md`, `pyproject.toml` awareness built into agent rules | SUPPORTED WITH LIMITATIONS — Codex CLI native `AGENTS.md` pointer for substantive/consequential work | +| **NeuralEngine CLI** | SUPPORTED — `neural status` and `neural search` available and used in all reviews | SUPPORTED WITH LIMITATIONS — projection preserves `neural status`, targeted retrieval, and read-only boundaries; target installation not verified | | **Review** | SUPPORTED — `repository-review` skill, reviewer agent with read-only permissions, formal review format with verdict/checkpoint/validation/scope/findings | NOT YET ASSESSED | | **Verification** | SUPPORTED — reviewer agent with `verification` skill and enforced read-only command permissions (8 additional allow patterns: find, test, wc, sha256sum, diff, cmp, grep, sed). Quick Verification runs without permission prompts. | NOT YET ASSESSED | | **Certification** | SUPPORTED — Certification Report template, 3 verdicts (CERTIFIED/CERTIFIED WITH NOTES/NOT CERTIFIED), collision-safe naming, `.agent-work/certifications/` convention | NOT YET ASSESSED | @@ -30,9 +30,10 @@ ## Codex CLI assessment notes -All Codex capabilities are `NOT YET ASSESSED`. The Codex Platform Assessment -(task: `.agent-work/prompts/assess-codex-platform-v1.0.md`) is the designated -authority to evaluate Codex against this matrix. +This implementation assesses only the bounded Codex CLI NeuralEngine slice. +The remaining Codex capabilities stay `NOT YET ASSESSED`. The provider-native +assessment at `.agent-work/reviews/review-provider-native-cross-agent-neuralengine-adapters.md` +is the authority for the host findings used by this slice. The following rules apply to the Codex assessment: @@ -47,6 +48,20 @@ The following rules apply to the Codex assessment: the v1.0 Adapter API defined in [DECISIONS/architecture-freeze-v1.0.md](../DECISIONS/architecture-freeze-v1.0.md). +## Codex CLI evidence sources + +The bounded Codex CLI NeuralEngine slice is derived from: + +- `platforms/codex/AGENTS.md` — minimal project-instruction pointer. +- `platforms/codex/skills/neuralengine/SKILL.md` — controlled semantic + projection of `shared/neuralengine.md` with Codex-required front matter. +- `MANIFEST.md` — shared-to-Codex mapping and controlled-copy boundary. +- `tests/test_agent_rollout.py` — focused front-matter, pointer, and semantic + drift checks. + +These files do not claim full Codex Adapter API support, Codex Desktop support, +or provider runtime installation. + ## OpenCode evidence sources OpenCode capabilities are derived from: diff --git a/agent-pack/MANIFEST.md b/agent-pack/MANIFEST.md index 7ab0757..39ff518 100644 --- a/agent-pack/MANIFEST.md +++ b/agent-pack/MANIFEST.md @@ -2,14 +2,14 @@ ## Shared-to-platform mapping -| Authoritative source | OpenCode target | -|---|---| -| `shared/neuralengine.md` | global instruction (`neuralengine-usage.md`) and NeuralEngine skill | -| `shared/repository-review.md` | repository-review skill | -| `shared/python-validation.md` | python-project-validation skill | -| `shared/arch-linux.md` | arch-linux-diagnostics skill | -| `shared/verification.md` | verification skill (Quick, Standard, and Certification implemented) | -| `shared/task-execution-policy.md` | no platform copy (vocabulary contract, deferred consumption) | +| Authoritative source | OpenCode target | Codex CLI target | +|---|---|---| +| `shared/neuralengine.md` | global instruction (`neuralengine-usage.md`) and NeuralEngine skill | `platforms/codex/skills/neuralengine/SKILL.md` (controlled copy; install target is `.agents/skills/neuralengine/SKILL.md`) | +| `shared/repository-review.md` | repository-review skill | not mapped in this slice | +| `shared/python-validation.md` | python-project-validation skill | not mapped in this slice | +| `shared/arch-linux.md` | arch-linux-diagnostics skill | not mapped in this slice | +| `shared/verification.md` | verification skill (Quick, Standard, and Certification implemented) | not mapped in this slice | +| `shared/task-execution-policy.md` | no platform copy (vocabulary contract, deferred consumption) | no platform copy (vocabulary contract, deferred consumption) | ## Platform-specific files (no shared equivalent) @@ -19,6 +19,7 @@ - `agents/reviewer.md` - `agents/planner.md` - `agents/mechanical.md` +- `codex/AGENTS.md` These files are platform-specific configuration artifacts. They have no corresponding shared source in this pack. diff --git a/agent-pack/README.md b/agent-pack/README.md index fcc9e39..c1a2843 100644 --- a/agent-pack/README.md +++ b/agent-pack/README.md @@ -10,10 +10,11 @@ repository—not a separate product. ## Scope - Six authoritative shared workflow files (Verification Framework added in v0.2.0, Task Execution Policy added in v0.4.0). -- One platform variant (OpenCode) derived from the user's current, working - OpenCode configuration. -- Placeholder directories for future Codex, Claude Code, and Antigravity - platform variants. +- One complete platform variant (OpenCode) derived from the user's current, + working OpenCode configuration. +- One bounded Codex CLI NeuralEngine skill projection. +- Placeholder directories for future Claude Code and Antigravity platform + variants. This pack does not modify NeuralEngine runtime behavior, Brain persistence, schemas, migrations, user data, or public APIs. @@ -47,7 +48,7 @@ contract and introduces the generic builder agent: | Task Execution Policy foundation review | READY FOR INDEPENDENT REVIEW | | ACP independent review | PASS | | OpenCode | Supported | -| Codex | Placeholder (not implemented) | +| Codex CLI NeuralEngine slice | Supported with limitations (CLI only) | | Claude Code | Placeholder (not implemented) | | Antigravity | Placeholder (not implemented) | @@ -211,6 +212,7 @@ Shared contracts: OpenCode platform implementation: - [platforms/opencode/](platforms/opencode/) — OpenCode adapter and skills. +- [platforms/codex/](platforms/codex/) — Codex CLI NeuralEngine adapter slice. - [platforms/opencode/agents/planner.md](platforms/opencode/agents/planner.md) — Read-only planning and routing agent. - [platforms/opencode/agents/builder.md](platforms/opencode/agents/builder.md) — Generic builder agent (new in v0.4.0). - [platforms/opencode/agents/arch-data-engineer.md](platforms/opencode/agents/arch-data-engineer.md) — Specialist implementation agent. diff --git a/agent-pack/platforms/codex/AGENTS.md b/agent-pack/platforms/codex/AGENTS.md new file mode 100644 index 0000000..9f6757a --- /dev/null +++ b/agent-pack/platforms/codex/AGENTS.md @@ -0,0 +1,7 @@ +# Codex CLI NeuralEngine pointer + +For substantive or consequential work, consider the repository +`neuralengine` skill at `.agents/skills/neuralengine/SKILL.md`. + +The semantic authority is `agent-pack/shared/neuralengine.md`. This pointer +does not duplicate or redefine that contract. diff --git a/agent-pack/platforms/codex/README.md b/agent-pack/platforms/codex/README.md index 0a69785..6ed336c 100644 --- a/agent-pack/platforms/codex/README.md +++ b/agent-pack/platforms/codex/README.md @@ -1,9 +1,43 @@ -# Codex Platform +# Codex CLI Platform -**Status:** Not implemented as of Agent Pack v0.2.0. +**Status:** NeuralEngine thin adapter implemented for Codex CLI only. -**Intended future mapping:** Adapt the five shared contracts to Codex agent -configuration format. Map OpenCode skills and agents to equivalent Codex -constructs. +This adapter is a controlled projection of +`agent-pack/shared/neuralengine.md`. It does not implement Codex Desktop or +any other provider, and it does not modify NeuralEngine runtime behavior, +Brain persistence, schemas, APIs, or user-global Codex configuration. -**Current version:** Not supported. This directory exists as a placeholder. +## Adapter files + +- `AGENTS.md` — minimal project-instruction pointer; merge this pointer into a + target repository's project instructions without replacing unrelated rules. +- `skills/neuralengine/SKILL.md` — Codex-compatible skill projection with only + the required `name` and `description` front matter. + +The skill body is a controlled copy of the shared contract. Drift validation +requires the body after front matter removal to remain byte-equal to +`agent-pack/shared/neuralengine.md`. + +## Manual installation mapping + +Installation is explicit and manual, consistent with the Agent Pack +architecture: + +```text +skills/neuralengine/SKILL.md +→ /.agents/skills/neuralengine/SKILL.md +``` + +The `AGENTS.md` content is a pointer to merge into the target repository's +project instructions. This package does not provide an installer, write to +`~/.codex`, or claim Desktop support. + +## Limitations + +- Codex CLI is the only supported surface in this adapter. +- Codex Desktop discovery parity is not established by this slice. +- Availability of the `neural` executable, `PATH`, Brain access, and runtime + command behavior must be verified in the target environment. +- Host permissions and approvals remain Codex controls; this adapter grants no + Brain-write, staging, commit, push, merge, tag, release, or publication + authority. diff --git a/agent-pack/platforms/codex/skills/neuralengine/SKILL.md b/agent-pack/platforms/codex/skills/neuralengine/SKILL.md new file mode 100644 index 0000000..2d69e45 --- /dev/null +++ b/agent-pack/platforms/codex/skills/neuralengine/SKILL.md @@ -0,0 +1,341 @@ +--- +name: neuralengine +description: Use NeuralEngine as the durable project knowledge, decision, experience, and playbook layer for substantive repository, architecture, review, diagnostic, planning, and authorized Brain tasks. +--- +# Mandatory NeuralEngine Usage + +NeuralEngine is the default durable knowledge and decision layer for all agents and models. + +Repository sources describe the current implementation. NeuralEngine may contain prior decisions, experience, knowledge, playbooks, and provenance that are not recoverable from the current working tree alone. + +## Authority model + +Treat sources according to their role: + +1. repository source defines the current implementation; +2. repository instructions define local execution constraints; +3. NeuralEngine provides durable knowledge, decisions, experience, playbooks, and provenance; +4. current command output provides direct runtime evidence; +5. external documentation provides supporting context. + +Do not use NeuralEngine records to override current repository source without explaining the conflict. + +Do not assume a record is authoritative merely because it exists. + +Evaluate: + +* lifecycle state; +* provenance; +* project key; +* source record; +* timestamps; +* superseding records; +* activation or revision state; +* applicability to the current task. + +## Start of work + +At the start of every substantive task, run: + +`neural status` + +A substantive task includes repository work, review, diagnosis, assessment, planning, implementation, or architecture analysis. + +Simple requests that only summarize already loaded instructions or skill contents do not require a new `neural status` call. + +Record whether NeuralEngine is: + +* available; +* unavailable; +* degraded; +* misconfigured; +* connected to the expected Brain. + +If `neural status` fails: + +1. preserve the exact error; +2. determine whether repository-only work can continue safely; +3. do not claim NeuralEngine usage; +4. record the limitation in the task report. + +## Search decision + +Before substantive analysis, review, diagnosis, planning, or editing, decide whether prior project knowledge, decisions, experience, or playbooks are relevant. + +Use `neural search` when prior durable knowledge may materially affect: + +* architecture; +* domain boundaries; +* persistence; +* migrations; +* security; +* public behavior; +* release decisions; +* previous incidents; +* diagnostic playbooks; +* project-specific conventions; +* prior accepted or rejected approaches. + +Repository source may be sufficient for: + +* exact current implementation inspection; +* isolated mechanical changes; +* syntax or formatting corrections; +* direct validation of an already defined task; +* runtime diagnosis based entirely on current logs. + +The absence of a search result is evidence only that no matching record was returned. It does not prove that no relevant knowledge exists. + +If relevant: + +1. run `neural search`; +2. record the exact query; +3. record returned record IDs and provenance; +4. explain briefly how the retrieved result affected the work. + +If not relevant: + +1. state explicitly that no NeuralEngine search was required; +2. explain why repository sources or current system evidence were sufficient. + +Do not claim NeuralEngine knowledge use based only on running `neural status`. + +## Query construction + +Use narrow, explicit queries. + +Start with one best query. + +Run a second query only when: + +- the first query reveals a distinct authoritative term; +- separate lifecycle or provenance records are required; +- the task spans two materially different contracts; +- the first result is ambiguous but establishes a better exact query. + +Do not issue repeated speculative searches merely because earlier searches returned no results. + +For ordinary repository work, use no more than two queries unless the task is explicitly a Brain investigation, migration, architecture assessment, or historical audit. + +Prefer queries containing: + +* project name or project key; +* affected domain; +* exact contract; +* lifecycle stage; +* relevant component; +* issue or decision being investigated. + +Avoid vague queries such as `architecture`, `bugs`, or `project decisions`. + +Record every exact query used. + +Do not silently rewrite the query in the final report. + +## Search result handling + +For every relevant result, record: + +* record ID; +* record type; +* project key; +* lifecycle state; +* provenance; +* source or parent record when present; +* why it is relevant; +* how it affected the task. + +Distinguish record types: + +### Observation + +Raw or normalized evidence about something that occurred. + +Do not treat an Observation as a durable conclusion. + +### Experience + +Interpreted evidence from completed work or outcomes. + +Use it as operational learning, not as universal truth. + +### Knowledge + +Durable, reusable understanding promoted through the defined lifecycle. + +Check its provenance and integrity boundaries before relying on it. + +### Playbook + +Reusable operational procedure. + +Verify: + +* active revision; +* applicability; +* inputs; +* constraints; +* expected outcome; +* execution provenance requirements. + +### PlaybookRun + +Evidence that a specific playbook revision was executed. + +Do not infer execution from playbook existence alone. + +### Evaluation + +Assessment of a run or outcome. + +Check the evaluated target and evidence. + +### EvolutionProposal + +Proposal for improving a playbook or durable behavior. + +It is not automatically accepted or active. + +### DecisionReview + +Structured review of a decision and its outcome. + +Check status, outcome evidence, and promotion state. + +## Provenance + +Never report only a record ID when provenance is available. + +Provenance may include: + +* source repository; +* source checkpoint; +* source review; +* originating observation; +* originating experience; +* promotion path; +* playbook revision; +* activation; +* application; +* execution record; +* user authorization. + +When provenance is missing or incomplete: + +1. state the limitation; +2. reduce confidence; +3. do not silently infer the missing chain. + +## Conflicts + +When NeuralEngine and repository source appear to conflict: + +1. identify the exact conflicting statements; +2. determine whether the Brain record is stale, superseded, or scoped differently; +3. prefer current implementation for present behavior; +4. preserve durable decisions that still apply; +5. report the conflict explicitly. + +Do not automatically update Brain records. + +Do not automatically modify repository source to match an old record. + +## Read boundary + +Read-only NeuralEngine operations are allowed without additional approval. + +This includes: + +* `neural status`; +* `neural search`; +* reading returned records and provenance; +* reading record details; +* inspecting provenance; +* inspecting lifecycle state; +* inspecting playbook revisions and runs. + +Do not describe an operation as read-only unless it cannot persist or promote data. + +## Brain write boundary + +Any Brain write requires explicit user authorization. + +Before requesting authorization, provide a preview containing: + +* proposed record type; +* proposed project key; +* proposed title or identifier; +* proposed content summary; +* source evidence; +* provenance; +* intended lifecycle state; +* expected effect; +* whether the write creates, updates, promotes, activates, or evaluates anything. + +Do not perform any of the following without explicit authorization: + +* create a record; +* update a record; +* promote Experience to Knowledge; +* promote DecisionReview to Experience; +* create or revise a Playbook; +* activate a Playbook revision; +* record a PlaybookRun; +* create an Evaluation; +* create an EvolutionProposal; +* change lifecycle state; +* backfill provenance; +* repair Brain data. + +Authorization for one write does not authorize later writes. + +## Lifecycle boundaries + +Do not automatically promote records between lifecycle stages. + +Creation, review, acceptance, activation, application, evaluation, and evolution are separate actions. + +Do not collapse: + +* Observation into Experience; +* Experience into Knowledge; +* DecisionReview into Experience; +* PlaybookRevision into activation; +* activation into application; +* application into PlaybookRun; +* PlaybookRun into Evaluation; +* Evaluation into EvolutionProposal. + +Each transition requires its own contract and authorization where applicable. + +## Required evidence + +Every substantive task report must contain a `NeuralEngine usage` section containing: + +* the result of `neural status`; +* whether `neural search` was used; +* exact search queries and returned record IDs when used; +* provenance; +* a brief explanation of how retrieved knowledge affected the work; +* or an explicit explanation why repository sources or current system evidence were sufficient and no search was needed. + +When the task produces a review file, include this evidence in that file. + +Otherwise include it in the final task report. + +Do not claim NeuralEngine usage based only on running `neural status`. + +## Completion rules + +Before considering NeuralEngine-related work complete: + +* verify the exact repository checkpoint; +* verify the project key; +* verify record IDs; +* verify provenance; +* verify lifecycle state; +* verify whether any write occurred; +* verify that every write had explicit authorization; +* verify that no automatic promotion occurred. + +Do not commit or push repository changes without separate explicit authorization. diff --git a/tests/test_agent_rollout.py b/tests/test_agent_rollout.py index 72494e8..7e83496 100644 --- a/tests/test_agent_rollout.py +++ b/tests/test_agent_rollout.py @@ -31,6 +31,41 @@ def _source_agent(name: str) -> Path: return _source_root() / "agent-pack" / "platforms" / "opencode" / "agents" / name +def _source_codex_skill() -> Path: + """Return the controlled Codex NeuralEngine skill projection.""" + return ( + _source_root() + / "agent-pack" + / "platforms" + / "codex" + / "skills" + / "neuralengine" + / "SKILL.md" + ) + + +def _source_codex_pointer() -> Path: + """Return the controlled Codex project-instruction pointer.""" + return _source_root() / "agent-pack" / "platforms" / "codex" / "AGENTS.md" + + +def _source_shared_neuralengine() -> Path: + """Return the authoritative shared NeuralEngine contract.""" + return _source_root() / "agent-pack" / "shared" / "neuralengine.md" + + +def _skill_body(content: str) -> str: + """Return a skill body after the required YAML front matter.""" + lines = content.splitlines(keepends=True) + assert lines and lines[0].strip() == "---" + closing = next( + (index for index, line in enumerate(lines[1:], start=1) if line.strip() == "---"), + None, + ) + assert closing is not None + return "".join(lines[closing + 1 :]) + + def _sha256(path: Path) -> str: """Return SHA-256 hex digest of a file.""" return hashlib.sha256(path.read_bytes()).hexdigest() @@ -800,3 +835,37 @@ def test_five_agent_install_preserves_all(self, tmp_path: Path) -> None: installed = {p.name for p in target_dir.iterdir()} assert installed == set(names) + + +class TestCodexNeuralEngineAdapter: + """Tests for the bounded Codex CLI NeuralEngine adapter projection.""" + + def test_codex_skill_exists_at_controlled_platform_path(self) -> None: + """Codex skill is packaged under the platform-controlled source path.""" + assert _source_codex_skill().is_file() + + def test_codex_skill_has_only_required_frontmatter(self) -> None: + """Codex projection has only the required skill metadata.""" + lines = _source_codex_skill().read_text(encoding="utf-8").splitlines() + assert lines[0] == "---" + closing = lines.index("---", 1) + assert lines[1:closing] == [ + "name: neuralengine", + "description: Use NeuralEngine as the durable project knowledge, decision, experience, and playbook layer for substantive repository, architecture, review, diagnostic, planning, and authorized Brain tasks.", + ] + + def test_codex_skill_body_matches_shared_contract(self) -> None: + """Codex projection cannot silently diverge from shared semantics.""" + skill = _source_codex_skill().read_text(encoding="utf-8") + shared = _source_shared_neuralengine().read_text(encoding="utf-8") + assert _skill_body(skill) == shared + + def test_codex_pointer_references_without_redefining_contract(self) -> None: + """Project pointer names the skill and canonical source without policy duplication.""" + content = _source_codex_pointer().read_text(encoding="utf-8") + assert ".agents/skills/neuralengine/SKILL.md" in content + assert "agent-pack/shared/neuralengine.md" in content + assert "does not duplicate or redefine that contract" in content + assert "## Authority model" not in content + assert "neural knowledge search" not in content + assert "Brain-write" not in content