diff --git a/README.md b/README.md index e8c24720..b2ce33f6 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ Repo-native agent orchestration and public Codex signal publishing. - Native macOS app for Decodex Codex account-pool management. - Explicit project registry under `~/.codex/decodex/projects//`. - Local operator listener with a dashboard at `/` and `/dashboard`, WebSocket - snapshot/control traffic at `/dashboard/control`, and `GET /livez` for liveness. + snapshot/control traffic at `/dashboard/control`, Decodex App snapshot/account + APIs under `/api/`, and `GET /livez` for liveness. - Static Astro site that publishes GitHub-backed Codex change signals. - Deterministic GitHub signal pipeline for change bundles, release deltas, rendered signal entries, and content validation. diff --git a/docs/reference/operator-control-plane.md b/docs/reference/operator-control-plane.md index cf6000e9..80787b91 100644 --- a/docs/reference/operator-control-plane.md +++ b/docs/reference/operator-control-plane.md @@ -33,6 +33,14 @@ Decodex currently runs as a local, single-machine control plane: - The project-owned `WORKFLOW.md` remains the execution-policy contract for that registered repo. +Decodex App is a native shell over the same local runtime and account-pool state. On +launch it connects to an existing default local listener when one is reachable; if +not, it starts the bundled `decodex` binary as +`decodex serve --api-only --listen-address 127.0.0.1:8912`. API-only mode serves the +dashboard, account APIs, and `GET /api/operator-snapshot` for the app, but it does +not register projects, poll Linear, dispatch work, or accept `--config` or +`--interval`. Use ordinary `decodex serve --interval ...` for the automation loop. + Project registration is not service intake. The `Projects` dashboard section may show multiple enabled projects with visible work at once, and its filter can reveal the full registered-project table, but a service is only eligible to intake @@ -110,10 +118,12 @@ service queue label before treating it as a connector problem. The browser dashboard reads the complete published state from the local `GET /dashboard/control` WebSocket. That socket is the dashboard authority for published snapshots, active-lane activity updates, and local dashboard control -acknowledgements; there is no separate HTTP snapshot polling route. The current -browser UI keeps live updates unscoped and exposes explicit stop controls for active -lanes with a known live child process plus account-pool selection controls; project -watch, project pause/resume, and manual retry controls are intentionally not shown. +acknowledgements. `GET /api/operator-snapshot` is the Decodex App read API over the +same runtime database, not a browser-dashboard polling authority and not a sign that +an API-only listener owns scheduling. The current browser UI keeps live updates +unscoped and exposes explicit stop controls for active lanes with a known live child +process plus account-pool selection controls; project watch, project pause/resume, +and manual retry controls are intentionally not shown. The stop control signals the recorded child process for that run, marks the local attempt interrupted, and releases the local queue lease. `ack` is dashboard-local acknowledgement only. The socket is not a browser connection to Codex app-server, diff --git a/docs/runbook/self-dogfood-pilot.md b/docs/runbook/self-dogfood-pilot.md index fc3ada2c..9bb950f3 100644 --- a/docs/runbook/self-dogfood-pilot.md +++ b/docs/runbook/self-dogfood-pilot.md @@ -366,6 +366,13 @@ wants to observe the self-bootstrap loop without reading source code. `app_server_preflight_failed` evidence for the `plugin/list` timeout, restart `decodex serve` if the app-server process is stale, and run `decodex probe` until plugin inventory responds before clearing `decodex:needs-attention`. + If preflight evidence shows `skills/list` enabled skills with scan diagnostics, + keep the diagnostics as compatibility evidence and do not uninstall official skills + solely to clear the scan error. Only missing cwd coverage or zero enabled skills are + `skills/list` blockers; for those, inspect `first_error_path` and `first_error`, + update the local Codex/Decodex compatibility or skill metadata as needed, restart + `decodex serve`, and rerun `decodex probe` before clearing + `decodex:needs-attention`. 4. In Linear, choose two or three small `decodex` issues for the demo batch. Keep each issue in a startable state such as `Todo`, make sure it does not carry @@ -768,6 +775,11 @@ repo gate commands. Linear should carry only the coarse team-visible failure sum worktree's local preflight evidence for `plugin/list`, restart `decodex serve` if stale, verify `decodex probe`, then clear `decodex:needs-attention` and move the issue back to a startable state only when another automated run is desired. +- If status or Linear terminal failure includes a `skills/list` preflight blocker, + inspect the attached `first_error_path` and `first_error` details before changing + local plugins or skills. Scan diagnostics with enabled skills are not blockers by + themselves; missing cwd coverage or zero enabled skills require local + Codex/Decodex compatibility repair before requeueing. - If `status` reports retained partial progress or the dashboard shows `Partial patch held`, inspect the named worktree first. Treat the retained patch as local recovery evidence: finish the repo gate and PR handoff if the patch is useful, or reset the worktree before clearing `decodex:needs-attention`. - If the run moved back to `Todo` with `decodex:needs-attention`, inspect the worktree, fix the blocking problem, clear `decodex:needs-attention`, and then move the issue back into a startable state for another automated attempt. - If the issue should never be automated again, add `decodex:manual-only`. diff --git a/plugins/decodex/skills/automation/SKILL.md b/plugins/decodex/skills/automation/SKILL.md index 2f06601d..4f8ac975 100644 --- a/plugins/decodex/skills/automation/SKILL.md +++ b/plugins/decodex/skills/automation/SKILL.md @@ -52,6 +52,9 @@ wants to register that project and start the scheduler in one command. Use `decodex run ` or `cargo run -p decodex --bin decodex -- run ` only for a deliberate one-issue automation pass; it still uses the same retained-lane eligibility and lifecycle rules. +Do not use hidden `serve --api-only` for automation. That mode belongs to Decodex App: +it serves local dashboard/account/app snapshot APIs, but it does not register +projects, poll Linear, or dispatch lanes. ## Intake and Ownership @@ -78,6 +81,11 @@ terminal automation signal. wait, retained repair, closeout, recovery worktrees, and cleanup debt. - Treat runtime DB rows, app-server protocol activity, and Linear execution-ledger comments as different evidence surfaces. +- When app-server preflight mentions `skills/list`, distinguish non-blocking scan + diagnostics from real blockers. If the run cwd is present and at least one skill is + enabled, preserve `error_count`, `first_error_path`, and `first_error` as evidence + but do not stop the lane solely because unrelated installed skill metadata failed to + scan. Missing cwd coverage or zero enabled skills remain blockers. - Before assuming a lane is stuck, compare lane phase, wait reason, last run activity, protocol activity, active lease state, and child-agent activity when present. diff --git a/plugins/decodex/skills/manual-cli/SKILL.md b/plugins/decodex/skills/manual-cli/SKILL.md index a2d43c4c..c6543b5f 100644 --- a/plugins/decodex/skills/manual-cli/SKILL.md +++ b/plugins/decodex/skills/manual-cli/SKILL.md @@ -80,6 +80,13 @@ Manual commit and landing are separate narrow workflows: - Use `run --dry-run` before live automation to validate project loading, issue discovery, eligibility, and worktree planning without tracker mutation. - Use `probe stdio://` before relying on the Codex app-server boundary. +- Treat hidden `serve --api-only` as Decodex App infrastructure only. It serves + dashboard, account, and app snapshot APIs, but it does not register projects, poll + Linear, or dispatch work. +- For `skills/list` app-server preflight output, enabled skills plus scan diagnostics + are local evidence, not a lane blocker. Missing cwd coverage or zero enabled skills + are blockers; inspect `first_error_path` and `first_error` before changing plugin or + skill installs. ## Boundaries