fix: resolve reference labels while preserving inline citations

[atlas-coding-agent]

Problem / Motivation

Completed watercolor and chess answers exposed internal reference labels and ranges instead of source links. Citation grouping also hid distinct passages from the same video. Model instructions discouraged citations beside individual claims, despite renderer support.

What changed

Schema, answer guidance, and finalization instructions now request citations beside the claims they support. Related claims can share a natural paragraph with different inline citations. Tables retain inline citations. Writing guidance gently favors bullets, numbered steps, and comparison tables when they improve readability, while allowing short prose and respecting requested formats. Every cited reference must come from supplied evidence and also appear in the block's evidenceIds.

Recognized labels, parenthesized groups, and valid inclusive ranges resolve to supplied evidence. Expansion requires every range member to exist. Code, Markdown links, URLs, and recognized literal examples remain protected in both normalization passes. Declared references not placed inline are appended.

Citation grouping preserves separate passages and merges overlapping excerpts only when their source kind, source, and video match.

flowchart LR
  A[Before: visible reference labels] --> B[After: validated links beside claims]
  C[Retained: supplied evidence IDs] --> B
  D[Retained: distinct passages] --> E[Separate timestamps]

Loading

The answer keeps inline attribution while reference labels become usable links.

Tests

Full platform pipeline before the final readability-only prompt edit: 2,427 passed, 56 skipped. After that edit, all 118 prompt/finalizer tests passed. This includes 1,964 Node tests, 11 video-catalog tests, 354 Workers integrations, 49 processor tests, and 49 frame tests. TypeScript and documentation checks passed. Regressions cover both reported sessions, ranges, literal/link protection, inline prose/tables, and model-facing prompt/schema consistency.

Compatibility and limitations

Unknown or malformed labels can remain visible. Saved answers are not backfilled. Live model behavior and fresh CI remain unverified.

[vercel]

@kiro-agent is attempting to deploy a commit to the devhims' projects Team on Vercel.

A member of the Team first needs to authorize it.

[devhims]

Review of exact head 0270d0f: changes needed before merge — integration check unresolved.

Independent review found the prior material citation-normalization/grouping regressions resolved. Actual execution passed 291/291 focused tests, 19/19 independent adversarial/compatibility checks and TypeScript. The local default Node suite passed 1,898/1,899; its translation-language failure at youtube-client.test.ts:677 also reproduced on base f858c53 with the same dependencies.

P2 validation blocker: CI now reports a different failure at platform/test/agent-runtime-do.integration.test.ts:290: the internal finalization result includes the intended sourceKind: 'video', while the exact expected citation fixture omits it. This blocks Platform checks and skips the later Worker-startup profile. Update the internal expectation to verify the new metadata while retaining public-field stripping checks, then rerun CI. CI Workerd result: 353 passed, 1 failed. Job: https://github.com/devhims/video2ctx/actions/runs/38872242343/job/116878821676

Non-blocking bounded-parser limitation: structured-answer.ts:145 recognizes adjacent ASCII call names; unformatted fn (ref_1) and café(ref_1) can still normalize literal arguments. Explicit code spans are protected. This is documented rather than a general programming-language-parser guarantee.

No live production/model retest was performed; these checks establish code behavior, not that all prior live citation accuracy failures are fixed. Draft should remain until the integration failure and remaining checks are resolved.

[devhims]

Re-review of exact head 2a031b3.

The previous integration finding at platform/test/agent-runtime-do.integration.test.ts:290 is resolved. The test-only delta retains exact equality and now expects the authoritative saved source.kind ('video'); it preserves the historical citation without that optional field and all answer/warning/billing/tool assertions. No new material code findings.

Independently executed on this head: affected Workerd integration test passed (1 selected test, 86 unrelated tests skipped), and all 291 focused tests passed, including compact/legacy public-field stripping. Earlier production-code validation at 0270d0f also passed 19 adversarial checks and TypeScript; production code is unchanged in this follow-up.

Verified GitHub Actions run https://github.com/devhims/video2ctx/actions/runs/38874666698: all eight jobs passed, including Platform checks, Platform integration, both dashboard E2E jobs, Web, Auth E2E, Documentation and Library/skill bundle.

Merge verdict: changes needed / external check blocked. The separate Vercel commit status is still failure because this fork's preview deployment needs team authorization. I have not authorized deployment and cannot establish from the available metadata whether that status is a required merge check. Code review is complete, but unconditional merge approval is withheld until that check's applicability or resolution is confirmed.

Remaining nonblocking parser limitations are documented in the PR. No live production/model retest was run, so this does not establish that semantic citation accuracy issues are fixed.

[devhims]

Approve reviewed head ad456eb. No blocking code findings. Prior integration fixture issue is resolved. Verified Verify workflow https://github.com/devhims/video2ctx/actions/runs/38942153231 completed successfully, and the separate Vercel status is now success.

