Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
75 commits
Select commit Hold shift + click to select a range
cb9f4ba
fix(knowledge): drop rolling-caption repeats at video-digest paragrap…
kyle-sexton Oct 11, 2026
3509038
feat(knowledge): re-lay out a closed video-digest slice into the corp…
kyle-sexton Oct 11, 2026
271fb46
feat(knowledge): re-lay out a video-digest slice before close and ret…
kyle-sexton Oct 11, 2026
d5a7de5
fix(knowledge): tighten caption boundary repeats; stage relayout outp…
kyle-sexton Oct 11, 2026
6ffc708
Merge remote-tracking branch 'origin/main' into fix/video-digest-rela…
kyle-sexton Oct 11, 2026
da7392a
docs(knowledge): describe the tightened boundary rule and staged rela…
kyle-sexton Oct 11, 2026
7cfed3c
fix(knowledge): guard relayout against slice overlap, interrupted swa…
kyle-sexton Oct 11, 2026
f3413fc
fix(knowledge): refuse ambiguous or info-less temp sessions in video-…
kyle-sexton Oct 11, 2026
aee123c
fix(knowledge): close the remaining overlap and partial-copy cases in…
kyle-sexton Oct 11, 2026
e5f1b7a
fix(knowledge): cover decks, bare frame names, >> tokens and install …
kyle-sexton Oct 11, 2026
78c4c45
fix(knowledge): check video-digest frames against frame-times.json bo…
kyle-sexton Oct 11, 2026
fc19627
Merge remote-tracking branch 'origin/main' into fix/video-digest-rela…
kyle-sexton Oct 11, 2026
42945b9
fix(knowledge): bind caption carry-over to the exact opener; require …
kyle-sexton Oct 11, 2026
0d7bf7e
fix(knowledge): stop a caption provenance note from exempting video-d…
kyle-sexton Oct 11, 2026
b0581ed
fix(knowledge): check relayout targets against recorded temp dirs in …
kyle-sexton Oct 11, 2026
1e84ce7
fix(knowledge): tighten relayout lane checks, frame-times shape and n…
kyle-sexton Oct 11, 2026
6f642bb
fix(knowledge): close the input-shape and reference-form gaps an adve…
kyle-sexton Oct 11, 2026
c24691f
fix(knowledge): handle any HTML attribute quoting and shape-check inf…
kyle-sexton Oct 11, 2026
c65c7c7
fix(knowledge): scan link destinations with parentheses; make the rel…
kyle-sexton Oct 11, 2026
4152273
fix(knowledge): finish interrupted relayout installs; decode path seg…
kyle-sexton Oct 11, 2026
7000a6c
refactor(knowledge): drop relayout claim and completion markers for a…
kyle-sexton Oct 11, 2026
fc223a9
fix(knowledge): match apostrophe variants in caption dedupe; skip esc…
kyle-sexton Oct 11, 2026
4daa3b6
fix(knowledge): read titles after a line ending; keep nested rewrites…
kyle-sexton Oct 11, 2026
36d4653
fix(knowledge): detect slice-root references by location, not a match…
kyle-sexton Oct 11, 2026
8afdedd
fix(knowledge): rewrite references to the slice dir itself; validate …
kyle-sexton Oct 11, 2026
1396517
fix(knowledge): case-insensitive Markdown files; absent-folder prefix…
kyle-sexton Oct 11, 2026
06a21e5
fix(knowledge): recognize root aliases and every backticked path form…
kyle-sexton Oct 11, 2026
fd67999
fix(knowledge): check the temp video's id; skip code blocks; validate…
kyle-sexton Oct 11, 2026
3a788a6
docs(knowledge): rewrap the relayout refusal list in output-contract.md
kyle-sexton Oct 11, 2026
b2adecd
docs(knowledge): finish rewrapping the relayout refusal list
kyle-sexton Oct 11, 2026
2e12428
docs(knowledge): wrap the last long line in the relayout refusal list
kyle-sexton Oct 11, 2026
f77c633
fix(knowledge): read multi-line code spans, escaped labels and comman…
kyle-sexton Oct 11, 2026
c273122
fix(knowledge): honor escaped image markers; leave container fences v…
kyle-sexton Oct 11, 2026
cc92c63
fix(knowledge): guard temp-dir reads; match raw #/? names; cite relay…
kyle-sexton Oct 11, 2026
b453855
fix(knowledge): keep relayout evidence out of the skill; read multi-l…
kyle-sexton Oct 11, 2026
11e8571
fix(knowledge): decode HTML references in src/href; require regular t…
kyle-sexton Oct 11, 2026
ef2a06f
fix(knowledge): escape rewritten HTML src/href values for their quoting
kyle-sexton Oct 11, 2026
5f5fcfa
fix(knowledge): decode backslash escapes in destinations; refuse unre…
kyle-sexton Oct 11, 2026
4f10998
fix(knowledge): allow escaped brackets in reference-definition labels
kyle-sexton Oct 11, 2026
11fce25
fix(knowledge): follow CommonMark link-label rules in relayout
kyle-sexton Oct 11, 2026
06984ee
fix(knowledge): require carry-over evidence for every caption repeat;…
kyle-sexton Oct 11, 2026
3f95aef
fix(knowledge): resolve before treating a path as a placeholder; exac…
kyle-sexton Oct 11, 2026
bf3a72e
fix(knowledge): share one destination parser and check spaced code pa…
kyle-sexton Oct 11, 2026
a1455e1
fix(knowledge): skip an HTML attribute match with no captured span in…
kyle-sexton Oct 11, 2026
1649d5c
fix(knowledge): treat HTML tag text as data and require whole-line re…
kyle-sexton Oct 11, 2026
777297c
fix(knowledge): check recorded temp dirs in no-media mode and accept …
kyle-sexton Oct 11, 2026
381441d
fix(knowledge): write the upstream title as plain Markdown text in th…
kyle-sexton Oct 11, 2026
61a65c8
fix(knowledge): keep the skill contract additive and decode reference…
kyle-sexton Oct 11, 2026
25274ca
fix(knowledge): resolve whole names before line suffixes, refuse syml…
kyle-sexton Oct 11, 2026
876e3db
fix(knowledge): validate every relative definition and treat backslas…
kyle-sexton Oct 11, 2026
4259d2b
fix(knowledge): whole-name-first for every reference kind, literal ti…
kyle-sexton Oct 11, 2026
0f697fd
fix(knowledge): reject titles across blank lines and apply HTML numer…
kyle-sexton Oct 11, 2026
606d7b0
fix(knowledge): never exempt a retired real file from the link check …
kyle-sexton Oct 11, 2026
c9b68dd
fix(knowledge): end bare link destinations only at the ASCII space or…
kyle-sexton Oct 11, 2026
ef264ed
fix(knowledge): encode rewritten link destinations so they parse back…
kyle-sexton Oct 11, 2026
dc55515
fix(knowledge): retired refs override allowed misses; treat ..name as…
kyle-sexton Oct 11, 2026
8601513
fix(knowledge): keep angle link destinations out of HTML masking
kyle-sexton Oct 11, 2026
1f280fd
fix(knowledge): decode semicolonless numeric references in HTML attri…
kyle-sexton Oct 11, 2026
7bdf4b3
fix(knowledge): keep word-distinguishing punctuation in caption dedup…
kyle-sexton Oct 11, 2026
fe69da9
fix(knowledge): an outer link whose label holds a link is literal text
kyle-sexton Oct 11, 2026
4267d49
fix(knowledge): mask autolinks, reject paren titles with bare parens,…
kyle-sexton Oct 11, 2026
0e5d4d0
fix(knowledge): CRLF blank lines, raw fragment delimiters in links; d…
kyle-sexton Oct 11, 2026
95ecca9
fix(knowledge): keep edge dashes in caption word matching; read wrapp…
kyle-sexton Oct 11, 2026
7ca97e3
fix(knowledge): decode HTML URL references before dropping tab and li…
kyle-sexton Oct 11, 2026
bc0be22
fix(knowledge): trim HTML URL edge whitespace; document link text in …
kyle-sexton Oct 11, 2026
e0bd11d
fix(knowledge): match CommonMark start tags only; treat curly quotes …
kyle-sexton Oct 11, 2026
359e1a6
fix(knowledge): mask every raw inline HTML form; ignore escaped link …
kyle-sexton Oct 11, 2026
06ce2ae
fix(knowledge): hide CDATA, declarations and processing instructions …
kyle-sexton Oct 11, 2026
4e5901c
fix(knowledge): refuse a non-directory --replace target and bare-CR M…
kyle-sexton Oct 11, 2026
857edfb
fix(knowledge): follow CommonMark raw-HTML whitespace, short comments…
kyle-sexton Oct 11, 2026
b5136cb
fix(knowledge): honor escaped HTML openers; keep HTML attribute refer…
kyle-sexton Oct 11, 2026
204799e
fix(knowledge): one line ending per tag separator, escaped tags skip …
kyle-sexton Oct 11, 2026
4d1d723
docs(knowledge): record the code-span-before-HTML limit of the relayo…
kyle-sexton Oct 11, 2026
82ad3c0
fix(knowledge): stop code spans at paragraph-interrupting block starts
kyle-sexton Oct 11, 2026
46e31de
fix(knowledge): stop code spans at setext heading underlines
kyle-sexton Oct 11, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
bump: minor
---

