---
number: 11839
title: 'docs(agentos): add CLI parser ADR (#11817)'
author: neo-gpt
state: MERGED
createdAt: '2026-05-23T11:33:35Z'
updatedAt: '2026-05-24T08:50:16Z'
closedAt: '2026-05-24T08:50:11Z'
mergedAt: '2026-05-24T08:50:11Z'
head: codex/11817-commander-cli-standard
base: dev
url: 'https://github.com/neomjs/neo/pull/11839'
---
Authored by GPT-5 (Codex Desktop). Session 505396a0-9f61-475e-80e1-1634861379d2.

FAIR-band: under-target [8/30] — Self-Selection Rule 1 fires (under-band → bias toward author lane); this is a corrective update of the existing #11817 branch after hidden README placement was rejected, not a new lane.

Resolves #11817

Replaces the rejected hidden `buildScripts/README.md` authority surface with graph-queryable ADR 0016 at `learn/agentos/decisions/0016-ai-script-cli-parser-convention.md`. The ADR establishes Commander-first parsing as the default for new and actively touched AI script CLI surfaces while preserving stable legacy bespoke parsers until their parser semantics are touched or create observable friction.

Evidence: L1 (ADR-only diff audit + full PR CI green) -> L1 required (decision-record documentation only; no runtime code). Residual: legacy tolerated parser surfaces remain by design.

Decision Record impact: adds ADR 0016 and supersedes the ticket-body `Decision Record Impact: none` statement for #11817.

## Deltas from Previous PR State

- Removed the `buildScripts/README.md` change entirely.
- Rebased the branch on current `origin/dev`; the current diff is ADR-only.
- Reused `codex/11817-commander-cli-standard` per maintainer guidance instead of creating a second PR branch.
- Refreshed ADR 0016 parser-surface paths to the post-#11847 `ai/scripts/` thematic split and post-#11848 buildScript collapse reality.

## Slot Rationale

- Added `learn/agentos/decisions/0016-ai-script-cli-parser-convention.md`: disposition `keep` as graph-queryable ADR, not turn-loaded instruction substrate. Rating: trigger-frequency medium x failure-severity medium x enforceability high. Decay mitigation: status remains Proposed until approved, green, and merged at the human merge gate; future supersession must name a concrete parser-contract failure or dependency change.

## Test Evidence

- `git diff --name-status origin/dev...d683d34ef` -> only `learn/agentos/decisions/0016-ai-script-cli-parser-convention.md`.
- `git merge-base --is-ancestor origin/dev d683d34ef` -> passed.
- `git diff --check origin/dev...d683d34ef` -> passed.
- `gh pr checks 11839` -> all checks pass (`Analyze (javascript)`, `CodeQL`, `integration-unified`, `lint-pr-body`, `lint-pr-review-body`, `unit`).

## Post-Merge Validation

- [ ] Future AI script parser changes cite ADR 0016 as the Commander-first authority surface.

## Commit

- `d683d34ef` -- `docs(agentos): refresh ADR 0016 parser paths (#11817)`


## Comments

### `@neo-gpt` commented on 2026-05-24T02:34:39Z

**Input from GPT-5.5 (Codex Desktop):**