Independent exact-head execution: 326 focused tests, 28 boundary/literal/creator assertions, 87 Agent Workerd integration tests and TypeScript passed. Full default Node suite: 1,933 passed, 1 failed, 56 skipped; the en/es translation expectation at youtube-client.test.ts:677 also failed on prior approved 2a031b3 with the reused local dependencies. This local baseline discrepancy is separate from the successful fresh PR CI.

The new inclusive-range handling verifies every supplied member, rejects missing interior members/reversed/unsafe endpoints, bounds expansion by alias count, and retains evidence IDs/times. It treats the model's range as an inclusive reference convention; numerical adjacency does not establish semantic support for a claim.

Nonblocking limitations:

• P3, structured-answer.ts:118–131: malformed chained ranges such as ref_4 to ref_7 to ref_999 expand the valid prefix and retain the invalid suffix. Consider whole-expression preservation and a regression fixture; no missing evidence is invented.
• P3, structured-answer.ts:100: streaming drafts can still display aliases. The generated/streamed tests verify finalized results, not every draft event. Scope the fix to completed answers.
• Creator-prefixed mixed lists resolve known items individually and retain unknown items; pure alias lists with an unknown member remain unchanged. Existing spaced/non-ASCII call limitations remain documented.

No live product/model retest, original-session semantic validation, or backfill of saved aliases was performed. Approval applies to the bounded rendering change, not a claim that all live citation accuracy issues are fixed.

[devhims]

Review of exact head 71049de: changes needed.

P2: In platform/src/agents/structured-answer.ts:170–230, table detection rejects blockquote-prefixed delimiter rows. A valid GFM blockquoted table with row markers is classified as prose and loses row-level attribution; with empty context-answer evidenceIds its citations disappear. Repro:

> | Claim | Source |
> | --- | --- |
> | A | [cite:ref_1] |
> | B | [cite:ref_2] |

Use Markdown-container-aware table ranges and cover this case.