### Added

- video-digest: `watch/relayout-slice.js` copies a slice into the knowledge-corpus layout (`transcript/`, `metadata/`, `frames/all/`, `frames/key/`, `media/`, `analysis/`, provenance `README.md`), rewrites the slice paths its markdown names through a path map (a pipeline file the layout does not keep becomes plain text saying so), and exits 1 listing every slice-internal path that still does not resolve. It runs on a closed slice, or before `close` on one whose outcome checks pass so the temp media is still there, and refuses a slice whose temp media is gone unless `--no-media`, which takes nothing from the temp session. It builds the layout in a staging directory and moves it into place only when the link check passes; an existing target needs `--replace` ([#6902](https://github.com/melodic-software/claude-code-plugins/issues/6902)). Hand re-layouts had broken relative paths twice: melodic-software/knowledge-corpus#42 needed four review rounds and six threads to clear them, and knowledge-corpus#46 fixed 41 broken paths in the slice knowledge-corpus#37 had landed.

### Fixed

- video-digest: an auto-caption transcript paragraph no longer repeats the previous paragraph's closing words that a rolling caption carried over: 2 to 12 words compared case- and punctuation-insensitively, dropped only when the opening cue carries them from the cue before it (the cues overlap in time, or the cue starts with the previous cue's words verbatim), so a phrase the speaker genuinely repeats stays ([#6992](https://github.com/melodic-software/claude-code-plugins/issues/6992)).
109 changes: 109 additions & 0 deletions plugins/knowledge/skills/video-digest/context/output-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,115 @@ once per process, and the new name wins when both are set.
material at a differently-shaped path (for example `sources/<type>/<slug>/`) does not get that
shape from this skill: land under `library_dir` as-written and re-lay-out by hand, or fork
the sub-path in your own automation. This skill's contract is root relocation only.
For the knowledge-corpus layout there is also `relayout-slice.js`, described next.

### Re-laying out a slice with `relayout-slice.js`

Run it on a slice landed under `library_dir`:

```bash
node "<skill-dir>/extraction/run.mjs" --data-dir "<plugin-data>" watch/relayout-slice.js "<slice-dir>" "<target-dir>" [--no-media] [--replace]
```

Re-laying out a slice by hand has repeatedly left broken relative paths in the corpus; the
script's rewrite and link check are what catch them.

The media, every extracted frame, the served caption tracks and the info JSON come from the temp
session `watch.json` records, which `close` removes. To keep them, run in this order:

1. `evals/check-watch-outcomes.js "<slice-dir>"` passes.
2. `watch/relayout-slice.js "<slice-dir>" "<target-dir>"`, with media.
3. `watch/watch-state.js close "<slice-dir>"`.
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved

The script runs on a closed slice, or on an unclosed one whose outcome checks pass (it runs them
itself and refuses when they fail). It refuses any slice whose temp media is gone unless
`--no-media` is passed, which takes nothing from the temp session (no media, frames, caption
tracks or info JSON) even when it still exists; after a normal close that is the only way it runs.
It refuses a `watch.json` that is not an object, whose `videoId` is not a plain id (it names
`media/<id>.<ext>`), that lacks a `title` or `sourceUrl`, or whose temp session dirs are not
strings. Without `--no-media` it also refuses a partly removed temp session, naming the missing
piece: the video, an empty video, caption track or frame image, any of those (or the
sidecar) that is not a regular file, the info JSON or
`frame-times.json` (or either one not holding a JSON object, or a `frame-times.json` record
without a finite number or null `timestampSec`), any frame image, a frame
`frame-times.json` lists, a `frame-times.json` entry for a scene or interval frame on disk
(anchor frames carry their time in their name), or the caption tracks. It refuses a temp session
holding several videos (an X post with more than one), naming them, since the watch does not
record which one is primary; a video whose id is not this slice's (for an X post, whose
info JSON does not name this post as its `display_id`); and a symlink in the slice or the temp
session, since a copy would follow it. In every mode, `--no-media` included, it refuses a recorded
work, frames or contact-sheets dir outside the OS temp dir or overlapping the slice, existing or
not, since `close` deletes those. It refuses when the slice is, holds, or sits
inside a path the run writes: the target, `<target>.relayout-backup`, or a
`.<target-name>.relayout-*` staging dir beside the target. In
every mode, `--no-media` included, it refuses when one of those paths is, holds, or sits inside a
temp dir `watch.json` records, existing or not, since `close` deletes those. It refuses an
existing target unless `--replace` is passed, which replaces the target and keeps its
`README.md`. The replaced target is moved to `<target>.relayout-backup` and deleted only once the
new layout is in place. If a run is interrupted mid-swap, the next run restores the target from
that backup when the target is missing (and says so), and refuses, naming the backup, when both
exist; remove whichever one you do not want to keep.

It writes the knowledge-corpus layout: `transcript/`, `metadata/` (with a trimmed `info.json`,
the companion sources brief, and the fetched `decks/` and `attachments/`), `frames/all/`,
`frames/key/` beside the frame and vision logs in `frames/`, `media/<id>.<ext>`, `analysis/`
(`RESEARCH.md`, `research/`, `recommendations/`, the companion digest), and a provenance
`README.md` when the target has none; the trimmed `info.json` also drops the local download
paths yt-dlp records. The script's header comment is the authoritative mapping. Each slice path
the copied markdown names is rewritten through a path map relative to the file's new location:
inline links (balanced or escaped parentheses in the destination, quoted or parenthesized titles),
reference-style definitions whose line holds nothing after the destination but an optional
title, HTML `src`/`href` attributes in any quoting or case (character references decoded),
and backticked paths, with each
segment percent-decoded (and re-encoded on rewrite) and `\` separators read as `/`.
A relative link that leaves the slice keeps pointing at the same file. Fenced code blocks are
left untouched, and link syntax inside an inline code span is not read as a link. Text inside an
HTML tag or comment is data: only a tag's own `src`/`href` attributes are read.
One naming a pipeline file the layout does not keep (such as `run-state/watch.json`, the slice's
own journey `README.md`, or an extracted frame's bare name under `--no-media`) becomes plain text
saying it is not retained; one naming a directory whose files went to several places (`source/`)
names where they went; one naming a lane folder the slice never produced (`source/decks/`) says
so. It builds the layout in a sibling staging directory and link-checks it there; it exits 1
listing every slice-internal path that still does not resolve, including a bare extracted-frame
name and a path under an original lane whose parent directory the slice had (`source/missing.txt`).
Not checked: paths under `plugins/`, `docs/`, `templates/` and `.claude/`, `AGENTS.md`, paths
that leave the target, and backticked paths that are neither under such a lane directory nor
under a top-level directory of the target or an entry beside the naming file (paths into another
repository, such as `research/deepening/...` from an upstream repo). Fix what the check lists in
the slice and re-run. Only a passing check moves the staging directory into place; on any failure
the staging directory is removed and the target is left as it was. Without `--replace` the
install is a single rename of the staging dir onto the
target path, which fails, and the run refuses, when a target with content appeared during the
run. On POSIX that rename replaces an empty directory someone created meanwhile; that is
accepted, since an empty directory holds no data. A run killed mid-copy or mid-install leaves its
`.<target-name>.relayout-*` staging dir behind; the next run names any such dir in a warning for
deletion by hand and never installs or deletes one, since it may belong to another slice's run
or to a run still going. The warning does not stop the run; delete a named dir once no run is
using it.

### Known limits of the re-layout

The reference scanner is not a full CommonMark parser. It does not model indented code blocks,
fenced code blocks that are indented or inside block quotes or list items, HTML blocks, link
labels nested more than one level, or link reference definitions inside containers (lists, block
quotes). References in those constructs may be left unrewritten or read as ordinary text, and the
link check is the backstop: it refuses a dangling slice-internal path it can see.

It also does not decode named character references beyond `&amp; &lt; &gt; &quot; &apos;`
(numeric references are decoded). A destination holding another one (`a&commat;b.pdf` for the file
`a@b.pdf`) is not mapped to its file, and the link check refuses it, naming the path, so nothing
passes silently.
When a retained file's name literally contains such a reference and the layout leaves its path
unchanged, the link is left as written and is not flagged.

Link-shaped text inside a reference definition's title is read as a link: the rewrite may update
it, and if it names a missing path the link check refuses the run.

A `<` right after an unescaped `](` is read as a link destination even when the `]` has no
opening label; an HTML tag there is not masked, and a missing path inside it makes the run refuse.

Code spans are found before raw HTML, so a backtick inside a quoted HTML attribute can pair with a
later backtick and hide the text between them from the rewrite and the link check.

## Agent-written artifacts share the same root

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import {
cleanManualCaptions,
stripCaptionHtmlEntities,
} from "@melodic/video-digestion/transcript/manual-caption-clean";
import { formatTranscript } from "@melodic/video-digestion/transcript/vtt-parser";
import { formatTimestamp, formatTranscript } from "@melodic/video-digestion/transcript/vtt-parser";

import { primaryEntry } from "../adapters/adapter-contract.js";
import { LANES, lanePath } from "../lib/slice-lanes.js";
Expand All @@ -34,6 +34,127 @@ function countParagraphs(transcript) {
return transcript ? transcript.split("\n\n").length : 0;
}

const BOUNDARY_REPEAT_MIN_WORDS = 2;
const BOUNDARY_REPEAT_MAX_WORDS = 12;
const PARAGRAPH_STAMP = /^(\[[^\]]*\]\s*)([\s\S]*)$/;

/** @param {string} text */
function tokens(text) {
return text.split(/\s+/).filter(Boolean);
}

/** @param {string} word */
function comparableWord(word) {
// Apostrophes in any form (', ’, ʼ) drop out, so don't, don’t and dont match.
// Only sentence punctuation at either end goes, so C++. and C# stay distinct.
return word.toLowerCase().replace(/['\u2019\u02BC]/g, "").replace(EDGE_PUNCTUATION, "");
}
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved

/**
* Sentence punctuation (quotes, brackets, ellipses) at a word's ends. Hyphens
* and dashes stay, so C-- and C never compare equal.
*/
const EDGE_PUNCTUATION =
/^[.,;:!?"\u2018\u201a\u201c\u201d\u201e\u2039\u203a\u00ab\u00bb()[\]{}\u2026]+|[.,;:!?"\u2018\u201a\u201c\u201d\u201e\u2039\u203a\u00ab\u00bb()[\]{}\u2026]+$/g;

/**
* The lexical words of `text`: punctuation-only tokens such as `>>` are not
* words, so they never count toward a run's length.
*
* @param {string} text
*/
function words(text) {
return tokens(text).filter(isWord);
}

/** @param {string} token - a word holds at least one letter or digit */
function isWord(token) {
return /[\p{L}\p{N}]/u.test(token);
}

/** @param {string[]} run */
function comparableRun(run) {
return run.map(comparableWord).join(" ");
}
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved

/**
* True when the cue opening the paragraph stamped `stamp` carries `run` over
* from the cue before it: the two cues overlap in time, or the opening cue
* starts with the previous cue's closing words verbatim (a rolling caption).
* False whenever the opening cue cannot be identified exactly.
*
* @param {string} stamp - the paragraph's `[M:SS]`
* @param {string[]} run - the paragraph's leading words
* @param {readonly { startSec: number, endSec: number, text: string }[]} cues
*/
function carriesOverFromPreviousCue(stamp, run, cues) {
// The paragraph stamp floors the opening cue's start to the second, so it
// identifies the opener only when exactly one cue starts in that second.
// With several, the evidence is ambiguous and the words stay.
const openers = cues.flatMap((cue, at) =>
`[${formatTimestamp(cue.startSec)}]` === stamp ? [at] : [],
);
if (openers.length !== 1 || openers[0] === 0) return false;
const cue = cues[openers[0]];
const previous = cues[openers[0] - 1];
const head = run.join(" ");
if (words(cue.text).slice(0, run.length).join(" ") !== head) return false;
return (
previous.endSec > cue.startSec || words(previous.text).slice(-run.length).join(" ") === head
);
}

/**
* Drop the words a paragraph opens with when they repeat the previous
* paragraph's closing words, the longest run first: 2 to 12 words compared
* case- and punctuation-insensitively, and only when the opening cue carries
* them over from the cue before it ({@link carriesOverFromPreviousCue}). A
* rolling auto caption carries its tail into the next cue, and the vendor
* formatter only drops overlaps of 3 or more words it matches ignoring case
* alone. A repeat the speaker actually said ("very good." / "Very good
* question", "I don't know." / "I don't know why.") stays. A paragraph always
* keeps at least one word.
*
* @param {string} transcript - paragraphs joined by a blank line, each `[M:SS] text`
* @param {readonly { startSec: number, endSec: number, text: string }[]} cues - the
* cues the transcript was formatted from
* @returns {string}
*/
export function dropParagraphBoundaryRepeats(transcript, cues) {
const paragraphs = transcript.split("\n\n");
for (let index = 1; index < paragraphs.length; index++) {
const current = PARAGRAPH_STAMP.exec(paragraphs[index]);
const previous = PARAGRAPH_STAMP.exec(paragraphs[index - 1]);
if (!current || !previous) continue;
const previousWords = words(previous[2]);
const currentTokens = tokens(current[2]);
const wordAt = currentTokens.flatMap((token, at) => (isWord(token) ? [at] : []));
const currentWords = wordAt.map((at) => currentTokens[at]);
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
const longest = Math.min(
BOUNDARY_REPEAT_MAX_WORDS,
previousWords.length,
currentWords.length - 1,
);
for (let length = longest; length >= BOUNDARY_REPEAT_MIN_WORDS; length--) {
const run = currentWords.slice(0, length);
if (comparableRun(previousWords.slice(-length)) !== comparableRun(run)) continue;
// Every match, whatever its length, needs cue-level carry-over evidence:
// a speaker may genuinely repeat several words ("I don't know." / "I
// don't know why.").
if (!carriesOverFromPreviousCue(current[1].trim(), run, cues)) continue;
// Keep punctuation-only tokens before the dropped words (a `>>` speaker
// marker); drop any between them.
const kept = [
...currentTokens.slice(0, wordAt[0]),
...currentTokens.slice(wordAt[length - 1] + 1),
];
paragraphs[index] = current[1] + kept.join(" ");
break;
}
}
return paragraphs.join("\n\n");
}

/**
* Build transcript text from a caption file.
*
Expand Down Expand Up @@ -66,7 +187,8 @@ export function buildTranscriptText(vttText, isAutoCaption, { repairLexicon = nu
repairedTermCount = repaired.replacementCount;
}

const transcript = formatTranscript(cues);
const formatted = formatTranscript(cues);
const transcript = isAutoCaption ? dropParagraphBoundaryRepeats(formatted, cues) : formatted;

return {
transcript,
Expand Down
Loading
Loading