import { LABOUR_SECTION_ICON, LOOP_SECTION_ICON } from "#configuration/icons/methodology.start.icons";
import { LABOUR_SECTION_ID, LOOP_SECTION_ID } from "#core/ids/methodology.start.ids";
import { layerLink as layer, nodeLink as node, stageLink as stage } from "#domain/converters/link.converter";
import type { Section } from "#types/document.types";

const LOOP_DIAGRAM =
    'flowchart TB\n    subgraph epistemic["Epistemic · how is it known?"]\n        orient["Orient · name the subject, read from the tree"]\n        see["See · look through the lenses the subject warrants"]\n        derive["Derive · a claim grounded in what was seen"]\n        project["Project · the next admissible move"]\n        act["Act · apply the operation to the state"]\n    end\n    subgraph conative["Conative · what is worth doing?"]\n        intent["Intent · the objective, and the highest-worth branch"]\n        constrain["Constrain · is the operation admissible?"]\n    end\n    subgraph evaluative["Evaluative · is it right, and are we done?"]\n        verify["Verify · is the evidence set non-empty?"]\n        commit["Commit · externalise the result as inspectable state"]\n        terminate["Terminate · saturated, complete and verified?"]\n    end\n    orient --> intent\n    intent -- gate: worth before work --> see\n    see --> derive --> project --> act --> constrain\n    constrain -- gate: admissible --> verify\n    verify -- gate: evidence --> commit --> terminate\n    verify -. refuted, back with the evidence .-> derive\n    terminate -- gate: stop --> orient';

const SCALE_DIAGRAM =
    'flowchart TB\n    fix["A one-line fix · one traversal, minutes"]\n    task["A task · one traversal, an afternoon"]\n    phase["A phase · one traversal that holds many tasks"]\n    plan["A plan · one traversal that holds many phases"]\n    fix --- task --- phase --- plan\n    plan -. each phase walks the loop again inside .-> phase\n    phase -. each task walks the loop again inside .-> task';

const LABOUR_DIAGRAM =
    'flowchart TB\n    subgraph tooling["The tooling"]\n        detect["Detection · every rule, on every change, the same way"]\n        heal["Healing · what a fixer can restore, it restores"]\n    end\n    subgraph ai["The AI"]\n        repair["Repair · what the fixers left, one finding at a time"]\n    end\n    subgraph operator["The operator"]\n        govern["Governance · what the work is for, and what finished means"]\n    end\n    detect --> heal\n    heal -- the findings left --> repair\n    repair -- a changed tree --> detect\n    govern -- rules and objectives --> detect\n    govern -- corrections --> repair\n    repair -. questions .-> govern';

const STAGES = [
    "orient",
    "intent",
    "see",
    "derive",
    "project",
    "act",
    "constrain",
    "verify",
    "commit",
    "terminate",
] as const;

