opensite-ai/opensite-skills / book-recorded-sessions
book-recorded-sessions
VerifiedPlan, record, and merge recorded sessions into book chapters: solo lessons, interviews with a proxy reader, multi-guest panels, or hybrid lesson-plus-conversation episodes that also serve video and short-form clips. Covers contract-driven run-of-show, contributor releases and employer clearance, per-speaker capture and transcripts, speaker-attributed atoms, merging many sessions into a traceable chapter, and clip hand-off flags. Use when chapters are built from spoken recordings or podcasts. Not for narrating the finished audiobook or editing clips.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
| assets/segment_types.yaml | config | 5.1 KB |
| references/contributor-release.md | markdown | 2.8 KB |
| references/merge-rules.md | markdown | 2.4 KB |
| references/session-formats.md | markdown | 3.8 KB |
| scripts/chapter_trace.pyexecutable | script | 8.1 KB |
| scripts/session_ingest.pyexecutable | script | 9.4 KB |
| scripts/session_plan.pyexecutable | script | 8.1 KB |
scripts/chapter_trace.py
View on GitHub#!/usr/bin/env python3
"""Check that merged chapters trace to recorded words and that guests' words are cleared and credited.
Each paragraph of a chapter built from sessions carries one or more source markers,
<!-- src:A-0012 --> or <!-- src:A-0012,A-0031 -->, naming atoms in 01-evidence/ATOMS.csv.
Atoms carry a speaker (contributor_id in CONTRIBUTORS.csv; empty means the author). Text the
agent had to compose sits inside {{ai}} ... {{/ai}} for the author to rewrite (mode T).
Checks, by authorship mode (04-rights/AUTHORSHIP_MODE.md):
all modes every src atom exists; no private atoms; each guest used has a contributor
release row in RIGHTS_LEDGER.csv (status cleared at --lock); a guest with an
attribution is named in the paragraph that uses their words
mode T every paragraph is traced or inside an {{ai}} span; the author's share of the
chapter's traced words is at least --min-author-share (default 0.6); at --lock
no {{ai}} words remain
mode H/G tracing is optional; guest checks still apply to traced paragraphs
Usage:
python scripts/chapter_trace.py <project_root> [chapter.md ...] [--lock]
[--min-author-share 0.6] [--json 06-production/reports/chapter_trace.json]
Default chapters: 03-manuscript/chapters/*.md. Exit 0 when every check passes.
"""
import argparse
import csv
import json
import pathlib
import re
import sys
SRC = re.compile(r"<!--\s*src:([^>]*?)-->")
COMMENT = re.compile(r"<!--.*?-->", re.S)
AI = re.compile(r"\{\{ai\}\}(.*?)\{\{/ai\}\}", re.S)
WORD = re.compile(r"[\w'’-]+")
SKIP = re.compile(r"^\s*(#|!\[|---\s*$|\*\*\*\s*$)")
def rows(path):
if not path.exists():
return []
with open(path, newline="", encoding="utf-8") as fh:
return list(csv.DictReader(fh))
def words(text):
return len(WORD.findall(COMMENT.sub(" ", text)))
def mode_of(root):
p = root / "04-rights" / "AUTHORSHIP_MODE.md"
m = re.search(r"Selected mode:\s*\**\s*([HTG])\b", p.read_text(encoding="utf-8")) if p.exists() else None
return m.group(1) if m else None
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("root")
ap.add_argument("chapters", nargs="*")
ap.add_argument("--lock", action="store_true")
ap.add_argument("--min-author-share", type=float, default=0.6)
ap.add_argument("--json")
args = ap.parse_args()
root = pathlib.Path(args.root).resolve()
files = [pathlib.Path(c) for c in args.chapters] or sorted((root / "03-manuscript" / "chapters").glob("*.md"))
mode = mode_of(root)
problems, warnings = [], []
if mode is None:
problems.append("authorship mode not selected in 04-rights/AUTHORSHIP_MODE.md")
atoms = {r["atom_id"].strip(): r for r in rows(root / "01-evidence" / "ATOMS.csv") if (r.get("atom_id") or "").strip()}
people = {r["contributor_id"].strip(): r for r in rows(root / "01-evidence" / "CONTRIBUTORS.csv")
if (r.get("contributor_id") or "").strip()}
authors = [cid for cid, r in people.items() if (r.get("role") or "").strip() == "author"] or ["author"]
rights = {r.get("item_id", "").strip(): r for r in rows(root / "04-rights" / "RIGHTS_LEDGER.csv")}
report_chapters = []
for f in files:
text = re.sub(r"```.*?```", "\n", f.read_text(encoding="utf-8"), flags=re.S) # code is not prose
blocks = []
for blk in re.split(r"\n\s*\n", text):
kept = "\n".join(line for line in blk.splitlines() if not SKIP.match(line)) # drop headings, images, rules
if COMMENT.sub("", kept).strip():
blocks.append(kept)
by_speaker, untraced, ai_words, traced_words = {}, [], 0, 0
for i, blk in enumerate(blocks, 1):
spans = AI.findall(blk)
a_w = sum(words(s) for s in spans)
ai_words += a_w
body = AI.sub(" ", blk)
b_w = words(body)
ids = [x.strip() for m in SRC.findall(blk) for x in re.split(r"[;,]", m) if x.strip()]
if not ids:
if b_w:
untraced.append(i)
continue
speakers = []
for aid in ids:
a = atoms.get(aid)
if a is None:
problems.append(f"{f.name} paragraph {i}: src atom {aid} not in ATOMS.csv")
continue
if (a.get("sensitivity") or "").strip() == "private":
problems.append(f"{f.name} paragraph {i}: atom {aid} is private")
elif (a.get("sensitivity") or "").strip() == "sanitize":
warnings.append(f"{f.name} paragraph {i}: atom {aid} must be sanitized; confirm before lock")
sp = (a.get("speaker") or "").strip() or authors[0]
speakers.append(sp)
if sp in authors:
continue
person = people.get(sp)
if person is None:
problems.append(f"{f.name} paragraph {i}: atom {aid} speaker {sp!r} not in CONTRIBUTORS.csv")
continue
rid = (person.get("rights_id") or "").strip()
status = rights.get(rid, {}).get("status", "").strip() if rid in rights else None
if status is None:
problems.append(f"{f.name} paragraph {i}: {sp} has no contributor release in RIGHTS_LEDGER.csv")
elif status != "cleared":
(problems if args.lock else warnings).append(
f"{f.name} paragraph {i}: {sp} release {rid} is {status or 'empty'}, not cleared")
attribution = (person.get("attribution") or "").strip().lower()
if attribution not in ("", "none", "uncredited"):
name = (person.get("name") or "").strip()
first = name.split()[0] if name else ""
plain = COMMENT.sub(" ", body).lower()
if not ((name and name.lower() in plain) or (first and re.search(rf"\b{re.escape(first.lower())}\b", plain))):
problems.append(f"{f.name} paragraph {i}: uses {sp}'s words without naming them")
if speakers and b_w:
traced_words += b_w
for sp in speakers:
by_speaker[sp] = by_speaker.get(sp, 0) + b_w / len(speakers)
author_w = sum(v for k, v in by_speaker.items() if k in authors)
share = round(author_w / traced_words, 3) if traced_words else None
if mode == "T":
if untraced:
problems.append(f"{f.name}: paragraphs {untraced} have no src marker and are not marked {{{{ai}}}}")
if share is not None and share < args.min_author_share:
problems.append(f"{f.name}: author share of traced words {share:.0%} is below {args.min_author_share:.0%}")
if args.lock and ai_words:
problems.append(f"{f.name}: {ai_words} words still inside {{{{ai}}}} spans at lock")
report_chapters.append({"file": f.name, "paragraphs": len(blocks), "untraced_paragraphs": untraced,
"traced_words": traced_words, "ai_words": ai_words, "author_share": share,
"words_by_speaker": {k: round(v) for k, v in by_speaker.items()}})
if not files:
problems.append("no chapter files found")
report = {"pass": not problems, "mode": mode, "lock": args.lock, "min_author_share": args.min_author_share,
"chapters": report_chapters, "problems": problems, "warnings": warnings}
for c in report_chapters:
sh = "n/a" if c["author_share"] is None else f"{c['author_share']:.0%}"
print(f"{c['file']}: {c['paragraphs']} paragraphs, untraced {len(c['untraced_paragraphs'])}, "
f"author share {sh}, ai words {c['ai_words']}")
for p in problems:
print(f" - {p}")
for w_ in warnings:
print(f" ~ {w_}")
print("PASS" if report["pass"] else "FAIL")
if args.json:
pathlib.Path(args.json).write_text(json.dumps(report, indent=2), encoding="utf-8")
return 0 if report["pass"] else 1
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |