vrr/CodeNomad
2
0
Fork 0
mirror of https://github.com/NeuralNomadsAI/CodeNomad.git synced 2026-10-22 22:31:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
CodeNomad/dev-docs/RUNTIME_MAINTENANCE.md
Pascal André 7a1fc90310
docs(agents): keep AGENTS.md to universal rules and agent docs to the current state (#1082) 
AGENTS.md loaded about 33,000 tokens into every agent session, subagent and reviewer, mostly per-feature contracts, and the agent documentation around it had accumulated duplicates, dated logs and history of removed designs. This PR makes AGENTS.md a short set of rules that apply everywhere plus an index of area documents, and leaves AGENTS.md, dev-docs and the repository skills describing only the current state.

Three commits, reviewable separately:

1. **Move (lossless).** Every per-area rule moved verbatim from AGENTS.md into its area document (existing ones, or six new ones: UI_CONVENTIONS, UI_SHELL, COMPOSER, TRANSCRIPT, SETTINGS, PROJECTS). A script split the old file into 208 units, required one destination for each and checked all 199 content units verbatim at their destination. AGENTS.md went from 134,000 to 16,000 characters.
2. **Trim.** A per-area ponytail review removed rules stated two or three times (keeping the more precise copy), dated validation logs, per-version qualification sections below the current minimum, abandoned designs and self-references; seven documents whose surviving rules live elsewhere were deleted. It also fixed statements the code contradicts (locale registration, the Mission play/recovery condition, plugin package updates, cleanup progress UI, timeline index persistence, automation restart/targets, stale pins and minimums).
3. **Current state only.** The new AGENTS.md rule: no history (removed features and their names, former behavior, provenance, dated logs) and no denials; correct a contradicted statement at its source. DEVELOPER_MODE.md is merged into BROWSER_AUTOMATION.md and every Developer Mode mention is gone (including the README and the browser help page in ten locales). Names that only made sense against older designs are renamed with every reference updated, MISSIONS_ENVIRONMENT_ADMISSION is folded into SESSION_ENVIRONMENT, and INDEX lists every document. The server npm README now states the real OpenCode minimum (2.1.2).

AGENTS.md is now about 14,000 characters (roughly 3,500 tokens); AGENTS.md, dev-docs and the vendor README went from about 11,200 lines to under 4,700.

Validation: every relative Markdown link and every cited dev-docs path resolves; no reference to a renamed or deleted document remains; `npm run test:help` passes for all ten locales.

Review: three independent GPT-6.1 Sol (high) reviews by area found binding rules lost in the trim and current-state passes; 25 were restored as present-tense facts or prohibitions and four contradicting statements corrected, each checked against code. A Fable 5.1 gatekeeper review of the whole PR passed; its follow-up routes session recovery from the index, points to dev-docs/INDEX.md and documents the family identity read.
2026-10-21 16:59:43 +02:00

2.6 KiB
Raw Permalink Blame History

Bundled runtime maintenance

  • .node-version is an exact pin shared by CI and both desktop packages. scripts/prepare-node-runtime.cjs copies npm, including its dependencies, from that official Node archive. A new application release is required to deliver any runtime change to installed applications.
  • Dependabot checks GitHub Actions weekly and proposes updates against dev; merges are manual. Composite actions that follow their upstream stable/latest major stay on those supported references.
  • Bundled Runtime Maintenance runs daily (07:23 UTC, subject to GitHub's scheduling delays) and on manual dispatch, on the default branch only. It selects newer LTS releases within the pinned Node major only. It never upgrades an installed application or OpenCode.
  • A Node update creates a version-specific regular (non-draft) PR changing only .node-version; review and merge are manual. Events from GITHUB_TOKEN start no workflows, so a maintainer closes and reopens the PR to run validation. Existing proposals, including closed ones, are left alone; orphan branches after an uncertain API response require manual reconciliation, never a force-push.
  • npm is warning-only. The check compares npm's latest published version with the version declared for the pinned Node release. It audits that published npm CLI and its bundled dependencies using an isolated temporary lockfile, with installation scripts disabled, separately from the application's dependency audit. The JSON advisory report is retained as an Actions artifact for seven days.
  • Version lag and advisory counts need applicability review. A Node update may bring a newer npm from the official archive; replacing npm separately is manual.
  • Failed metadata/audit requests fail the job; updates and advisories only emit warnings and a job summary, never an unrelated PR build gate.

Repository settings must allow GitHub Actions to create pull requests. The audit job has read-only repository permissions. A separate trusted proposal job requests contents: write and pull-requests: write; never add a personal token or automatic approval. Run npm run check:runtime locally for the same read-only assessment.

Agent conventions

  • Bundled runtime maintenance keeps .node-version exact and proposes only same-major LTS upgrades as regular, non-draft PRs without automatic merge. The scheduled npm CLI/dependency audit is warning-only: never independently replace bundled npm, auto-fix dependencies, merge or publish from that check, and never report a failed audit as clean. Application runtime changes require reviewed builds/releases.