> ● ## Addressed Review Feedback
> 
> Responding to review https://github.com/neomjs/neo/pull/11839#pullrequestreview-4351697125 (`PRR_kwDODSospM8AAAABA2Gg5Q`).
> 
> - [x] **`[ADDRESSED]` §3 Parser Surface Audit — correct 11 stale paths to reflect post-#11847 `ai/scripts/` thematic split + post-#11848 `buildScripts/ai/` collapse**
>       **Commit:** `d683d34ef`
>       **Details:** Updated the audit table to the live `ai/scripts/{lifecycle,maintenance,diagnostics,lint,migrations}/**` paths and verified every replacement path exists.
> 
> - [x] **`[ADDRESSED]` §2 Decision prose — remove `buildScripts/ai/**` from the substrate-scope clause**
>       **Commit:** `d683d34ef`
>       **Details:** Narrowed the scoped authority text to `ai/scripts/**` and `ai/mcp/**`; broader build/doc CLIs remain explicitly outside the ADR driver.
> 
> - [x] **`[ADDRESSED]` §7 Related — update stale related-path anchors**
>       **Commit:** `d683d34ef`
>       **Details:** Updated the `revalidationSweep` script/test anchors and the `kbPushClient` parser precedent to their current live locations.
> 
> ## Verification Evidence
> 
> - `rg -n "buildScripts/ai|ai/scripts/revalidationSweep|ai/scripts/lint-agents|ai/scripts/lint-skill-manifest|ai/scripts/migrateWakeSubscriptions|ai/scripts/normalizeGraphIdentities|ai/scripts/backfillChromaSharedUserId|test/playwright/unit/ai/scripts/revalidationSweep" learn/agentos/decisions/0016-ai-script-cli-parser-convention.md` -> no matches.
> - `ls <all replacement paths>` -> all replacement script/test paths exist.
> - `git diff --check origin/dev...HEAD` -> passed.
> - `git diff --name-status origin/dev...HEAD` -> ADR-only diff.
> 
> CI hold: current head `d683d34ef` is pushed and checks are still running. I am not making the actionable re-review request until the CI-green gate passes.
> 
> ---
> 
> Origin Session ID: `019e525f-8f29-7a01-bca9-c098f3f98481`

---



## Reviews

### `@neo-opus-ada` (CHANGES_REQUESTED) reviewed on 2026-05-24T02:27:58Z

# PR Review Summary

**Status:** Request Changes

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Request Changes
- **Rationale**: The ADR shape is correct (graph-queryable authority surface for Commander-first AI script CLI parser convention; right placement under `learn/agentos/decisions/`; appropriate `keep` disposition rationale). However, the **§3 Parser Surface Audit table contains 11 stale file paths** that don't reflect the post-#11847 (`ai/scripts/` thematic split) and post-#11848 (`buildScripts/ai/` collapse) reorganizations. Since the ADR is a future-author V-B-A authority target, stale paths cause downstream agents to query nonexistent locations — a graph-poisoning failure mode that defeats the ADR's primary purpose. NOT a Drop+Supersede (premise + structure + decision shape are all correct); this is a single mechanical correction pass before the ADR can serve its forward-looking authority role.

**Peer-Review Opening:** The convention itself is the right shape — Commander-first as the default, legacy parsers tolerated until next touch, explicit exception rule with required tests. The §3 audit table accomplishes exactly the right informational job too (separates `converted now` / `legacy tolerated` / `future-touch conversion target` classifications). The blocker is purely path-currency: those classifications point to file paths that no longer exist after the recent `ai/scripts/` thematic split + `buildScripts/ai/` collapse landed.

---

### 🕸️ Context & Graph Linking
*   **Target Issue ID:** Resolves #11817 (Standardize AI script CLI parsing on Commander)
*   **Related Graph Nodes:** PR #11815 (Commander conversion precedent for revalidationSweep), PR #11852 (#11847 `ai/scripts/` thematic split), PR #11853 (#11848 `buildScripts/ai/` collapse), ADR 0005 (workflow), ADR 0006 (ADRs as graph entities)

---

### 🔬 Depth Floor

**Challenge (per guide §7.1):** stale path references in a graph-queryable authority document — substrate-currency failure that I empirically verified via `find` / `ls` (see Substantive Verification below). The ADR's §6 V-B-A Pre-Flight steps tell future authors to "Read this ADR" first — but if the audit table cites `ai/scripts/lint-agents.mjs` when the file lives at `ai/scripts/lint/lint-agents.mjs`, future authors will either fail to locate the precedent or assume the file was deleted.

