feat!: Neural Codex port for OpenCode 1.18.31

.github/workflows/docs-lint.yml

@@ -0,0 +1,28 @@
+name: Validate Plugin
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Install test runner
+        run: python -m pip install --disable-pip-version-check pytest
+      - name: Run supported test suite
+        run: python -m pytest -q
+      - name: Run hook unit tests
+        run: node --test tests/hooks.test.js
+      - name: Validate plugin documentation
+        run: ./scripts/doc-lint.sh

.gitignore

@@ -0,0 +1,6 @@
+plans/
+.opencode/compact-context.md
+node_modules/
+__pycache__/
+.pytest_cache/
+.DS_Store

AGENTS.md

@@ -0,0 +1,54 @@
+# Neural OpenCode project instructions
+
+## Product boundary
+
+Neural OpenCode is one installable OpenCode plugin. Its supported surface is
+exactly five skills: `discover`, `spec`, `craft`, `vet`, and `exercise`, plus
+the reviewed hooks under `plugins/neural-open-code/hooks/`.
+
+Do not add a second skill root, a silent config writer, or an installer that
+copies files into a user's home directory. The plugin package plus documented
+`opencode.json` keys are the distribution contract.
+
+OpenCode 1.18.31 has no marketplace API and no `hooks.json`. Do not invent
+Codex `.codex-plugin` paths or Claude `settings.json` merges.
+
+## Canonical paths
+
+- Plugin package: `plugins/neural-open-code/package.json`
+- Plugin entry: `plugins/neural-open-code/index.js`
+- Skills: `plugins/neural-open-code/skills/<name>/SKILL.md`
+- Hooks: `plugins/neural-open-code/hooks/`
+- Example config: `opencode.example.json`
+- Public docs: `docs/`
+- Plans and evidence: `plans/`
+- Unsupported 1.9.0 surface: `archived/v1.9.0/`
+
+## Change workflow
+
+Use `/discover` for material ambiguity, `/spec` before non-trivial
+implementation, `/craft` for an approved plan, and independent `/vet` plus
+`/exercise` gates before shipping. Keep generated evidence beside its plan.
+
+Never auto-trust hooks or mutate a user's global OpenCode configuration. Never
+commit credentials or read/write `.env` contents as part of validation.
+
+## Required validation
+
+```bash
+python3 -m pytest -q
+node --test tests/hooks.test.js
+./scripts/doc-lint.sh
+```
+
+A valid directory shape is necessary but not sufficient: tests must also reject
+stale claims and unsupported inventory.
+
+## Documentation map
+
+- Architecture: `ARCHITECTURE.md`
+- Harness contract: `docs/AGENT-HARNESS.md`
+- Workflow: `docs/WORKFLOW.md`
+- Hooks and trust: `docs/HOOKS.md`
+- Model availability and prompting: `docs/CONFIGURATION.md`
+- Verification: `docs/VERIFICATION.md`

ARCHITECTURE.md

@@ -0,0 +1,67 @@
+# Neural OpenCode architecture
+
+Neural OpenCode has two layers: one plugin package and documented project
+config keys. This mirrors OpenCode 1.18.31's distribution model (npm/file
+plugins + disk skills) and keeps authoring, installation, and runtime paths
+unambiguous.
+
+```text
+repository
+├── opencode.json
+├── opencode.example.json
+└── plugins/neural-open-code
+    ├── package.json
+    ├── index.js
+    ├── skills
+    │   ├── discover
+    │   ├── spec
+    │   ├── craft
+    │   ├── vet
+    │   └── exercise
+    └── hooks
+        └── *.js
+```
+
+## Why this is not a Codex marketplace
+
+OpenCode 1.18.31 has no plugin marketplace, no `plugin.json` skill manifest,
+and no `hooks.json`. Plugins are TypeScript/JavaScript modules that return a
+`Hooks` object. Skills are `SKILL.md` trees discovered from `.opencode/skills`
+or `skills.paths`. Neural OpenCode therefore ships one package and asks the
+user to add two explicit keys.
+
+## Plugin boundary
+
+`package.json` identifies the package (`name`, `exports["./server"]`,
+`engines.opencode`). The entry registers only lifecycle hooks. It does not
+declare MCP servers, models, permissions, or agents.
+
+## Workflow boundary
+
+The five skills have intentionally different authority:
+
+1. `/discover` gathers unknowns and stops.
+2. `/spec` writes an approvable contract and stops.
+3. `/craft` implements only an approved contract.
+4. `/vet` evaluates in fresh context and returns `SHIP` or `HOLD`.
+5. `/exercise` runs tests and drives observable user behavior.
+
+No skill silently collapses planning, implementation, review, and exercise into
+one self-certifying step.
+
+## Hook boundary
+
+Hooks implement OpenCode events:
+
+- `tool.execute.before` — inspect `bash`, `write`, `edit`, and `apply_patch`
+- `tool.execute.after` — scan tool output
+- `experimental.session.compacting` — write a recovery note
+
+They throw to block. They do not call the `config` hook. They complement
+OpenCode permission policy; they do not replace it.
+
+## Configuration boundary
+
+The plugin never changes model, approval, sandbox, network, MCP, or global
+configuration. `docs/CONFIGURATION.md` contains examples only, which keeps
+installation reversible and policy-neutral.

CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.0.0] - 2026-09-19
+
+### Breaking cleanup: Neural Codex port for OpenCode 1.18.31
+
+Neural OpenCode is now a lightweight evidence-gated harness, not the 1.9.0
+kitchen sink. Host target is OpenCode **v1.18.31** (there is no OpenCode
+v2.0.8).
+
+### Added
+
+- Five workflow skills with Neural Codex contracts: `/discover`, `/spec`,
+  `/craft`, `/vet`, `/exercise`
+- OpenCode-native plugin at `plugins/neural-open-code/` (`package.json` +
+  `index.js` hooks)
+- Guardrail hooks on `tool.execute.before`, `tool.execute.after`, and
+  `experimental.session.compacting`
+- Focused docs, GitHub Page sources, and contract tests
+- `archived/v1.9.0/` holding the previous product surface as unsupported
+
+### Removed from the supported product path
+
+- Agentic course (`/course`) and lesson pack
+- Neural Squad (`/squad-*`)
+- Neural loops (`/loop` and archived loop commands)
+- TTS / ElevenLabs
+- Multi-AI mesh (`/pv-mesh`, `/ai-collab`, dedicated Codex/Gemini agents)
+- KPI, Compute Advantage, and cost trackers
+- Memory / expertise / remember-recall product
+- Skills manager, onboard tour, and extra command/agent packs
+- Custom `install.sh` / one-liner home-directory installers
+- Output styles, status lines, expertise schemas, and CRAFT templates as
+  first-class surface
+
+Lyft, WordPress, and MCP-dependent features remain deferred.
+
+### Migration
+
+1. Install OpenCode 1.18.31 or later.
+2. Add the two documented keys from `opencode.example.json` to your project.
+3. Stop using archived 1.9.0 commands and skills.
+4. Review `plugins/neural-open-code/hooks/` before trusting a session.
+
+No GitHub release, npm publish, or live Pages deploy is performed by this
+change.
+
+---
+
 ## [1.9.0] - 2026-02-03
 
 ### Interactive Agentic Coding Course