AgentTranscriptIndexGuard.kt

    @JvmStatic
    fun main(args: Array<String>) {
        val repo = repoRoot()
        val index = File(repo, INDEX_REL)
        val corpusDir = File(repo, CORPUS_REL)
        require(index.isFile) { "no index page at ${index.absolutePath}" }
        require(corpusDir.isDirectory) { "no transcript corpus at ${corpusDir.absolutePath}" }

        val corpus = (corpusDir.listFiles { f -> f.isFile && f.extension == "yaml" } ?: emptyArray())
            .map { it.nameWithoutExtension }
            .sorted()
        require(corpus.isNotEmpty()) { "no transcript yaml in ${corpusDir.absolutePath}" }

        val lines = index.readLines()
        val problems = mutableListOf<String>()

        // ---- parse the page ----
        val sections = mutableListOf<Section>()
        val entries = mutableListOf<Entry>()
        var current: Section? = null
        var totalsParagraph: String? = null
        // A fenced code block on this page can legitimately contain a `## …` line or an entry-shaped
        // line (the "Running one" fence does not, but a future one might), and reading either as page
        // structure would be a confusing false failure. So fences are skipped rather than parsed.
        var inFence = false
        for ((i, raw) in lines.withIndex()) {
            if (raw.trimStart().startsWith("```")) {
                inFence = !inFence
                continue
            }
            if (inFence) continue
            val heading = HEADING.find(raw)
            if (heading != null) {
                val title = heading.groupValues[1]
                val bundled = (i + 1 until minOf(i + 5, lines.size)).any { BUNDLED.containsMatchIn(lines[it]) }
                current = Section(title, i + 1, if (bundled) emptySet() else declaredLevels(lines, i, title, problems), bundled)
                sections.add(current)
            }
            val entry = ENTRY.find(raw)
            if (entry != null) {
                entries.add(Entry(entry.groupValues[1], i + 1, current, openLinkTarget(lines, i)))
            }
            if (TOTALS.containsMatchIn(raw)) {
                totalsParagraph = lines.drop(i + 1).takeWhile { it.isNotBlank() }.joinToString(" ")
            }
        }

        // ---- bundled documents: their own section, held to BUNDLED_DOCUMENT_STARTING_POINTS ----
        val bundledEntries = entries.filter { it.section?.bundled == true }
        val bundledByName = bundledEntries.groupBy { it.name }
        for ((name, rel) in BUNDLED_DOCUMENT_STARTING_POINTS) {
            val found = bundledByName[name]
            if (found == null) problems.add(
                "$name: a bundled starting point (BUNDLED_DOCUMENT_STARTING_POINTS) with NO entry under the " +
                    "`<!-- transcript-index: bundled -->` section of $INDEX_REL. Write a `### $name` entry there."
            ) else if (found.size > 1) problems.add("$name: ${found.size} bundled entries on $INDEX_REL — keep one.")
            if (!File(File(repo, "public/docs/assets/$rel").canonicalFile, "metadata.edn").isFile) problems.add(
                "$name: BUNDLED_DOCUMENT_STARTING_POINTS points at public/docs/assets/$rel, which holds no metadata.edn."
            )
        }
        for (entry in bundledEntries) if (entry.name !in BUNDLED_DOCUMENT_STARTING_POINTS) problems.add(
            "line ${entry.line}: entry `### ${entry.name}` is in the bundled section but is not in " +
                "BUNDLED_DOCUMENT_STARTING_POINTS, so the welcome screen does not offer it."
        )
        entries.removeAll(bundledEntries)
        for (section in sections.filter { it.bundled }) sections.remove(section)

        // ---- 1 & 2: completeness and orphans ----
        val byName = entries.groupBy { it.name }
        for (name in corpus) {
            val found = byName[name]
            when {
                found == null -> problems.add(
                    "$name: in the corpus (dev_docs/agents/transcripts/$name.yaml) but has NO entry on " +
                        "$INDEX_REL. Write one: a `### $name` heading and a paragraph under the section whose " +
                        "verified-by marker matches how CI checks it. See dev_docs/agent_transcript_index.md."
                )
                found.size > 1 -> problems.add(
                    "$name: ${found.size} entries on $INDEX_REL (lines ${found.joinToString(", ") { it.line.toString() }}) — keep one."
                )
            }
        }
        for (entry in entries) {
            if (entry.name !in corpus) problems.add(
                "line ${entry.line}: entry `### ${entry.name}` names no transcript — dev_docs/agents/transcripts/" +
                    "${entry.name}.yaml does not exist. Delete the entry, or fix the name if the yaml was renamed."
            )
        }

        // ---- 3: each entry's CI level is one its section declares ----
        val sectionless = sections.filter { it.levels.isEmpty() && entries.any { e -> e.section == it } }
        for (section in sectionless) problems.add(
            "line ${section.line}: section \"${section.title}\" holds entries but declares no CI level. Add a " +
                "`<!-- transcript-index: verified-by = execute -->` marker (or compile / kotlinjs, comma-separated) " +
                "under the heading."
        )
        for (entry in entries) {
            if (entry.name !in corpus) continue
            val level = levelOf(entry.name)
            val section = entry.section
            if (level == null) {
                problems.add(
                    "${entry.name}: not in EXECUTE, COMPILE_ONLY or KOTLINJS in DemoTranscriptExecSmokeTest, so " +
                        "nothing in CI verifies it and the page cannot honestly say how it is checked."
                )
                continue
            }
            if (section == null) {
                problems.add("line ${entry.line}: entry `### ${entry.name}` sits above the first `##` section heading.")
                continue
            }
            if (section.levels.isNotEmpty() && level !in section.levels) problems.add(
                "${entry.name}: entry at line ${entry.line} is under \"${section.title}\", which declares " +
                    "verified-by = ${section.levels.joinToString(", ") { it.marker }}, but CI verifies this " +
                    "transcript as ${level.marker} (${level.describe}). Move the entry, or widen the section's marker " +
                    "and its prose."
            )
        }

        // ---- 4: Open links exist exactly for materialized transcripts, and resolve ----
        val bundleRoot = File(repo, BUNDLE_REL)
        for (entry in entries) {
            if (entry.name !in corpus) continue
            val materialized = entry.name !in AgentTranscriptMaterializer.EXCLUDE
            val target = entry.openTarget
            when {
                materialized && target == null -> problems.add(
                    "${entry.name}: entry at line ${entry.line} has no `Open ↗` link, but the transcript IS " +
                        "materialized into $BUNDLE_REL/${entry.name}/ and is offered on the welcome screen. Link it: " +
                        "[Open ↗](offline.html?file=assets/agent_transcripts/${entry.name}/metadata.edn)"
                )
                !materialized && target != null -> problems.add(
                    "${entry.name}: entry at line ${entry.line} links a starting point, but the transcript is in " +
                        "AgentTranscriptMaterializer.EXCLUDE, so no document is generated for it and the link is dead. " +
                        "Drop the link and say in the prose why this one is agent-only."
                )
                target != null && target != entry.name -> problems.add(
                    "${entry.name}: entry at line ${entry.line} links $BUNDLE_REL/$target/metadata.edn — the wrong " +
                        "transcript's starting point (a copy-paste)."
                )
                target != null && !File(File(bundleRoot, target), "metadata.edn").isFile -> problems.add(
                    "${entry.name}: entry at line ${entry.line} links $BUNDLE_REL/$target/metadata.edn, which is not " +
                        "committed. Regenerate with `./gradlew regenerateAgentTranscriptStartingPoints`."
                )
            }
        }

        // ---- 5: no counts in the CI paragraph ----
        val totals = totalsParagraph
        if (totals == null) {
            problems.add(
                "$INDEX_REL has no `<!-- transcript-index: totals -->` marker. Put it directly above the paragraph " +
                    "that says how each transcript is verified."
            )
        } else {
            val numbers = Regex("""\b\d+\b""").findAll(totals).map { it.value }.toList()
            if (numbers.isNotEmpty()) problems.add(
                "the totals paragraph quotes ${numbers.joinToString(", ")}. It must quote no counts: every branch that " +
                    "adds a transcript would have to edit it, and those edits conflict. Describe the depths without numbers."
            )
        }

        if (problems.isNotEmpty()) {
            System.err.println("AgentTranscriptIndexGuard FAILED with ${problems.size} problem(s):")
            problems.forEach { System.err.println("  - $it") }
            System.err.println(
                "\n$INDEX_REL is the public index of the transcript corpus. It is hand-written on purpose — see " +
                    "dev_docs/agent_transcript_index.md — so these are fixed by editing prose, not by regenerating."
            )
            exitProcess(1)
        }
        println(
            "AgentTranscriptIndexGuard ok — ${corpus.size} transcript(s), ${entries.size} entry/entries, " +
                sections.filter { it.levels.isNotEmpty() }
                    .joinToString("; ") { "\"${it.title}\" = ${it.levels.joinToString("+") { l -> l.marker }}" }
        )
    }