const LOOP_SECTION: Section = {
    icon: LOOP_SECTION_ICON,
    id: LOOP_SECTION_ID,
    intro: `Every piece of work here has the same shape. A plan, a check, an agent, a refactor and a review are one loop at different sizes. The loop is the first thing to learn, because every later chapter is the loop applied to one kind of work, as <cite>ten nodes</cite> draws and <cite>four sizes</cite> nests, and every mechanism in this method exists to hold one of its gates. The loop is published as records on the ontology page, one per stage: ${STAGES.map(stage).join(", ")}.`,
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Run the loop at the size of the task, and name the node the work is on. The four gates never fold whatever the size: worth is decided before any effort, an operation is admitted before it is trusted, a claim needs evidence before it is committed, and the loop stops as done only when nothing is left, everything is done and everything is verified; otherwise it stops as blocked.",
                    boundary:
                        "The loop is not a ceremony for a throwaway script. It earns its cost where the work will be read, changed or trusted by someone later. A reference, a note or a contract is descriptive rather than executed, and forcing the full loop onto it produces ceremony rather than rigour.",
                    cause: "Nothing forced a shape onto the work, so the shape came from the model's next likely sentence.",
                    decision: "Run the same ten nodes at every size, rather than a lighter shape for a smaller task.",
                    failureMode:
                        "The AI starts writing code in the first message, guesses the goal, and the conversation drifts as each reply answers the previous reply instead of the task.",
                    kind: "lesson",
                    principle: "Work has one shape, and the shape is the loop.",
                    problem: "Work with an AI tends to start at execution and skip everything before it.",
                    validation:
                        "Read the plan, the check and the agent for one task as the same ten nodes. A step that fits none of them is either missing or noise.",
                },
                {
                    kind: "text",
                    text: `Three layers own the nodes. The ${layer("epistemic", "epistemic")} layer asks how a thing is known: orient names the subject as a bounded set of things read from the tree, see picks the lenses that subject warrants, derive produces a claim grounded in what was seen, project chooses the next admissible move, and act applies it to the state. The ${layer("conative", "conative")} layer asks what is worth doing: intent states the ${node("tel-objective", "objective")} and ranks the branches by ${node("tel-priority", "priority")}, and constrain admits or refuses the operation once it exists. The ${layer("evaluative", "evaluative")} layer asks whether it is right and whether it is done: verify demands ${node("ver-evidence", "evidence")}, commit writes the result down as state the next cycle can read, and terminate decides whether to ${node("ter-stop", "stop")}.`,
                },
                {
                    kind: "text",
                    text: `The edges carry as much as the nodes. A ${node("ver-refutation", "refuted")} claim goes back to derive with the evidence that refuted it, never forward with a caveat. A repair re-enters at the earliest node that can supply the missing evidence, invalidates everything after it, and is bounded, so a loop that keeps repairing terminates as ${node("ter-block", "blocked")} rather than as done. Every decision has a declared shape: a gate that owes a ranking is not satisfied by a yes, and a gate that owes a yes is not satisfied by a ranking. The same loop is what an agent template walks and what an instruction pattern selects by fit, which is why the grammar page and this page describe one loop twice.`,
                },
                { caption: "ten nodes", kind: "mermaid", text: LOOP_DIAGRAM },
            ],
            title: "Ten nodes, every size",
        },
        {
            blocks: [
                {
                    kind: "text",
                    text: "The loop nests. A plan is one traversal whose act node produces phases, and each phase is a traversal whose act node produces tasks, and each task is a traversal that ends in an edit and a run of the checks. The gates hold at every level. A phase cannot start until the phase before it has committed evidence the next one reads, and a plan cannot stop until every phase has, which is why the plan is a graph with a gate between phases rather than a tick beside each.",
                },
                {
                    kind: "text",
                    text: "The difference between an instruction and a traversal is visible in the first minute. The instruction asks for an outcome. The traversal names the nodes it passes through, so a reader can see where it went wrong. Asked to raise a file limit, a traversal orients by opening every file that mentions the limit and finds two copies of the first. It states its intent as one limit with a single source of truth, and derives that the request is a one home problem rather than a limit change. It acts by changing the declaration and deleting the copies, and constrains itself to the checker's one option. It verifies by running the gate once and reading the output whole, commits the report, and terminates because the objective sentence reads true against the tree. The edit touched one file instead of three, and the reader can see which node the work is at from the message alone.",
                },
                { caption: "four sizes", kind: "mermaid", text: SCALE_DIAGRAM },
            ],
            title: "Instruction and traversal",
        },
    ],
    title: "The loop",
};

const LABOUR_SECTION: Section = {
    icon: LABOUR_SECTION_ICON,
    id: LABOUR_SECTION_ID,
    intro: "The tooling detects and heals what it can. The AI repairs what the fixers leave. I govern. Each of us does the part we are suited for, as <cite>three parties</cite> draws, and the parts do not swap. This division is the second thing to learn, because every later chapter assumes it, and every failure this method knows is one party doing another party's job. The architecture page derives the same split from a different premise, that the author is probabilistic, and lands on the same three parties.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Give detection to a check that runs the same way every time, with its fixer on by default. Give the findings the fixer cannot close to the AI, one at a time, each with its location and its expected value. Keep the decisions about what the work is for, and hand nothing else down.",
                    cause: "A person cannot attend to every line, and a model cannot tell a rule from a preference unless something outside it holds the line.",
                    decision:
                        "Give detection to the tooling and governance to the person, rather than a review that reads what a check could hold.",
                    failureMode:
                        "The person reviews for style, the AI reviews for correctness, and both miss the architectural drift because neither owns it.",
                    kind: "lesson",
                    principle: "Quality is a property of the tooling, not of anyone's attention.",
                    problem:
                        "When nobody names the roles, the human ends up doing the machine's job and the machine ends up guessing the human's.",
                    validation:
                        "Read the last ten findings your tooling raised. Every one of them names a check, not a person. If a person found it, the check is missing.",
                },
                {
                    kind: "text",
                    text: "Detection is mechanical because it has to be identical on every run. A rule a reviewer applies from memory is applied differently on a tired day, and a rule a model applies from a prompt is applied differently once the context fills, while a check is static analysis that returns the same verdict for the same tree. One correct answer and scale follows determinism derive what follows from that. Healing belongs to the same party for the same reason: where exactly one correct answer exists, the fixer applies it in the run that caught the fault, and nobody is asked.",
                },
                {
                    kind: "text",
                    text: "Repair belongs to the AI because a finding is small and specific, and a model does small and specific things well; detect, log, fix carries the finding's shape. What it does not do is judge its own work as done, because reading an edit is not running the checks, which it looked right is built on. Governance stays with the person because worth is not computed here. What the work is for, what finished looks like and which of two admissible branches wins are decisions I make and write down before the effort starts. A correction I give is expected to harden into a rule rather than to be remembered; a rule that lives only in a person is manual-only governance, and it decays.",
                },
                { caption: "three parties", kind: "mermaid", text: LABOUR_DIAGRAM },
            ],
            title: "Three parties, three jobs",
        },
    ],
    title: "Who does what",
};

export const START_SECTIONS: readonly Section[] = [LOOP_SECTION, LABOUR_SECTION];