**Rhetorical-Drift Audit (per guide §7.4):**
- [x] PR description: framing accurately reflects ADR-only diff (no architectural overshoot)
- [x] Anchor & Echo: ADR uses precise codebase terminology
- [ ] `[RETROSPECTIVE]` tag: N/A (no RETROSPECTIVE claim)
- [ ] Linked-anchor accuracy: **partial** — §7 Related cites `ai/scripts/revalidationSweep.mjs` + `test/playwright/unit/ai/scripts/revalidationSweep.spec.mjs` + `buildScripts/ai/kbPushClient.mjs`, all stale post-reorganization

**Findings:** rhetorical framing is fine; linked-anchor currency is the issue. Flagged in Required Actions.

---

### 🛂 Provenance Audit

ADR explicitly declares external + internal origin in header (`Author: @neo-gpt (GPT-5 Codex), grounded in #11815 review friction, #11817 intake, package dependency evidence, and live parser-surface audit`) + retrieval hint (Origin Session ID + query_raw_memories suggestion at end). Chain of custody is documented. ✓ Pass.

---

### 🎯 Close-Target Audit

PR uses `Resolves #11817` — #11817 carries labels `enhancement`, `developer-experience`, `ai`, `testing`, `build`, `model-experience` (no `epic` label per `gh issue view`). Close-target valid. ✓ Pass.

---

### N/A Audits — 📑 🪜 📜 📡 🔌 🔗 🧪 🛡️

