feat: dossier parser + spec validation for AGENTS.md (lib/dossier.sh) #464

New issue

Closed

opened 2026-08-08 23:09:56 +00:00 by igor · 0 comments

igor commented

2026-08-08 23:09:56 +00:00

Collaborator

Implements the machine half of docs/agents-md-spec.md (on master as of today). Read that spec first — it is the authoritative contract; this ticket summarizes, the spec governs.

Deliverables

lib/dossier.sh — the dossier parser:
- dossier_get <checkout_dir> <key> — echoes the value for <key> from the root AGENTS.md Metadata block; empty + nonzero when absent. Extraction rule per spec: the FIRST fenced code block after the literal heading ## Metadata, parsed as flat key: value scalar lines (grep/awk only — no yaml dependency).
- dossier_keys <checkout_dir> — lists the keys present.
- A fallback path: when the repo has no root AGENTS.md, read the same logical keys from legacy agent.json (url ← .smoke.url, feedback-csv ← .feedback.csv) so existing consumers can switch to dossier_get without behavior change during migration.
Validation integration (lib/repo-checks.sh / bin/validate-repo.sh) — implement the spec's "Validation contract" section exactly:
- Absent root AGENTS.md → legacy validation path, NOT a failure (migration gate).
- Present but nonconforming → hard fail with a specific, greppable reason line.
- Checks: required sections in spec order with exact heading strings; ## Metadata last with exactly one fenced block of flat scalars; closed key vocabulary; type always required; url required for site types (arcade, game, content, api, personal); H1 equals url host with leading www. stripped; KPI entries carry a measurement source (separator --, en/em dash, or comma) or the section is exactly (none yet); nested AGENTS.md files contain no ## Metadata.
Tests — bin/test-dossier.sh (added to the suite the same way as the other bin/test-*.sh): happy path, each validation failure mode above, the absent-vs-nonconforming gate, the agent.json fallback, and a fixture with a nested prose-only AGENTS.md.

Explicitly OUT of scope (follow-up tickets)

The interactive onboarding wizard (bin/onboard.sh).
Switching automerge/feedback call sites to dossier_get (they keep reading agent.json directly for now; the fallback in deliverable 1 is what makes the later cutover a one-line change per call site).
Any per-repo AGENTS.md conversions.

Notes for the implementer

No repo currently has a conforming dossier — the migration gate means validation behavior for the whole fleet must be UNCHANGED by this PR. That invariant belongs in the tests.
Keep the diff under the 400-line cap; if tests push past it, prefer trimming fixture verbosity over trimming failure-mode coverage.

Implements the machine half of `docs/agents-md-spec.md` (on master as of today). Read that spec first — it is the authoritative contract; this ticket summarizes, the spec governs. ## Deliverables 1. **`lib/dossier.sh`** — the dossier parser: - `dossier_get <checkout_dir> <key>` — echoes the value for `<key>` from the root `AGENTS.md` Metadata block; empty + nonzero when absent. Extraction rule per spec: the FIRST fenced code block after the literal heading `## Metadata`, parsed as flat `key: value` scalar lines (grep/awk only — no yaml dependency). - `dossier_keys <checkout_dir>` — lists the keys present. - A fallback path: when the repo has no root `AGENTS.md`, read the same logical keys from legacy `agent.json` (`url` ← `.smoke.url`, `feedback-csv` ← `.feedback.csv`) so existing consumers can switch to `dossier_get` without behavior change during migration. 2. **Validation integration** (`lib/repo-checks.sh` / `bin/validate-repo.sh`) — implement the spec's "Validation contract" section exactly: - Absent root `AGENTS.md` → legacy validation path, NOT a failure (migration gate). - Present but nonconforming → hard fail with a specific, greppable reason line. - Checks: required sections in spec order with exact heading strings; `## Metadata` last with exactly one fenced block of flat scalars; closed key vocabulary; `type` always required; `url` required for site types (`arcade`, `game`, `content`, `api`, `personal`); H1 equals `url` host with leading `www.` stripped; KPI entries carry a measurement source (separator `--`, en/em dash, or comma) or the section is exactly `(none yet)`; nested `AGENTS.md` files contain no `## Metadata`. 3. **Tests** — `bin/test-dossier.sh` (added to the suite the same way as the other `bin/test-*.sh`): happy path, each validation failure mode above, the absent-vs-nonconforming gate, the agent.json fallback, and a fixture with a nested prose-only AGENTS.md. ## Explicitly OUT of scope (follow-up tickets) - The interactive onboarding wizard (`bin/onboard.sh`). - Switching automerge/feedback call sites to `dossier_get` (they keep reading `agent.json` directly for now; the fallback in deliverable 1 is what makes the later cutover a one-line change per call site). - Any per-repo AGENTS.md conversions. ## Notes for the implementer - No repo currently has a conforming dossier — the migration gate means validation behavior for the whole fleet must be UNCHANGED by this PR. That invariant belongs in the tests. - Keep the diff under the 400-line cap; if tests push past it, prefer trimming fixture verbosity over trimming failure-mode coverage.

igor added the

Agent

label

2026-08-08 23:09:57 +00:00

igor self-assigned this

2026-08-08 23:10:08 +00:00

igor referenced this issue from a pull request that will close it,

2026-08-08 23:24:09 +00:00

feat: add dossier parser + spec validation for AGENTS.md (lib/dossier.sh) #465

igor added spent time

2026-08-08 23:24:10 +00:00

13 minutes 29 seconds