[finding] AGENTS.md Documentation Guardrails table names content/docs/guides/ — the directory does not exist on main

Observation

AGENTS.md's Documentation Guardrails table carries the row:

Path	Type	Rule
`content/docs/guides/`	hand-written	Update `meta.json` when adding pages.

but content/docs/ on current main (93304c2) contains no guides/ directory at all (top-level dirs: ai, api, automation, capabilities, concepts, data-modeling, deployment, getting-started, kernel, permissions, plugins, protocol, references, releases, ui).

Noticed while exercising #9866's provenance recompute: a temp page write to content/docs/guides/… failed with "No such file or directory" because the table row pointed at a directory that is not there.

Why it matters (mildly)

The table is the reader's map of which docs trees are hand-written vs generated vs release-owned. A row naming a missing directory is the same drift class the docs-audit gate exists to catch in ALL_HANDWRITTEN (#4851) — here it is prose, so nothing checks it. The meta.json advice the row carries is real and applies to the trees that DO exist; it is anchored to a ghost path.

Suggested disposition

Either drop the row or rename it to the tree(s) that took over guide content (e.g. getting-started/ / capabilities/). AGENTS.md is a governed surface — the fix is a small governed PR, human merge.

Observation-class: filed unassigned, finding label, no pm:queue, per triage discipline.

Triage: routed domain:skills — AGENTS.md content correction (Documentation Guardrails table names a directory absent on main); AGENTS.md is instruction-architecture surface owned by the skills lane, and the fix is a governed-face PR (draft-only, human merge).

Generated by Claude Code

Grading (skills seat, session session_01RMTpSRF5CjMmQBFfPtPCwJ, 2026-08-23 concentrated round): promoted finding → pm:queue. One-row governed fix in AGENTS.md's Documentation Guardrails table: verify against current main which tree(s) actually took over guide content, then re-point or drop the content/docs/guides/ row (implementer verifies, does not guess). Draft + human merge; AGENTS.md is at ceiling — a one-row net change must stay ratchet-neutral or pay.

Generated by Claude Code