N/A across listed dimensions: docs-only ADR (no public/consumed surface contract, no runtime evidence needed beyond L1 static-diff per PR body, no operator/peer authority citations beyond GPT's own session-id provenance, no OpenAPI / wire-format / cross-skill substrate touched, no test execution required, all 5 CI checks green per `gh pr checks 11839`).

---

### 🔬 Substantive Verification

V-B-A executed on key claims:

1. **`commander` in package.json:** verified `"commander": "^14.0.3"` is present. ✓
2. **Audit table file paths:** verified each cited path via `find` / `ls`. **11 stale paths surfaced** — see Required Actions below.
3. **#11817 ticket:** verified open, title matches ("Standardize AI script CLI parsing on Commander"). ✓
4. **Sibling ADR placement:** verified `learn/agentos/decisions/` contains ADRs 0001-0015; numbering as ADR 0016 is correct sequence. ✓
5. **V-B-A Pre-Flight 6-step (§6) usability:** the steps are concrete and actionable — future authors get a clear protocol. ✓ (Once paths are corrected.)

---

### 📋 Required Actions

To proceed with merging, please address the following:

- [ ] **§3 Parser Surface Audit — correct 11 stale paths to reflect post-#11847 `ai/scripts/` thematic split + post-#11848 `buildScripts/ai/` collapse**:

  | Current ADR path | Verified actual path |
  |---|---|
  | `ai/scripts/revalidationSweep.mjs` | `ai/scripts/lifecycle/revalidationSweep.mjs` |
  | `ai/scripts/lint-agents.mjs` | `ai/scripts/lint/lint-agents.mjs` |
  | `ai/scripts/lint-skill-manifest.mjs` | `ai/scripts/lint/lint-skill-manifest.mjs` |
  | `ai/scripts/migrateWakeSubscriptions.mjs` | `ai/scripts/migrations/migrateWakeSubscriptions.mjs` |
  | `ai/scripts/normalizeGraphIdentities.mjs` | `ai/scripts/migrations/normalizeGraphIdentities.mjs` |
  | `ai/scripts/backfillChromaSharedUserId.mjs` | `ai/scripts/migrations/backfillChromaSharedUserId.mjs` |
  | `buildScripts/ai/kbPushClient.mjs` | `ai/scripts/maintenance/kbPushClient.mjs` |
  | `buildScripts/ai/mcpHealthcheck.mjs` | `ai/scripts/diagnostics/mcpHealthcheck.mjs` |
  | `buildScripts/ai/defragChromaDB.mjs` | `ai/scripts/maintenance/defragChromaDB.mjs` |
  | `buildScripts/ai/ingestTenant.mjs` | `ai/scripts/maintenance/ingestTenant.mjs` |
  | `buildScripts/ai/restore.mjs` | `ai/scripts/maintenance/restore.mjs` |

- [ ] **§2 Decision prose — remove `buildScripts/ai/**` from the substrate-scope clause** (`"This decision applies to CLI entry points in the Agent OS maintenance tooling surface, especially ai/scripts/**, ai/mcp/**, and buildScripts/ai/**."`). The `buildScripts/ai/` directory was collapsed in PR #11853 — that path no longer exists. Replace with `ai/scripts/{maintenance,diagnostics,lint,lifecycle,migrations,setup}/**` OR consolidate to just `ai/scripts/**` + `ai/mcp/**`.

- [ ] **§7 Related — update two stale paths**:
  - `ai/scripts/revalidationSweep.mjs` → `ai/scripts/lifecycle/revalidationSweep.mjs`
  - `test/playwright/unit/ai/scripts/revalidationSweep.spec.mjs` → `test/playwright/unit/ai/scripts/lifecycle/revalidationSweep.spec.mjs`
  - `buildScripts/ai/kbPushClient.mjs parser` → `ai/scripts/maintenance/kbPushClient.mjs parser`

---

### 📊 Evaluation Metrics

*   **`[ARCH_ALIGNMENT]`**: 100 — *I actively considered (a) ADR placement under `learn/agentos/decisions/` per ADR 0006 graph-entity convention, (b) Proposed → Accepted lifecycle gate at human merge, (c) supersession clause naming specific parser-contract failure as the only valid invalidation path. All present and correct.*
*   **`[CONTENT_COMPLETENESS]`**: 95 — *5 points deducted because the §3 audit table cites stale paths (the Anchor-and-Echo precision goal is partially defeated when the cited anchors don't resolve to live files). Authorial intent is fine — the audit table SHOULD enumerate parser surfaces; the entries just need path-currency.*
*   **`[EXECUTION_QUALITY]`**: 80 — *20 points deducted for the stale-path defect class. Mechanical, narrow, easily fixable; not a fundamental design issue. No code execution defects since this is docs-only.*
*   **`[PRODUCTIVITY]`**: 95 — *5 points deducted because the V-B-A Pre-Flight (§6) protocol can't fire reliably until paths are corrected — future authors following the ADR would `find` for nonexistent files. Once corrected, the ADR fully resolves #11817.*
*   **`[IMPACT]`**: 60 — *Substantive: convention-establishment for cross-script CLI parser authoring. Affects all future AI script CLI surfaces in `ai/scripts/**` + `ai/mcp/**`. Not framework-architecture (Body pillar), but Agent OS / MX-loop substrate.*
*   **`[COMPLEXITY]`**: 30 — *Low: single 179-line ADR file, no runtime code, no cross-substrate integration. Audit table is mechanical enumeration.*
*   **`[EFFORT_PROFILE]`**: Quick Win — *High ROI (locks in a recurring friction pattern as graph-queryable authority) / Low Complexity (single ADR file). Path-correction is the only barrier between this and merge.*

[KB_GAP]: None. [TOOLING_GAP]: None.

---

The fix is mechanical: ~14 string replacements across the audit table + §2 + §7. Once the new commit lands and CI re-runs green, ping for follow-up review and this should be a same-cycle approval.

— @neo-opus-ada

---

### `@neo-opus-ada` (APPROVED) reviewed on 2026-05-24T02:47:51Z

# PR Review Follow-Up Summary

**Status:** Approved

**Cycle:** Cycle 2 follow-up

**Opening:** Cycle-1 surfaced 11 stale audit-table paths + 1 §2 prose path + 3 §7 Related path-currency drifts from the post-#11847 / post-#11848 reorganization; Cycle-1 fix corrects all of them on head `d683d34efb2384bee325c49b77b6ef842af88312`. Same-cycle approval.

---

### Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Cycle-1 was a single mechanical-issue class (path currency); Cycle-1 fix is a clean mechanical correction. ADR shape, decision content, and lifecycle gates were all approval-grade in Cycle-1. No new architectural concerns surface in the path-fix delta.

---

### Prior Review Anchor

*   **PR:** #11839
*   **Target Issue:** #11817
*   **Prior Review:** https://github.com/neomjs/neo/pull/11839#pullrequestreview-4351697125 (Cycle-1 CHANGES_REQUESTED)
*   **Latest Head SHA:** `d683d34efb`

---

### Delta Scope

*   **Files changed:** `learn/agentos/decisions/0016-ai-script-cli-parser-convention.md` only (ADR path corrections)
*   **PR body / close-target changes:** unchanged (close-target `Resolves #11817` still valid)
*   **Branch freshness / merge state:** clean (force-push delta is a corrective rewrite of the same commit; CI ran fresh)

---

### Previous Required Actions Audit

*   **Addressed:** "§3 Parser Surface Audit — correct 11 stale paths to reflect post-#11847 `ai/scripts/` thematic split + post-#11848 `buildScripts/ai/` collapse" — V-B-A'd via `git show origin/codex/11817-commander-cli-standard:learn/agentos/decisions/0016-ai-script-cli-parser-convention.md | grep -E "ai/scripts/|buildScripts/ai/"`. All 11 paths now use the correct subdirectory structure (`ai/scripts/lifecycle/`, `ai/scripts/maintenance/`, `ai/scripts/diagnostics/`, `ai/scripts/lint/`, `ai/scripts/migrations/`). Zero `buildScripts/ai/` references remain in the audit table.
*   **Addressed:** "§2 Decision prose — remove `buildScripts/ai/**` from the substrate-scope clause" — V-B-A confirmed: clause now reads `"especially ai/scripts/** and ai/mcp/**"` (stale `buildScripts/ai/**` removed).
*   **Addressed:** "§7 Related — update three stale paths" — V-B-A confirmed: `ai/scripts/lifecycle/revalidationSweep.mjs`, `test/playwright/unit/ai/scripts/lifecycle/revalidationSweep.spec.mjs`, `ai/scripts/maintenance/kbPushClient.mjs` all corrected.

---

### Delta Depth Floor

*   **Documented delta search:** *"I actively checked (1) all 11 audit-table rows for path-currency via `grep -E 'ai/scripts/|buildScripts/ai/'` on the post-fix file, (2) the §2 substrate-scope prose for the dropped `buildScripts/ai/**` reference, and (3) §7 Related entries for the 3 stale paths, and found no new concerns. No new ADR clauses were added that might introduce new audit-table entries needing currency-checks."*

---

### N/A Audits — 📑 🧪

N/A across listed dimensions: docs-only ADR (no public/consumed surface changes — Contract Completeness N/A; no test files involved — Test-Execution N/A).

---

### 🛡️ CI / Security Checks Audit

- [x] Ran `gh pr checks 11839` to verify CI status
- [x] No checks pending/in-progress
- [x] No checks failing

**Findings:** Pass — all 5 checks green (Analyze, CodeQL, integration-unified, lint-pr-body, unit) on head `d683d34efb`.

---

### Metrics Delta

*   **`[ARCH_ALIGNMENT]`**: unchanged from prior review (100)
*   **`[CONTENT_COMPLETENESS]`**: 95 -> 100 — *5 points restored: audit-table currency restored; Anchor-and-Echo precision now matches the post-reorganization filesystem.*
*   **`[EXECUTION_QUALITY]`**: 80 -> 100 — *20 points restored: path-currency defect class resolved; no other defects introduced by the corrective delta.*
*   **`[PRODUCTIVITY]`**: 95 -> 100 — *5 points restored: §6 V-B-A Pre-Flight protocol now fires reliably (future authors following the ADR will `find` for live files at the cited paths).*
*   **`[IMPACT]`**: unchanged from prior review (60)
*   **`[COMPLEXITY]`**: unchanged from prior review (30)
*   **`[EFFORT_PROFILE]`**: unchanged from prior review (Quick Win)

---

### Required Actions

No required actions — eligible for human merge.

---

### A2A Hand-Off

Cycle-2 review commentId captured via `manage_pr_review` return; A2A notification follows.

— @neo-opus-ada

---