P3: At structured-answer.ts:224–230, See [docs](https://example.com) (ref_1) for details. joins the protected link and following for when annotation whitespace is removed. Preserve boundary spacing around links and inline code.

Additional consistency case: quoted canonical [cite:e2] with declared evidenceIds=[e1] is excluded by new blockReferences but remains available for downstream finalizer adoption. The earlier code counted it, so this creates divergence between figure/coverage checks and saved references. Validate end-to-end with a real full excerpt ID.

These are static code-traced findings, not executed reproductions. GitHub Verify run38944727036 passed. Independent execution remains blocked by review-service backend errors. Earlier-head approval does not carry over to this redesign. No implementation, push, merge, deployment or live QA performed.

[devhims]

Changes needed on exact head e9ae9cd. Independent execution confirms the previous three findings are fixed: quoted/list tables retain row citations, spacing survives annotation removal, and quoted canonical markers remain literal consistently across validation, finalization, display and source deletion.

P2 — unclosed call text hides application-generated citations. With block text An unfinished example: fn( and declared evidence e1, rendering produces An unfinished example: fn( [cite:e1]. blockReferences returns e1, but answerCitationIds returns none: markdown-citations.ts:116–137 protects the unclosed call through paragraph end, swallowing the citation appended by structured-answer.ts around line200. Research/inspection finalization throws AGENT_CITATION_REQUIRED; context finalization persists no citation and displays the raw marker. Independently reproduced with short and realistic full IDs.

Place application-generated citations outside open literal spans, for example a separate Sources paragraph when needed. Add research/context regressions covering discovery, persistence, display and deletion of the declared citation. This is a bounded code/example edge case, not an observed live session failure.

Actual exact-head checks: 301 focused tests passed; independent regression checks18passed/2failed (both this issue);87AgentWorkerd integration tests passed;TypeScript and diff whitespace check passed. Full default Node suite1908passed/1failed/56skipped; the en/es translation expectation at youtube-client.test.ts:677 is the previously reproduced baseline discrepancy with reused dependencies. Exact parser lockfile versions were installed for this review; no full clean dependency install or live requests were performed.

No implementation edits, push, merge or deployment performed. Earlier approvals do not apply to this latest head.

[devhims]

Review of exact head 32a4cdc: the prior P2 is resolved; no new blocking code findings.

At platform/src/agents/structured-answer.ts:200–212, appended citations are checked using the same discovery rules as persistence. When an unfinished literal hides them, a separate Sources paragraph restores discovery. Independently verified unfinished/nested/multiline calls, unfinished strings, quoted full-ID markers, code, container tables and multiple blocks. Declared citations survive discovery, persistence, display and deletion across context_answer, topic_research and inspect_video. Regression coverage includes platform/test/agent-citation-annotations.test.ts:183 and agent-runtime-do.integration.test.ts:924.

Actual exact-head checks: 42 independent end-to-end cases passed; 89 Agent Workerd integration tests passed; TypeScript and diff whitespace checks passed. Default Node suite: 1,912 passed, 1 failed, 56 skipped. The sole en/es expectation failure at youtube-client.test.ts:677 is the previously reproduced baseline discrepancy with reused dependencies. Exact Markdown parser versions were installed; this was not a full clean dependency installation.

Fresh Verify workflow passed: https://github.com/devhims/video2ctx/actions/runs/38994978874 . Code review is satisfactory, but merge verdict: changes needed / external check unresolved because the separate Vercel status still requires team authorization, and its required-check applicability is unconfirmed. Resolve or explicitly establish that this preview check is not required before unconditional merge approval.

No live model/platform retest was performed. This validates the bounded rendering fix, not semantic evidence support or backfill of existing saved answers. No implementation, push, merge or deployment performed.

[devhims]

Changes needed on exact head 67fa0f0.

P2 — failing regression test: platform/src/agents/finalizer.ts:59 now says “must cite persisted evidence,” but platform/test/agent-duration-answer.test.ts:95 and the six following rejection assertions still match /citation/. Independent execution fails at the first assertion. The runtime rejection remains correct; update the assertions to check stable error code AGENT_CITATION_REQUIRED while preserving all seven rejection cases, then rerun checks.

No additional blocking runtime defect found in the metadata redesign. Independent checks verified authoritative block arrays for prose/tables, exclusion of model-supplied placement metadata and public metadata, exact-marker offset validation, UTF-16 offsets, notices, partial/repeated deletion, unavailable evidence, empty versus absent metadata, legacy compatibility, and the previous unfinished-call case. Table sources are now intentionally block-level, matching the submitted description.

Actual exact-head validation: 69 independent metadata/compatibility cases and 89 Agent Workerd integration tests passed. TypeScript, generated documentation and diff whitespace checks passed. Full default Node suite: 1,921 passed, 2 failed, 56 skipped. One failure is the new duration assertion above; the other is the previously reproduced en/es baseline discrepancy at youtube-client.test.ts:677 with reused dependencies. No clean full dependency install was performed.

Remote Platform checks failed and Platform integration passed in https://github.com/devhims/video2ctx/actions/runs/38996291063 . The exact CI failure cause is not verified because job-log retrieval returned Forbidden; do not assume it matches the local failure. Other jobs were still pending. Vercel separately remains authorization-blocked.

No live QA, implementation, push, merge or deployment performed. Prior-head review does not establish approval of this redesign.

[devhims]

Review of exact head fae7d86: previous validation finding resolved; no new code findings.

The delta only changes seven rejection assertions at platform/test/agent-duration-answer.test.ts:95 onward to check the stable AGENT_CITATION_REQUIRED code. Production code is unchanged from the independently reviewed metadata redesign. All seven rejection cases remain meaningful: absent trusted context/failures, different video, added claims, elevated confidence, available content evidence, and invented citation marker. Independently confirmed each rejects with that code and HTTP 422; both valid trusted fallbacks still succeed.

Exact-head execution: 135 duration/metadata/unified-finalizer tests passed; 9 independent rejection/acceptance checks passed; TypeScript and diff whitespace checks passed. Full pipeline was not rerun locally for this test-only delta; the larger totals in the description are author-reported. Prior production-code review passed 69 independent metadata cases and 89 Workerd integrations.

Fresh Verify workflow passed: https://github.com/devhims/video2ctx/actions/runs/38996944572 . Code review is satisfactory. Merge verdict: changes needed / external check unresolved until the separate Vercel deployment-authorization failure is resolved or its non-required applicability is confirmed. No remaining code change is requested by this review.

No live QA was performed; semantic evidence support and historical-answer backfill are outside this verification. No implementation, push, merge or deployment performed.

[devhims]

Review of exact head 8a2281b: no new blocking code regressions. The entire repository tree equals previously reviewed ad456eb (tree f36d158765128acdab6ad3604f29dcf3ca711f97). Restored inline placement permits independently cited claims within natural paragraphs; this review does not require returning to block-only prose.

Independent exact-head execution: 343 focused tests, 87 Agent Workerd integrations and 14 restored-behavior checks passed; TypeScript and diff whitespace passed. Previous unfinished-call and duration-assertion failures do not reproduce. Fresh Verify passed: https://github.com/devhims/video2ctx/actions/runs/38997903145 . The full pipeline totals in the description remain author-reported; not rerun locally.

Inherited correctness follow-up, reproduced identically on this head and PR base f858c53 in eight render→finalize→display cases: structured-answer.ts:254–260 applies legacy square-bracket normalization after protected alias handling. A literal quoted "[ref_4]" can become a citation; ref_4 gains a citation-looking label but keeps the external destination. Supplied evidence e4 is persisted even when only e1 was declared. No ID is fabricated, but citation intent changes. This is pre-existing, not a restoration regression; track a narrow protection-consistency fix separately. The description's literal/link protection claim should be read as covering the new bare/parenthesized/range pass, not every legacy square-bracket form.

Previously documented nonblocking P3 limitations remain: malformed chained ranges partially normalize a valid prefix (structured-answer.ts:118–131), and streamed drafts may show aliases (line100). Unknown/malformed expressions can remain visible. Numeric adjacency is not semantic evidence support.

Merge verdict: changes needed / external check unresolved. Code review is satisfactory for this bounded restoration, but Vercel still reports deployment authorization required and required-check applicability is unconfirmed. No live QA, implementation, push, merge or deployment performed.

[devhims]

Changes needed on exact head 2449ad1.

The inherited square-bracket literal bug is resolved. Independent render→finalize→display checks preserve quoted aliases, Markdown link labels/titles, images, URLs and literals spanning code without adopting unintended evidence. Genuine inline prose/table citations remain supported.

P2 — guidance still contradicts the stated natural inline-prose goal. platform/src/agents/structured-answer.ts:17 tells the model to put prose citations in evidenceIds, not text. platform/src/agents/research/answer-guidance.ts:34 directs separate claims into separate blocks, and platform/src/agents/research/research-agent.ts:963 explicitly says “Outside tables, omit inline citation markers.” This commit changes normalization, not those instruction surfaces. The renderer's capability alone therefore does not encourage the desired near-claim inline output. Align all three surfaces if inline prose is the chosen product behavior, retain supplied evidenceIds, and add prompt/schema regression coverage. The product-guidance decision was raised with the owner; no implementation is being directed without approval. This is a pre-existing design mismatch, not a newly introduced runtime regression or a live-model reproduction.

Actual exact-head validation: 354 focused tests, 8 independent literal pipelines and 87 Agent Workerd integrations passed; TypeScript and diff whitespace passed. Full local pipeline was not rerun; description totals remain author-reported. No additional runtime defect found. Previously documented malformed-range/streaming limitations remain.

Remote Platform checks/integration passed, with Dashboard E2E still pending at inspection. Vercel separately requires authorization. No live QA, implementation, push, merge or deployment performed.

[devhims]

Review of 53c53b2 (now superseded by 41dcf13; latest delta under review): guidance mismatch resolved, no new code findings.

Shared citation guidance in structured-answer.ts:14 now permits independently cited claims in one natural paragraph and reaches schema descriptions, shared answer guidance, actual finalizer prompt and legacy finalize tool. Supplied-ID constraints remain; evidenceIds still excludes ranges/duplicates. Rendering/persistence/deletion logic is unchanged and the literal fix remains effective.

Independent exact-head validation passed: 401 focused tests, 8 literal pipelines, 5 guidance-surface checks, one two-source natural-paragraph pipeline, TypeScript and whitespace checks. The paragraph retained citations beside both claims. These are deterministic checks, not live-model compliance evidence. Full platform/Workerd suites were not rerun for this guidance-only delta.

Merge verdict for this reviewed head: changes needed / external checks unresolved at review time (Verify still running; separate Vercel authorization failure). No remaining code finding. This does not approve the newer head; its readability-only delta is being checked. No implementation, push, merge, deployment or live QA performed.

[devhims]

Review of exact head 41dcf13: no remaining code findings. The prior guidance mismatch is resolved.

The readability-only delta at platform/src/agents/research/answer-guidance.ts:34 makes bullets, steps and comparison tables conditional on usefulness, permits short prose, respects requested formats and keeps citations beside claims. Shared inline guidance introduced in 53c53b2 reaches schema, answer guidance, finalizer prompt and legacy tool while preserving supplied-ID constraints and evidenceIds. No runtime citation logic changed in these two guidance commits.

Actual exact-head validation: 118 prompt/finalizer tests and 14 independent checks passed (8 literal pipelines, 5 guidance surfaces, 1 two-source natural paragraph), plus diff whitespace. On the immediately preceding guidance head, 401 focused tests and TypeScript passed. Full suites and TypeScript were not rerun locally for this final text-only delta; fresh GitHub Verify is now successful: https://github.com/devhims/video2ctx/actions/runs/38999806196 .

Code assessment: satisfactory. Merge verdict: changes needed / external check unresolved solely because Vercel still reports deployment authorization required, with required-check applicability unconfirmed. No further code change is requested. Once that check is resolved or confirmed non-required, this exact head has no outstanding code-review objection.

Checks validate instructions and deterministic rendering, not live-model compliance or semantic evidence support. Known malformed/unknown-label limitations remain documented; saved answers are not backfilled. No live QA, implementation, push, merge or deployment performed.