Skip to content

feat(ingest): prompt for a description at authoring time (RM8)#91

Merged
ChelseaKR merged 1 commit into
mainfrom
claude/project-code-review-merge-jz4qwg
Jul 14, 2026
Merged

feat(ingest): prompt for a description at authoring time (RM8)#91
ChelseaKR merged 1 commit into
mainfrom
claude/project-code-review-merge-jz4qwg

Conversation

@ChelseaKR

Copy link
Copy Markdown
Owner

What this change does

Implements the remaining code portion of RM8 (authoring-time accessibility prompts). The ingest CLI already nudged on a missing transcript for audio/video, but it set only title + publisher on a record's Dublin Core and had no way to supply a description and no prompt when one was absent.

  • Adds a repeatable --description TEXT flag to ledger ingest that populates dublin_core.description.
  • Adds a non-blocking stderr advisory when a record has no description — a description is what makes an item discoverable and gives a reader (including a screen-reader user) context beyond the title.
  • Updates the ACR.md 504 row and the RM8 research-roadmap entry to reflect the new authoring prompt.

Why

ACR criterion 504 (Authoring Tools) was Partially Supports specifically because "the CLI does not yet actively prompt an author to supply accessibility information." This closes the metadata half of that gap (transcript prompting already existed). Per-payload alt text for a future image payload type remains the open part of RM8 and is noted as such.

Checklist

  • Primary ISO/IEC 25010 characteristic: interaction capability (accessibility of the authored record).
  • make verify equivalents green locally: ruff check + ruff format --check clean; mypy clean (57 files); full pytest green (1002 passed, 2 skipped). One unrelated test (test_consent_store_write_failure_raises_without_leaking) fails only under this sandbox's root uid because it simulates a write failure via chmod 0o500, which root bypasses — it fails identically on origin/main with this diff stashed, and passes on CI's non-root runner.
  • No-outing: advisories name only the record's own title-less metadata state; no contributor identity or sealed value reaches any output. The description is author-supplied public Dublin Core, not a sealed field.
  • Redaction-safe: tests use synthetic values only.
  • Tests added: tests/test_metadata_advisory.py — a title-only ingest warns "no description"; --description silences it and persists the value.
  • Observability: adds one new advisory line to stderr (non-blocking), consistent with the existing transcript/preservation advisories.
  • No read surface changed (CLI stderr only), so the accessibility browse-gate is unaffected; advisories remain English CLI notes like the existing ones (no i18n catalog change).
  • No preservation format, dependency, guardrail, or identity path changed; no new ADR required.
  • Rollback: no state/deploy effect — additive optional flag, default behavior unchanged except the new advisory line.
  • Docs updated: ACR.md, docs/RESEARCH-ROADMAP.md; CHANGELOG.md under Unreleased.

Notes for reviewers

The advisory deliberately stays an English CLI stderr note, matching the two existing ingest advisories (transcript, preservation) — those are operator-facing and not routed through the gettext catalog, so no EN/ES/FR/AR translation is required here. The web browse surface (which is i18n'd) is untouched.


Generated by Claude Code

The ingest CLI already nudged on a missing transcript for audio/video but set
only title+publisher on a record's Dublin Core, with no way to supply a
description and no prompt when it was absent. Add a repeatable --description
flag that populates dublin_core.description, and a non-blocking stderr advisory
when a record has none: a description is what makes an item discoverable and
gives a reader (including a screen-reader user) context beyond the title.

Advisories stay English CLI stderr notes, matching the existing transcript and
preservation advisories (no i18n catalog change). Updates the ACR 504 row and
the RM8 research-roadmap entry to reflect the new authoring prompt; per-payload
alt text for a future image payload type remains the open part of RM8.

Tests: a title-only ingest warns 'no description'; --description silences it and
persists the value on the record's Dublin Core.

Signed-off-by: ChelseaKR <3114598+ChelseaKR@users.noreply.github.com>
@ChelseaKR
ChelseaKR merged commit d6f9791 into main Jul 14, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant