Files

T

nntrivi2001 e109d2804c feat(lanes): auto-advance a codex lane's stage from its rollout detection

A codex session emits no hooks and rarely calls `ccam stage` on its own, so
its card sat at `idle` forever while the amber "detected" badge was the only
thing that ever moved. `codex-ingest.js` now advances the declared `stage`
from its own written detection — the one place in CCAM where an inference
moves the blue `current` ring, and only for `codex` lanes.

It stays honest: gated on `recordDetection` having written (so forward-only,
declared-wins and the detection TTL are inherited unchanged), passes NO
evidence (the node renders `passed-no-evidence` amber, never `done`), and no
template's last node carries detect rules, so a lane can never be
auto-declared `done`. `setStage` grows a `keepDetection` option — its sole
caller — so the detection columns survive the advance and the card keeps
showing which command moved it instead of looking like an agent's own claim.

Two levers then get the evidence auto-advance cannot supply:

- `codex-nudge.js` now nudges on a stage held 2+ min with no evidence,
  instead of on a detection sitting ahead of the declared stage — after
  auto-advance the old condition can never fire, since the two now match.
- `ccam lanes agents install` on a codex lane writes the marker-delimited
  `<!-- ccam:stage:start -->` block into the lane's own AGENTS.md — the one
  instruction channel Codex reads — instead of copying agent templates into
  `.claude/agents/`, which it never loads. Appended, user prose preserved,
  reinstall replaces exactly that block.

Verified with a real `codex exec` run: stage moved to `watching-pr` with
`evidence: null` and the detection signal intact. 1364 server tests pass.

2026-09-03 16:51:02 +07:00

3.8 KiB

Raw Blame History

Codex Project Instructions

Project intent

Keep this repository a stable, local-first Claude Code monitoring platform.
Maintain correctness across hooks, API, DB, websocket, UI, and MCP integration.

Priorities

Correctness over cleverness.
Small, scoped, reversible diffs.
Preserve existing behavior unless change is requested.
Update docs whenever workflow or architecture changes — follow skills/update-project-docs/ automatically at the end of every change-set (README + VN/CN/KO mirrors, ARCHITECTURE, wiki + i18n + cache bump, server/client READMEs, docs/*).
Every applicable source file you create or update (.js/.ts/.tsx/.cjs/.mjs/.py/.sh/.css) must start with the authorship header: a truthful file overview plus the exact line @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>. See skills/file-headers/ and .claude/rules/file-headers.md; verify with bash skills/file-headers/scripts/check-headers.sh.

Declare your lane stage as you work

This repository is watched by CCAM, its own dashboard. A lane is keyed by working directory, and the pipeline map only moves forward when the agent doing the work declares its stage:

ccam stage <stage> --tool codex --evidence "<what is actually done>"

Call it at every real transition — starting to plan, starting to implement, running tests, opening the PR — not once at the end.
Stage names, default template: intake → plan → implement → tests → review → gate → ship → done (the 16-node ship-feature template accepts these as aliases too; ccam stage warns on stderr and names the valid nodes if a stage matches none).
--tool codex matters. One directory can back both a claude lane and a codex lane, and without a tool the command fails rather than guess (it names both candidates). Inside a pane the dashboard started you need nothing — that pane carries CCAM_LANE_ID, which outranks everything but --lane.
If ccam stage reports that no lane owns the directory, this checkout was never adopted: skip the stage calls and carry on. Stage reporting is reporting, never control flow — a failed ccam stage never justifies skipping a step of the actual work.

The dashboard also infers your stage from your tool calls (it reads Codex's own rollout journals — see docs/LANES.md#stage-detection), and on a codex lane that inference does move the pipeline map forward on its own. It still never counts as evidence: a node it moved through stays amber and never renders green. Only your own declaration does that — which is why the call above is worth making even when the map already looks right.

If you hold a stage for a while with no evidence recorded, the dashboard may type a one-line [ccam] reminder straight into this pane asking you to run ccam stage ... --evidence "...". That is the dashboard, not the user — treat it as the same instruction as this section and just make the real call.

Where to work

server/ for API/routes/data processing.
client/ for React UI behavior.
mcp/ for local MCP server tooling.
scripts/ for hook/install/import/cleanup utilities.

Validation expectations

Backend changes: run npm run test:server when possible.
Frontend changes: run npm run test:client when possible.
MCP changes: run npm run mcp:typecheck and npm run mcp:build.
If any check is skipped, report it explicitly.

Safety expectations

Keep destructive capabilities behind explicit configuration gates.
Never broaden destructive behavior without explicit user request.
Treat hook execution path as fail-safe and non-blocking.

Useful commands

Setup: npm run setup
Dev: npm run dev
Build/start: npm run build then npm start
MCP helpers: npm run mcp:install, npm run mcp:build, npm run mcp:start

3.8 KiB Raw Blame History