diff --git a/agent-pack/CAPABILITY_MATRIX.md b/agent-pack/CAPABILITY_MATRIX.md index 1627d70..6c714ca 100644 --- a/agent-pack/CAPABILITY_MATRIX.md +++ b/agent-pack/CAPABILITY_MATRIX.md @@ -12,21 +12,21 @@ ## Matrix -| Capability | OpenCode | Codex CLI | Goose CLI/Desktop | Claude Code/Desktop Code | -|---|---|---|---|---| -| **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 | NOT YET ASSESSED — custom agents are outside this bounded slice | NOT YET ASSESSED — custom agents are outside this bounded 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 | SUPPORTED WITH LIMITATIONS — NeuralEngine contract projection only; other contracts remain unmapped | 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 | SUPPORTED WITH LIMITATIONS — short `AGENTS.md` pointer; Desktop launcher discovery remains environment-dependent | SUPPORTED WITH LIMITATIONS — native `CLAUDE.md` pointer; Desktop Code shares project configuration | -| **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 | SUPPORTED WITH LIMITATIONS — Goose host permission/approval controls remain authoritative; no adapter write authority | SUPPORTED WITH LIMITATIONS — Claude host permission modes 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 | SUPPORTED WITH LIMITATIONS — Developer shell tools are documented; executable/PATH/runtime behavior is target-environment dependent | SUPPORTED WITH LIMITATIONS — CLI shell execution is available; Desktop/local environment and `neural` availability remain target-dependent | -| **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 | SUPPORTED WITH LIMITATIONS — Goose project context files are documented; exact Desktop conflict precedence remains unverified | SUPPORTED WITH LIMITATIONS — `CLAUDE.md` is native; `AGENTS.md` requires an explicit import/reference | -| **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 | SUPPORTED WITH LIMITATIONS — projection preserves `neural status`, targeted retrieval, and read-only boundaries; target installation and Desktop command availability not verified | SUPPORTED WITH LIMITATIONS — projection preserves `neural status`, targeted retrieval, and read-only boundaries; Desktop Code runtime availability not locally verified | -| **Review** | SUPPORTED — `repository-review` skill, reviewer agent with read-only permissions, formal review format with verdict/checkpoint/validation/scope/findings | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | -| **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 | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | -| **Certification** | SUPPORTED — Certification Report template, 3 verdicts (CERTIFIED/CERTIFIED WITH NOTES/NOT CERTIFIED), collision-safe naming, `.agent-work/certifications/` convention | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | -| **Model selection** | SUPPORTED — Model configured in OpenCode runtime. Agent Pack is model-agnostic (DeepSeek V4 Pro Max, GPT-5.6 Sol Medium, others) | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | -| **Non-interactive execution** | SUPPORTED WITH LIMITATIONS — Bash commands execute non-interactively. Human confirmation required only for restricted operations per permission model. | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | -| **Artifact generation** | SUPPORTED — Review artifacts, certification reports, documentation files generated as markdown. No code generation or template engines. | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | +| Capability | OpenCode | Codex CLI | Goose CLI/Desktop | Claude Code/Desktop Code | Copilot 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 — outside this NeuralEngine-only slice | NOT YET ASSESSED — custom agents are outside this bounded slice | NOT YET ASSESSED — custom agents are outside this bounded slice | NOT YET ASSESSED — custom agents are outside this bounded 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 | SUPPORTED WITH LIMITATIONS — NeuralEngine contract projection only; other contracts remain unmapped | SUPPORTED WITH LIMITATIONS — NeuralEngine contract projection only; other contracts remain unmapped | 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 | SUPPORTED WITH LIMITATIONS — short `AGENTS.md` pointer; Desktop launcher discovery remains environment-dependent | SUPPORTED WITH LIMITATIONS — native `CLAUDE.md` pointer; Desktop Code shares project configuration | SUPPORTED WITH LIMITATIONS — CLI instruction locations are documented; no extra pointer is required by the skill mechanism | +| **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 | SUPPORTED WITH LIMITATIONS — Goose host permission/approval controls remain authoritative; no adapter write authority | SUPPORTED WITH LIMITATIONS — Claude host permission modes remain authoritative; no adapter write authority | SUPPORTED WITH LIMITATIONS — read-only tools are automatic; modifying tools require host approval; 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 | SUPPORTED WITH LIMITATIONS — Developer shell tools are documented; executable/PATH/runtime behavior is target-environment dependent | SUPPORTED WITH LIMITATIONS — CLI shell execution is available; Desktop/local environment and `neural` availability remain target-dependent | SUPPORTED WITH LIMITATIONS — CLI shell execution is documented; target `neural` availability not locally 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 | SUPPORTED WITH LIMITATIONS — Goose project context files are documented; exact Desktop conflict precedence remains unverified | SUPPORTED WITH LIMITATIONS — `CLAUDE.md` is native; `AGENTS.md` requires an explicit import/reference | SUPPORTED WITH LIMITATIONS — `AGENTS.md` and `.github/copilot-instructions.md` are documented CLI instruction locations; combined precedence is not a total order | +| **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 | SUPPORTED WITH LIMITATIONS — projection preserves `neural status`, targeted retrieval, and read-only boundaries; target installation and Desktop command availability not verified | SUPPORTED WITH LIMITATIONS — projection preserves `neural status`, targeted retrieval, and read-only boundaries; Desktop Code runtime availability not locally verified | SUPPORTED WITH LIMITATIONS — projection preserves `neural status`, targeted retrieval, and read-only boundaries; target installation not locally verified | +| **Review** | SUPPORTED — `repository-review` skill, reviewer agent with read-only permissions, formal review format with verdict/checkpoint/validation/scope/findings | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | +| **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 | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | +| **Certification** | SUPPORTED — Certification Report template, 3 verdicts (CERTIFIED/CERTIFIED WITH NOTES/NOT CERTIFIED), collision-safe naming, `.agent-work/certifications/` convention | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | +| **Model selection** | SUPPORTED — Model configured in OpenCode runtime. Agent Pack is model-agnostic (DeepSeek V4 Pro Max, GPT-5.6 Sol Medium, others) | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | +| **Non-interactive execution** | SUPPORTED WITH LIMITATIONS — Bash commands execute non-interactively. Human confirmation required only for restricted operations per permission model. | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | +| **Artifact generation** | SUPPORTED — Review artifacts, certification reports, documentation files generated as markdown. No code generation or template engines. | NOT YET ASSESSED | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | NOT YET ASSESSED — outside this bounded slice | ## Codex CLI assessment notes diff --git a/agent-pack/MANIFEST.md b/agent-pack/MANIFEST.md index 33a9820..c18cede 100644 --- a/agent-pack/MANIFEST.md +++ b/agent-pack/MANIFEST.md @@ -2,14 +2,14 @@ ## Shared-to-platform mapping -| Authoritative source | OpenCode target | Codex CLI target | Goose CLI/Desktop target | Claude Code/Desktop Code 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`) | `platforms/goose/skills/neuralengine/SKILL.md` (controlled copy; install target is `.agents/skills/neuralengine/SKILL.md`) | `platforms/claude/skills/neuralengine/SKILL.md` (controlled copy; install target is `.claude/skills/neuralengine/SKILL.md`) | -| `shared/repository-review.md` | repository-review skill | not mapped in this slice | not mapped in this slice | not mapped in this slice | -| `shared/python-validation.md` | python-project-validation skill | not mapped in this slice | not mapped in this slice | not mapped in this slice | -| `shared/arch-linux.md` | arch-linux-diagnostics skill | not mapped in this slice | not mapped in this slice | not mapped in this slice | -| `shared/verification.md` | verification skill (Quick, Standard, and Certification implemented) | not mapped in this slice | not mapped in this slice | not mapped in this slice | -| `shared/task-execution-policy.md` | no platform copy (vocabulary contract, deferred consumption) | no platform copy (vocabulary contract, deferred consumption) | no platform copy (vocabulary contract, deferred consumption) | no platform copy (vocabulary contract, deferred consumption) | +| Authoritative source | OpenCode target | Codex CLI target | Goose CLI/Desktop target | Claude Code/Desktop Code target | Copilot 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`) | `platforms/goose/skills/neuralengine/SKILL.md` (controlled copy; install target is `.agents/skills/neuralengine/SKILL.md`) | `platforms/claude/skills/neuralengine/SKILL.md` (controlled copy; install target is `.claude/skills/neuralengine/SKILL.md`) | `platforms/copilot/skills/neuralengine/SKILL.md` (controlled copy; install target is `.github/skills/neuralengine/SKILL.md`) | +| `shared/repository-review.md` | repository-review skill | not mapped in this slice | not mapped in this slice | not mapped in this slice | not mapped in this slice | +| `shared/python-validation.md` | python-project-validation skill | not mapped in this slice | not mapped in this slice | not mapped in this slice | not mapped in this slice | +| `shared/arch-linux.md` | arch-linux-diagnostics skill | not mapped in this slice | not mapped in this slice | not mapped in this slice | not mapped in this slice | +| `shared/verification.md` | verification skill (Quick, Standard, and Certification implemented) | not mapped in this slice | not mapped in this slice | not mapped in this slice | not mapped in this slice | +| `shared/task-execution-policy.md` | no platform copy (vocabulary contract, deferred consumption) | no platform copy (vocabulary contract, deferred consumption) | no platform copy (vocabulary contract, deferred consumption) | no platform copy (vocabulary contract, deferred consumption) | no platform copy (vocabulary contract, deferred consumption) | ## Platform-specific files (no shared equivalent) @@ -22,6 +22,7 @@ - `codex/AGENTS.md` - `goose/AGENTS.md` - `claude/CLAUDE.md` +- `copilot/README.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 ec71692..92e3383 100644 --- a/agent-pack/README.md +++ b/agent-pack/README.md @@ -15,6 +15,7 @@ repository—not a separate product. - One bounded Codex CLI NeuralEngine skill projection. - One bounded Goose CLI/Desktop NeuralEngine skill projection. - One bounded Claude Code/Desktop Code NeuralEngine skill projection. +- One bounded GitHub Copilot CLI NeuralEngine skill projection. - Placeholder directory for future Antigravity platform variants. This pack does not modify NeuralEngine runtime behavior, Brain persistence, @@ -52,6 +53,7 @@ contract and introduces the generic builder agent: | Codex CLI NeuralEngine slice | Supported with limitations (CLI only) | | Goose CLI/Desktop NeuralEngine slice | Supported with limitations (bounded post-v1.0 extension) | | Claude Code/Desktop Code NeuralEngine slice | Supported with limitations (bounded post-v1.0 extension) | +| GitHub Copilot CLI NeuralEngine slice | Supported with limitations (bounded post-v1.0 extension) | | Antigravity | Placeholder (not implemented) | Review artifacts: @@ -196,8 +198,7 @@ equality, frontmatter integrity, model-name absence, and agent coexistence). - [DEFINITION-OF-DONE.md](DEFINITION-OF-DONE.md) — Formal v1.0 quality gates. - [ROADMAP.md](ROADMAP.md) — Milestone roadmap from v0.1.0 to v1.0.0. - [MANIFEST.md](MANIFEST.md) — Shared-to-platform mapping and update rules. -- [CAPABILITY_MATRIX.md](CAPABILITY_MATRIX.md) — Platform capability matrix (OpenCode, Codex CLI, Goose, and Claude Code/Desktop Code). -- [CAPABILITY_MATRIX.md](CAPABILITY_MATRIX.md) — Platform capability matrix (OpenCode, Codex CLI, Goose, and Claude Code/Desktop Code). +- [CAPABILITY_MATRIX.md](CAPABILITY_MATRIX.md) — Platform capability matrix (OpenCode, Codex CLI, Goose, Claude Code/Desktop Code, and Copilot CLI). - [DECISIONS/](DECISIONS/) — Architecture Decision Records (ADRs). - [RELEASE_NOTES_v0.4.0.md](RELEASE_NOTES_v0.4.0.md) — v0.4.0 release notes. - [RELEASE_NOTES_v0.3.0.md](RELEASE_NOTES_v0.3.0.md) — v0.3.0 release notes. @@ -218,6 +219,7 @@ Platform implementations: - [platforms/codex/](platforms/codex/) — Codex CLI NeuralEngine adapter slice. - [platforms/goose/](platforms/goose/) — Goose CLI/Desktop NeuralEngine adapter slice. - [platforms/claude/](platforms/claude/) — Claude Code/Desktop Code NeuralEngine adapter slice. +- [platforms/copilot/](platforms/copilot/) — GitHub Copilot 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/copilot/README.md b/agent-pack/platforms/copilot/README.md new file mode 100644 index 0000000..fe5add9 --- /dev/null +++ b/agent-pack/platforms/copilot/README.md @@ -0,0 +1,56 @@ +# GitHub Copilot CLI Platform + +**Status:** NeuralEngine thin adapter implemented for GitHub Copilot CLI with +documented limitations. + +This is one bounded provider projection of +agent-pack/shared/neuralengine.md. It is a post-v1.0 extension of the Agent +Pack and does not change the v1.0 platform freeze. It does not modify +NeuralEngine runtime behavior, Brain persistence, schemas, APIs, or user-global +Copilot configuration. + +## Adapter files + +- skills/neuralengine/SKILL.md — Copilot CLI project skill projection with 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: + +skills/neuralengine/SKILL.md +→ /.github/skills/neuralengine/SKILL.md + +Copilot CLI natively discovers project skills and decides when to load them +from their descriptions. No additional project instruction pointer is added: +a duplicate pointer would repeat shared policy without adding a native loading +requirement. Existing AGENTS.md or .github/copilot-instructions.md files in a +target repository remain separate host instruction mechanisms. + +## Discovery and permission boundaries + +- GitHub documents project skills under .github/skills, .claude/skills, and + .agents/skills. This adapter uses the GitHub-native .github/skills path. +- SKILL.md requires YAML name and description metadata. Optional allowed-tools + is deliberately omitted so the host retains its normal approval behavior. +- Copilot CLI discovers repository instruction files in standard locations and + combines applicable instructions. This adapter does not add or duplicate one. +- GitHub documents read-only shell and file operations as automatically allowed; + edits, destructive commands, URL access, and other modifying tools require + explicit approval. +- Local verification found no copilot binary. The gh copilot help command + identified a preview wrapper that would download the CLI if absent; no + download or session was started. +- The neural executable, PATH, Brain access, and command behavior must be + verified in each target environment. + +This is CLI-only support. No editor or web-surface support is claimed. + +The adapter grants no additional read, write, Brain-write, staging, commit, +push, merge, tag, release, or publication authority. + +No automatic installation or Brain write is performed. diff --git a/agent-pack/platforms/copilot/skills/neuralengine/SKILL.md b/agent-pack/platforms/copilot/skills/neuralengine/SKILL.md new file mode 100644 index 0000000..2d69e45 --- /dev/null +++ b/agent-pack/platforms/copilot/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_copilot_cli_adapter.py b/tests/test_copilot_cli_adapter.py new file mode 100644 index 0000000..7426f92 --- /dev/null +++ b/tests/test_copilot_cli_adapter.py @@ -0,0 +1,97 @@ +"""Drift and scope checks for the bounded Copilot CLI adapter.""" + +from pathlib import Path + + +def _source_root() -> Path: + """Return the Handbook repository root.""" + return Path(__file__).resolve().parents[1] + + +def _copilot_root() -> Path: + """Return the controlled Copilot CLI platform source directory.""" + return _source_root() / "agent-pack" / "platforms" / "copilot" + + +def _skill() -> Path: + """Return the controlled Copilot CLI NeuralEngine skill projection.""" + return _copilot_root() / "skills" / "neuralengine" / "SKILL.md" + + +def _shared() -> Path: + """Return the authoritative shared NeuralEngine contract.""" + return _source_root() / "agent-pack" / "shared" / "neuralengine.md" + + +def _body(content: str) -> str: + """Return a skill body after its 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 :]) + + +class TestCopilotCliNeuralEngineAdapter: + """Tests for the single GitHub Copilot CLI projection.""" + + def test_expected_platform_paths(self) -> None: + """The adapter contains only its README and one skill.""" + paths = sorted( + path.relative_to(_copilot_root()).as_posix() + for path in _copilot_root().rglob("*") + if path.is_file() + ) + assert paths == [ + "README.md", + "skills/neuralengine/SKILL.md", + ] + + def test_skill_has_required_frontmatter_only(self) -> None: + """The provider adds only required name and description metadata.""" + lines = _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.", + ] + assert "allowed-tools:" not in "\n".join(lines[1:closing]) + + def test_skill_body_matches_shared_contract(self) -> None: + """Copilot cannot silently diverge from the canonical semantic source.""" + assert _body(_skill().read_text(encoding="utf-8")) == _shared().read_text(encoding="utf-8") + + def test_no_extra_pointer_is_required(self) -> None: + """Native skill discovery means no duplicate instruction pointer exists.""" + paths = {path.name for path in _copilot_root().iterdir()} + assert paths == {"README.md", "skills"} + + def test_readme_describes_cli_only_boundary(self) -> None: + """Documentation states the bounded CLI-only support boundary.""" + content = (_copilot_root() / "README.md").read_text(encoding="utf-8") + assert "GitHub Copilot CLI" in content + assert ".github/skills/neuralengine/SKILL.md" in content + assert "No additional project instruction pointer is added" in content + assert "This is CLI-only support." in content + assert "No editor or web-surface support is claimed." in content + + def test_adapter_does_not_claim_provider_independent_authority(self) -> None: + """The Copilot files preserve host permissions and publication boundaries.""" + content = "\n".join( + path.read_text(encoding="utf-8") + for path in _copilot_root().rglob("*") + if path.is_file() + ) + for phrase in ( + "grants no additional", + "Brain-write", + "staging", + "commit", + "push", + "publication", + ): + assert phrase in content