Claim: PM loop round 1, wave 3
Session: session_01RMTpSRF5CjMmQBFfPtPCwJ
Branch: claude/issue-11079-guides-ghost-row
Worktree: objectstack-issue-11079
Domain: domain:skills
File surface: AGENTS.md (one Documentation Guardrails table row) (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus — no path-derived mandate; governed root instruction file, verification-first one-row change
Clause-②: no
Serial constraints cleared: none in flight on AGENTS.md — wave-3 siblings disjoint; note AGENTS.md sits at its ratchet ceiling (961/961) — the change must be ratchet-neutral or pay per the gate's remedy.

Generated by Claude Code

{
  "issue": 11079,
  "status": "done",
  "branch": "claude/issue-11079-guides-ghost-row",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/11282",
  "premise_still_valid": true,
  "premise_check": {
    "a_row_still_present": "true — AGENTS.md:547 on origin/main carried the `content/docs/guides/` | hand-written | Update meta.json when adding pages row",
    "b_directory_absent": "true — `git ls-tree origin/main content/docs/guides/` returns empty; the 15 real dirs are ai, api, automation, capabilities, concepts, data-modeling, deployment, getting-started, kernel, permissions, plugins, protocol, references, releases, ui",
    "issue_body_integrity": "intact — raw REST body is 1427 chars, ends at '...per triage discipline.', no control bytes"
  },
  "disposition": "re-point (NOT drop)",
  "evidence_for_re_point_vs_drop": {
    "no_tree_took_over": "content/docs/guides/ NEVER existed. Across all 512 reachable commits (git rev-list --all --count = 512) there is no add/rename/delete of any *guides* path: `git log --all --follow -- content/docs/guides`, `git log --all --diff-filter=D -- content/docs/guides/*` and `git log --all --name-only --diff-filter=ADR -- *guides*` are all EMPTY. So 'which tree took over' has the answer: none — the row was a ghost from the start, not a stale pointer to relocated content. The issue's guessed targets are wrong on their own terms: getting-started/ was ALREADY its own row in this table, and capabilities/ is just one more hand-written tree.",
    "drop_condition_is_false": "The card allowed a drop only if the rule the row carries were already stated for the real trees elsewhere in the table. `grep -n meta.json AGENTS.md` returns EXACTLY ONE hit — line 547, the ghost row itself. Dropping would have deleted the meta.json rule from AGENTS.md outright. Hence re-point.",
    "rule_is_real_and_universal": "All 13 hand-written trees have their own meta.json, each an explicit ordered pages array with NO rest-spread (grep -l for the rest literal over every content/docs meta.json is empty), so an unlisted page really is absent from the nav. Per-tree pages/mdx counts: ai 9/9, api 12/12, automation 10/10, capabilities 11/11, concepts 6/6, data-modeling 18/18, deployment 12/9, getting-started 11/9, kernel 8/6, permissions 21/21, plugins 5/5, protocol 7/4, ui 17/16 (excesses are subdirectory refs such as kernel/contracts/, protocol/objectql/).",
    "cross_check_against_gate_owned_list": "check:docs-audit-scope maintains the generated ALL_HANDWRITTEN block in .claude/workflows/docs-accuracy-audit.js — 189 hand-written docs over 14 trees + 3 root files, regenerated from the tree. It contains no guides path. That gate-owned list is the authoritative population; the prose row was the only thing claiming guides/ exists.",
    "why_the_replacement_does_not_enumerate": "An enumeration in prose is the exact drift class this issue reports, and the trees are already enumerated (and kept fresh) by the gate. The new row is defined by EXCLUSION — 'every tree except references/ and releases/ above' — which stays true when a tree is added."
  },
  "summary": "Re-pointed the Documentation Guardrails ghost row in AGENTS.md. Verification (not guessing) showed content/docs/guides/ never existed in 512 commits of history, so no tree took over its content and there is no rename to follow; and the meta.json advice it carried is the ONLY statement of that rule in all of AGENTS.md, so the drop condition the card specified is false. The row is therefore re-pointed to the hand-written trees generically (every content/docs tree except references/ and releases/), carrying the meta.json rule forward and stating explicitly that the three rows below it are named examples rather than the whole set. One row in, one row out — ratchet-neutral. Sole file touched: AGENTS.md.",
  "files_changed": ["AGENTS.md"],
  "diff_shape": "1 file changed, 1 insertion(+), 1 deletion(-) — AGENTS.md stays 961 lines",
  "ratchet_verdict_line": "check-skill-line-ratchet: AGENTS.md is 961 lines (ceiling 961; headroom 0).",
  "tests": "Gates derived with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no paths passed — the script read the change set itself: '1 path(s) vs merge base 050d8d868', AGENTS.md). It named 7 matched families, including the governed-merges family and the ratchet via the AGENTS.md/** root-file watch hints, exactly as the dispatch predicted. All 7 run GREEN as a union at final commit d4c72da9 (clean working tree), through scripts/pm/os-verify-lock.sh — VERDICT command-exit 0 · held the lock 7s · waited 0s. Verdict lines quoted from the gates' own output, exit codes captured before any pipe: check:docs-audit-scope RC=0 'docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).'; check:pm-governed-merges RC=0 'check-governed-merges --self-test: 119 assertions'; check:pm-governed-prose RC=0 'check-governed-prose: 2 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.'; check:pm-skill-id-lint RC=0 'check-skill-id-lint: 17 file(s) clean (pattern for 3+ digit IDs).'; check:pm-skill-ratchet RC=0 'check-skill-line-ratchet: AGENTS.md is 961 lines (ceiling 961; headroom 0).'; check:required-contexts RC=0 'check-required-contexts: 6 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).'; node scripts/check-required-contexts.mjs (required-set-patrol) RC=0. No unit tests apply — the change is one prose table row, no code. No ablation applies. NUL/control-byte self-scan on AGENTS.md and on the PR body: clean.",
  "deviations": [
    "First run of check:required-contexts exited 1 with ERR_MODULE_NOT_FOUND for 'yaml' — I had skipped pnpm install in the fresh worktree; not a gate failure. Installed, re-ran, green. Recorded rather than silently re-run.",
    "pnpm install --workspace-concurrency=2 was rejected by pnpm v10.31.0 as an unknown option on the install command; re-ran without it.",
    "No local repo-wide scan was run (pnpm lint etc.): dispatch-gates placed the change set in 7 families and none of them is a repo-wide lint. This is the derivation's own answer, not a narrowing I chose."
  ],
  "governed_surface": "AGENTS.md is on the governed register. PR #11282 opened as DRAFT (confirmed via REST: draft=true, base=main), never flipped ready, no auto-merge requested, human merge only — stated in the PR body.",
  "labels": "skip-changeset applied via the additive POST /issues/11282/labels endpoint and READ BACK after the bots settled: ['documentation', 'size/xs', 'skip-changeset'] — it survived the size-labeler's run. No changeset written (instruction-file prose only, nothing published).",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

ACCEPT (skills seat, session session_01RMTpSRF5CjMmQBFfPtPCwJ, reviewer of record) — PR #11282.

Checklist conclusions, verified against GitHub: draft ✓ · base main ✓ · Fixes #11079 first line ✓ · changed files = exactly AGENTS.md, one row in one row out, 961/961 ratchet-neutral with the gate's own verdict quoted ✓ · skip-changeset read back ✓. Diff read against the RAW patch (the PR body's rendering shows an empty span where content/docs/<tree>/ sits — that is the MCP read-path artifact this lane just landed a fact-table row about; the committed bytes are intact and correct). The re-point-not-drop disposition is evidence-backed, not guessed: guides/ never existed across all 512 reachable commits (no rename trail to follow — the card's own suggested targets were wrong on their own terms, and the dev proved it rather than obeying), and the ghost row was the ONLY statement of the meta.json rule in the file, so dropping would have deleted a real rule. The exclusion-defined replacement (every tree except references/ and releases/ above) deliberately avoids re-creating the enumeration-drift class this card reports, with the gate-owned ALL_HANDWRITTEN list as the authoritative population — the right shape.

Governed surface (AGENTS.md): PR stays draft, human merge only; review requested from os-zhuang (author claude[bot]).

Generated by Claude Code

Navigation Menu

Repository navigation

[finding] AGENTS.md Documentation Guardrails table names `content/docs/guides/` — the directory does not exist on main #11079

Observation

Why it matters (mildly)

Suggested disposition

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[finding] AGENTS.md Documentation Guardrails table names content/docs/guides/ — the directory does not exist on main #11079

Description

Observation

Why it matters (mildly)

Suggested disposition

Activity

os-zhuang commented on Aug 23, 2026

os-zhuang commented on Aug 23, 2026

os-zhuang commented on Aug 23, 2026

os-zhuang commented on Aug 23, 2026

os-zhuang commented on Aug 23, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[finding] AGENTS.md Documentation Guardrails table names `content/docs/guides/` — the directory does not exist on main #11079