docs(knowledge): document video-digest vision JSON, untrusted framing, prerequisites

[kyle-sexton]

Closes #6818
Closes #6820
Closes #6828

Summary

Three documentation gaps in the knowledge plugin's video-digest skill, fixed together:

• docs(knowledge): video-digest's agent-authored triage and promotion JSON shapes exist only in validator code #6818: the JSON shapes subagents write in Phase 4 existed only in validator code.
• fix(knowledge): frame video-digest's ingested transcripts, comments and pages as untrusted data #6820: ingested transcripts, descriptions, comments, decks, companion pages and cloned repositories carried no untrusted-content framing.
• fix(knowledge): declare Git Bash on Windows and a Node 20.11 floor for video-digest #6828: Git Bash on Windows and the Node 20.11 floor were undeclared.

Fix

• New templates/vision-json-shapes.md: fields, allowed values and a worked example for sheet_NNN.json, promotion-decisions.json and key-frame-quality-audit.json, derived from lib/watch-vision-validation.js, lib/synthesis-filename.js, merge-triage-json.js and render-quality-audit.js. watch-pipeline.md Phase 4 points to it and says each brief carries its file's section, plus the sheet's sheet-frame-index.json entry for triage, with a pointer record for the subagent-context docs.
• The untrusted-content spine from docs/conventions/untrusted-content/README.md, byte-identical, in SKILL.md "Source discipline", the watch-pipeline.md execution model (every research, vision, link/repo and companion brief carries it; findings land in recommendations/questions.md; writes stay in the slice and temp directories) and the companion-primary-sources.md fan-out step.
• SKILL.md Prerequisites names Git Bash on Windows and Node 20.11+ (21.2+ on the 21 line), with pointer records. prerequisites.json gets a node version floor of 20.11, following the miro plugin's node entry.
• Kept SKILL.md small because of the pending concision rewrite (Concise skills rollout: knowledge (6 skills, 5 model-invoked) #6565): +13 lines. The new content is in the spokes and the template.

Decisions:

• No bash entry in prerequisites.json. docs/conventions/prerequisites/README.md says git, bash, sh and the POSIX utilities "are assumed and never declared", and the schema has no per-OS field. Git Bash is named in SKILL.md prose only. This declines the second half of the issue's fix fix: correct plugin-system inaccuracies and harden references #2.
• Why 20.11: run.mjs, setup-deps.mjs and watch/detect-recoverable-bootstrap.js read import.meta.dirname, added in v20.11.0 and v21.2.0 (Node esm.md). The scan for newer APIs across the plugin's .js, .mjs, .cjs and .ts files, vendor included, found nothing higher. module.register and --import in register-hook.mjs need less. The repo root's engines: >=24 covers dev tooling, not consumers. Node 21.0 and 21.1 pass a dotted min of 20.11 but lack the API, which is a gap in the checker's floor model.
• The node entry is shared with course-digest and setup. /knowledge:setup runs video-digest's setup-deps.mjs, so it really needs the floor. course-digest uses no import.meta.dirname, so the floor over-gates it slightly. The degrade text says which scripts need it.

Verification

• Ran the three worked examples through the real validators on a scratch slice: validateTriageSheet, validatePromotionDecisions, validateQualityAudit and validateTriageAgentic all returned []. merge-triage-json.js, validate-triage-json.js (with a matching sheet-frame-index.json) and validate-promotion-decisions.js reported valid. render-quality-audit.js and render-triage-log.js rendered.
• node lib/prerequisites.mjs check plugins/knowledge --for skill:video-digest: node 24.21.0 PASS against the new floor.
• markdownlint-cli2 on the five changed markdown files: 0 issues.
• check-skill.sh video-digest: PASS, 0 errors, 6 warnings. One warning is the expected body growth (284 to 297 lines). The rest come from existing content.
• check-changelog-fragments.sh --check and --check-required origin/main pass.
• Conformance greps for the framing spine match file for file (3 and 3).
• No extraction code changed, and no test reads the new template, so the extraction suite was not run.

Related

• Concise skills rollout: knowledge (6 skills, 5 model-invoked) #6565: the pending concision rewrite of this skill. The spine lines in SKILL.md must survive it.
• course-digest and map-corpus lack the framing spine too (noted in fix(knowledge): frame video-digest's ingested transcripts, comments and pages as untrusted data #6820, out of scope here).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-11T01:36:21.552839Z	7163811	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 6m 26s —— View job

---

Code review complete

• Gather context (diff, CLAUDE.md/AGENTS.md/REVIEW.md, changed files)
• Review changed files for correctness and maintainability
• Verify candidate findings adversarially (via review:lane-verifier)
• Post inline comments / summary

Summary

Reviewed all 6 changed files against the real validator/renderer source in
plugins/knowledge/skills/video-digest/extraction/ (lib/watch-vision-validation.js,
lib/synthesis-filename.js, merge-triage-json.js, validate-triage-json.js,
validate-promotion-decisions.js, vision-gated-promote.js, render-quality-audit.js,
render-triage-log.js, check-watch-outcomes.js) and the node prerequisite's version-gate
logic. Field-by-field, the new templates/vision-json-shapes.md shapes (sheet IDs, cell IDs,
verdict enum, destName kebab-case + forbidden-prefix rules, gapNote/session constraints,
quality-audit note-length rule) all match the actual validator code, including both worked
examples. The untrusted-content framing spine added to SKILL.md, watch-pipeline.md, and
companion-primary-sources.md is byte-identical to the canonical spine in
docs/conventions/untrusted-content/README.md, confirmed by grep (3 files carry it, matching the
PR's claim). The node floor bump in prerequisites.json is internally consistent with the
SKILL.md Prerequisites text.

One finding posted inline (verified via an independent review:lane-verifier pass before
posting): the "Per-sheet triage" section's intro names only merge-triage-json.js and
validate-triage-json.js as the file's validators, but the model row's required/forbidden-value
rule is actually enforced only by check-watch-outcomes.js (via validateTriageAgentic()), which
that section never names — so a sheet with a missing or forbidden model would pass both cited
scripts and only fail much later, at outcome verification.

Not independently re-run: the PR's own markdownlint-cli2, check-skill.sh, and
check-changelog-fragments.sh results — those are author-claimed and unverified by me (no
tooling available in this environment to reproduce them).

[claude]

Claude finished @kyle-sexton's task in 1m 30s —— View job

---

Security review: no issues found

• Gather context (diff, changed files)
• Determine request type (CI security-review lane)
• Review changed files for security-relevant surface
• Check for instruction-surface deletions against protected classes
• Adversarial validation of any candidates
• Post final findings

Scope reviewed (gh pr diff 6849, head 7163811): 6 files — a new changelog fragment, a prerequisites.json version-floor addition, and four markdown edits to the knowledge plugin's video-digest skill (SKILL.md, watch-pipeline.md, companion-primary-sources.md, and the new templates/vision-json-shapes.md).

Findings: none.

• The diff is documentation plus one JSON config addition; no executable code paths, scripts, or validators changed. The prerequisites.json version-check block (args/pattern/min) follows the existing schema already used by the miro plugin's node entry — the checker code that consumes it (lib/prerequisites.mjs) is untouched by this PR, so no new attack surface there.
• This PR adds untrusted-content framing rather than removing or narrowing it, so the instruction-surface-deletion lens doesn't apply. The new spine text in SKILL.md, watch-pipeline.md, and companion-primary-sources.md was checked against docs/conventions/untrusted-content/README.md's three-part framing contract (classification, finding, authority floor) and matches the required byte-identical spine, with each site's "site tail" correctly naming where the fixed write authority stays (slice/temp directories only, never the --target repo) — consistent with the PR's own "conformance greps match file for file" verification note.
• templates/vision-json-shapes.md only documents JSON shapes already enforced by existing validators (merge-triage-json.js, render-quality-audit.js, etc.); it adds no new parsing or execution logic.

No GitHub Actions workflow files, auth/access-control code, or injection-relevant surfaces (command/SQL/path/template) are touched by this PR.

[github-actions]

claude-security-review has reviewed this pull request through 21ca3b6; a later push is reviewed from there.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 71638111de

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

claude-review has reviewed this pull request through 21ca3b6; a later push is reviewed from there.

[claude]

Claude finished @kyle-sexton's task in 1m 8s —— View job

---

Security review: no issues found

• Gather context (diff, changed files)
• Determine request type (CI security-review lane, via /review:security-review)
• Review changed files for security-relevant surface
• Check instruction-surface deletions against protected classes
• Adversarial validation of any candidates
• Post final findings

Scope reviewed (git diff origin/main...HEAD at head
21ca3b6): the same 6 files listed on the PR — a new changelog fragment, a node version-floor addition to plugins/knowledge/prerequisites.json, and four markdown edits to the knowledge plugin's video-digest skill (SKILL.md, watch-pipeline.md, companion-primary-sources.md, and the new templates/vision-json-shapes.md).

Findings: none.

• The diff is documentation plus one JSON config addition; no executable code paths, scripts, or validators changed. The prerequisites.json version-check block
  (args/pattern/min)
  follows the schema lib/prerequisites.mjs already implements and that the miro plugin's node entry already uses; args (["--version"]) and pattern come from this repo's own trusted config, not from any untrusted input, and lib/prerequisites.mjs itself is untouched by this PR, so no new attack surface there.
• Instruction-surface lens applied: every prose change in this diff is an addition that strengthens the untrusted-content framing (SKILL.md
  L62-L67,
  watch-pipeline.md
  L91-L102,
  companion-primary-sources.md
  L25-L28).
  No existing rule, guardrail, allowlist, or confinement statement is removed, narrowed, or softened anywhere in the diff, so the deletion lens (checked against docs/conventions/instruction-exception-register/README.md, present in this checkout) finds nothing to flag — the new text explicitly reinforces that writes stay confined to the slice/temp directories and never the --target repo.
• templates/vision-json-shapes.md only documents JSON shapes already enforced by existing validators (merge-triage-json.js, render-quality-audit.js, check-watch-outcomes.js, etc.); it adds no new parsing, execution, or file-write logic of its own.

No GitHub Actions workflow files, auth/access-control code, or injection-relevant surfaces (command/SQL/path/template) are touched by this PR. This confirms the prior security-review lane result on commit 7163811 still holds for the current head 21ca3b6.

[claude]

Claude finished @kyle-sexton's task in 3m 1s —— View job

---

Code review complete

• Gather context (diff, CLAUDE.md/AGENTS.md/REVIEW.md, changed files)
• Check skip gate (draft/closed/trivial/already-reviewed head)
• Review changed files for correctness and maintainability
• Verify candidate findings adversarially (via review:lane-verifier)
• Post inline comments / summary

Summary

Reviewed the 6 files changed between origin/main and HEAD 21ca3b6, cross-checking every claim
in the new templates/vision-json-shapes.md against the real validator/renderer source in
plugins/knowledge/skills/video-digest/extraction/:

• lib/watch-vision-validation.js (validateTriageSheet, validateTriageManifest,
  validateTriageAgentic, validatePromotionDecisionRow, validateQualityAudit)
• lib/synthesis-filename.js (FORBIDDEN_SYNTHESIS_NAME_PREFIXES/_PATTERNS,
  FORBIDDEN_PIPELINE_SESSION_SLUG_PATTERNS, isStubQualityAuditNote)
• watch/merge-triage-json.js, watch/validate-triage-json.js,
  watch/validate-promotion-decisions.js, watch/vision-gated-promote.js,
  watch/render-quality-audit.js, and evals/check-watch-outcomes.js
  (pushTriageManifestChecks, pushQualityAuditChecks's manifest-audit-parity row-count check)

Field by field, the three JSON shapes (sheet/cell IDs, the model required/forbidden-value rule,
the destName kebab-case + forbidden-prefix/pattern list, gapNote/session constraints, the
quality-audit 20-char substantive-note floor, and the row-count parity rule) all match the actual
code, including both worked examples.

Both findings posted against the prior head (7163811) by Codex and by this lane are already
fixed on the current head:

• Codex's P1 (template unreachable without a direct SKILL.md routing entry) — SKILL.md's
  routing table now carries
  templates/vision-json-shapes.md.
• This lane's finding (the model row's validator misattributed to merge-triage-json.js /
  validate-triage-json.js only) — the "Per-sheet triage" intro now names
  check-watch-outcomes.js for that rule.

The untrusted-content framing spine added to SKILL.md, watch-pipeline.md, and
companion-primary-sources.md is byte-identical to the canonical spine in
docs/conventions/untrusted-content/README.md's "The framing contract" section, confirmed by
direct comparison of all three insertion sites. The node version-floor addition in
prerequisites.json is internally consistent with SKILL.md's Prerequisites text, and that
section correctly follows the pointer/as-of-date/recheck-trigger convention for the two volatile
upstream specifics it cites (injected-command shell behavior, import.meta.dirname).

No new findings to report.

Not independently re-run: the PR's own markdownlint-cli2, check-skill.sh, and
check-changelog-fragments.sh results, and the real-validator scratch-slice run described in
Verification — those are author-claimed and unverified by me in this pass (I did, however,
independently trace every validator/renderer code path the template documents, as detailed
above).