Sidecar Lint & Repair
Citation-sidecar hygiene for a research corpus. Two read-only diagnostics
(sidecar-lint, sidecar-lint --orphans) and two repair tools
(sidecar-repair) that backfill authors and canonicalize affiliations.
These operate on documentation/citations/REF-*-citations.md under the
resolved corpus root (AIWG_CORPUS_ROOT env > research.corpusRoot in
.aiwg/aiwg.config > cwd).
How to run
# Structural lint — missing sections/frontmatter, duplicate table headers
aiwg corpus sidecar-lint
# Zero-edge orphans (no incoming AND no outgoing edges), titled from the analysis doc
aiwg corpus sidecar-lint --orphans
# Repair: backfill (see REF doc) authors + normalize affiliations — DRY-RUN
aiwg corpus sidecar-repair
# Repair for real
aiwg corpus sidecar-repair --write
# Restrict to one repair
aiwg corpus sidecar-repair --authors-only --write
aiwg corpus sidecar-repair --affiliations-only --write
# Write a report to a file (resolved against the corpus root)
aiwg corpus sidecar-lint --out reports/sidecar-lint.txt
What sidecar-lint checks
| Issue |
Meaning |
missing-frontmatter / malformed-frontmatter |
No --- block, or no closing --- |
frontmatter-missing-{ref,title,type} |
Required sidecar frontmatter field absent |
missing-outgoing-section / missing-incoming-section |
No Outgoing/Incoming H2 (merge-redirects with status: merged / MERGED INTO are exempt) |
duplicate-table-headers-count=N |
Two | # | Title headers under one sub-header — the doubled-append signature |
--orphans lists sidecars with zero REF edges in either section (lenient
scan: any REF-NNN token in an Outgoing/Incoming section counts as an edge,
regardless of table-column naming).
What sidecar-repair does
- Authors — for sidecars whose
authors: still contains (see REF doc),
parse the analysis doc's ## Citation block and write structured
authors: - name: entries. Handles Last, F. M. initials, &/and
separators, et al. truncation, and institutional single-authors.
- Affiliations — normalize
affiliation-primary to a canonical
PROF-O-{slug} when unambiguous; multi-org / parenthetical / unknown values
are left untouched and reported as ambiguous. The canonical map ships as a
default and is overridable per-corpus via
documentation/profiles/orgs/affiliation-map.yaml (slug → variant names).
Both default to dry-run; nothing is written without --write.
Reconciliation with research-lint
This is the sidecar-structural layer. The research-lint skill runs the
generic aiwg lint --ruleset research over .aiwg/research/ (note-level
frontmatter, REF-id uniqueness, citation-resolves, note orphans). Those checks
do not look inside citation-sidecar structure. Use:
research-lint for note/corpus-wide referential integrity and the lint ruleset engine.sidecar-lint for the citation-sidecar internals (Outgoing/Incoming sections, edge tables, author/affiliation metadata) and edge-graph orphans.
They compose; neither duplicates the other.
Triggers
- "lint the citation sidecars"
- "find orphaned sidecars"
- "fix (see REF doc) authors"
- "normalize affiliations to PROF-O"
- "sidecar lint" / "sidecar repair"
Notes
- All four operations are TS-native (
src/artifacts/corpus-tools/sidecar-lint.ts,
sidecar-repair.ts) — ports of section9 lint_sidecars.py, find_orphans.py,
fix_broken_authors.py, normalize_affiliation.py.
- Author backfill matches the source's trailing-dot handling (a final initial
like
Hinton, G. is stored Hinton, G) for idempotency against corpora
already processed by the original script.
1---2namespace: aiwg3platforms: [all]4name: sidecar-lint5description: Lint and repair citation sidecars in a research corpus — structural integrity (missing Outgoing/Incoming sections, missing frontmatter ref/title/type, doubled-append duplicate table headers), zero-edge orphan detection, (see REF doc) author backfill from the analysis citation block, and affiliation-primary canonicalization to PROF-O slugs. Runs via `aiwg corpus sidecar-lint` / `aiwg corpus sidecar-repair`.6commandHint:7 argumentHint: "sidecar-lint [--orphans] | sidecar-repair [--authors-only|--affiliations-only] [--write]"8 allowedTools: Read, Bash, Write9 model: haiku10 category: research-validation11 modelRole: efficiency12 modelTier: economy13---1415# Sidecar Lint & Repair1617Citation-sidecar hygiene for a research corpus. Two read-only diagnostics18(`sidecar-lint`, `sidecar-lint --orphans`) and two repair tools19(`sidecar-repair`) that backfill authors and canonicalize affiliations.2021These operate on `documentation/citations/REF-*-citations.md` under the22resolved corpus root (`AIWG_CORPUS_ROOT` env > `research.corpusRoot` in23`.aiwg/aiwg.config` > cwd).2425## How to run2627```bash28# Structural lint — missing sections/frontmatter, duplicate table headers29aiwg corpus sidecar-lint3031# Zero-edge orphans (no incoming AND no outgoing edges), titled from the analysis doc32aiwg corpus sidecar-lint --orphans3334# Repair: backfill (see REF doc) authors + normalize affiliations — DRY-RUN35aiwg corpus sidecar-repair3637# Repair for real38aiwg corpus sidecar-repair --write3940# Restrict to one repair41aiwg corpus sidecar-repair --authors-only --write42aiwg corpus sidecar-repair --affiliations-only --write4344# Write a report to a file (resolved against the corpus root)45aiwg corpus sidecar-lint --out reports/sidecar-lint.txt46```4748## What `sidecar-lint` checks4950| Issue | Meaning |51|-------|---------|52| `missing-frontmatter` / `malformed-frontmatter` | No `---` block, or no closing `---` |53| `frontmatter-missing-{ref,title,type}` | Required sidecar frontmatter field absent |54| `missing-outgoing-section` / `missing-incoming-section` | No Outgoing/Incoming H2 (merge-redirects with `status: merged` / `MERGED INTO` are exempt) |55| `duplicate-table-headers-count=N` | Two `\| # \| Title` headers under one sub-header — the doubled-append signature |5657`--orphans` lists sidecars with **zero** REF edges in either section (lenient58scan: any `REF-NNN` token in an Outgoing/Incoming section counts as an edge,59regardless of table-column naming).6061## What `sidecar-repair` does6263- **Authors** — for sidecars whose `authors:` still contains `(see REF doc)`,64 parse the analysis doc's `## Citation` block and write structured65 `authors: - name:` entries. Handles `Last, F. M.` initials, `&`/`and`66 separators, `et al.` truncation, and institutional single-authors.67- **Affiliations** — normalize `affiliation-primary` to a canonical68 `PROF-O-{slug}` when unambiguous; multi-org / parenthetical / unknown values69 are left untouched and reported as ambiguous. The canonical map ships as a70 default and is **overridable per-corpus** via71 `documentation/profiles/orgs/affiliation-map.yaml` (slug → variant names).7273Both default to **dry-run**; nothing is written without `--write`.7475## Reconciliation with `research-lint`7677This is the **sidecar-structural** layer. The `research-lint` skill runs the78generic `aiwg lint --ruleset research` over `.aiwg/research/` (note-level79frontmatter, REF-id uniqueness, citation-resolves, note orphans). Those checks80do not look inside citation-sidecar structure. Use:8182- **`research-lint`** for note/corpus-wide referential integrity and the lint ruleset engine.83- **`sidecar-lint`** for the citation-sidecar internals (Outgoing/Incoming sections, edge tables, author/affiliation metadata) and edge-graph orphans.8485They compose; neither duplicates the other.8687## Triggers8889- "lint the citation sidecars"90- "find orphaned sidecars"91- "fix (see REF doc) authors"92- "normalize affiliations to PROF-O"93- "sidecar lint" / "sidecar repair"9495## Notes9697- All four operations are TS-native (`src/artifacts/corpus-tools/sidecar-lint.ts`,98 `sidecar-repair.ts`) — ports of section9 `lint_sidecars.py`, `find_orphans.py`,99 `fix_broken_authors.py`, `normalize_affiliation.py`.100- Author backfill matches the source's trailing-dot handling (a final initial101 like `Hinton, G.` is stored `Hinton, G`) for idempotency against corpora102 already processed by the original script.
jmagly 