import { FLAT_LIST_SECTION_ICON, TEMPLATE_SECTION_ICON, WORTH_SECTION_ICON } from "#configuration/icons/plan.icons";
import { FLAT_LIST_SECTION_ID, TEMPLATE_SECTION_ID, WORTH_SECTION_ID } from "#core/ids/plan.ids";
import { MARKDOWN_LANGUAGE, TYPESCRIPT_LANGUAGE } from "#configuration/constants/code.constants";
import { nodeLink as node, stageLink as stage } from "#domain/converters/link.converter";
import type { Section } from "#types/document.types";

const NODE_CONTRACT_SHAPE =
    'export const LAYERS = ["epistemic", "conative", "evaluative"] as const;\nexport const NODES = ["orient", "intent", "see", "derive", "project", "act", "constrain", "verify", "commit", "terminate"] as const;\n\nexport type Yields =\n    | { readonly mathType: "set-theory"; readonly shape: "set" | "boolean" }\n    | { readonly mathType: "logic"; readonly shape: "boolean" }\n    | { readonly mathType: "graph"; readonly shape: "edge-list" }\n    | { readonly mathType: "optimisation"; readonly shape: "boolean" | "ranking" }\n    | { readonly mathType: "probability"; readonly shape: "number[0,1]" }\n    | { readonly mathType: "computation"; readonly shape: "procedure" };\n\nexport interface Gate<Node extends (typeof NODES)[number]> {\n    readonly rule: Node;\n    readonly checks: readonly { readonly claim: string; readonly evidence: string }[];\n    readonly onPass: Node | "STOP";\n    readonly onFail: { readonly owner: Node; readonly bounded: true };\n}\n\nexport interface NodeContract<Node extends (typeof NODES)[number], Input, Output> {\n    readonly node: Node;\n    readonly layer: (typeof LAYERS)[number];\n    readonly yields: Yields;\n    readonly input: Input;\n    readonly transform: (input: Input) => Output;\n    readonly constraints: readonly string[];\n    readonly output: Output;\n    readonly handoff: Gate<Node>;\n}\n\nexport type Mandatory = "intent" | "constrain" | "verify" | "terminate";';

const PLAN_TEMPLATE =
    "# <what this change is for, in one sentence>\n\n## Worth\nObjective: the outcome, named so the result can be checked against it.\nNot in scope: the nearest things this change will not do.\nBranches ranked: the way chosen, and why the others lost.\n\n## Admissible\nHard limits: what no phase may cross, whatever it would gain.\nCost: what this is allowed to take, and the point past which it stops.\n\n## Phases, ordered by dependency\n### Phase 1: <name>\nNeeds: nothing.\nGate: the evidence Phase 2 reads before it starts.\n- [ ] task: <one change> — file: <where> — evidence: <what proves it> — verifier: <who reads it> — not: <what this task leaves alone>\n\n### Phase 2: <name>\nNeeds: the gate of Phase 1.\nGate: ...\n\n## Termination\nThe run stops when the objective sentence reads true against the tree, not when the list is ticked.";

const WORTH_DIAGRAM =
    'flowchart TB\n    request["A request"]\n    objective["The objective · one sentence the result is checked against"]\n    nongoal["The non-goal · the nearest thing this will not do"]\n    branches["The admissible branches"]\n    rank{"Highest worth · utility minus cost?"}\n    chosen["The chosen branch, and why the others lost"]\n    stop["Below worth · redirect or stop"]\n    request --> objective --> nongoal --> branches --> rank\n    rank -- yes --> chosen\n    rank -- no --> stop';

const PLAN_SHAPE_DIAGRAM =
    'flowchart TB\n    subgraph flat["The flat list"]\n        direction TB\n        f1["item, in the order it came to mind"] --> f2["item"] --> f3["item"] --> f4["item"]\n        f4 --> ticked["done when every box is ticked"]\n    end\n    subgraph graph["The graph"]\n        direction TB\n        p1["phase 1"] -- gate: the evidence phase 2 reads --> p2["phase 2"]\n        p1 -- gate --> p3["phase 3"]\n        p2 -- gate --> p4["phase 4"]\n        p3 -- gate --> p4\n        p4 --> objective["done when the objective sentence reads true against the tree"]\n    end';

const TEMPLATE_DIAGRAM =
    'flowchart TB\n    draft["Draft · the first plan from the task"]\n    compare["Compare · node by node, gate by gate, against the template"]\n    restructure["Restructure · to what the template enforces"]\n    plan["The plan · worth ranked, phases ordered, gates named, termination stated"]\n    draft --> compare --> restructure --> plan\n    compare -. the draft is raw material, the template is the authority .-> draft';

const GENESIS_DIAGRAM =
    'flowchart TB\n    question{"How does the thing come to be?"}\n    checklist["A plan, a checklist, a task set"]\n    claim["A verdict on claims, an audit"]\n    pattern["A shared abstraction from repeated evidence"]\n    agent["A reusable specialised investigator"]\n    layer["A template from an executed document"]\n    none["None fits · say so rather than force one"]\n    question -- anything --> checklist\n    question -- a verdict --> claim\n    question -- a base --> pattern\n    question -- an agent --> agent\n    question -- a template --> layer\n    question -. no fit .-> none';

const WORTH_SECTION: Section = {
    icon: WORTH_SECTION_ICON,
    id: WORTH_SECTION_ID,
    intro: `Before any work starts, one gate decides whether it starts at all, the gate <cite>the worth gate</cite> draws. What is this for, what does finished look like, and is this the highest-worth branch among the ones that are admissible? That is the ${stage("intent")} node of the loop, and the ontology grounds it on the teleology axis: an ${node("tel-objective", "objective")}, a ${node("tel-utility", "utility")}, a ${node("tel-cost", "cost")} and a ${node("tel-priority", "priority")}. A task that cannot answer that is not ready to be a task.`,
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Write the objective in one sentence before the first step, named so the result can be checked against it. Write what is out of scope beside it, because unstated scope grows silently. Rank the admissible ways of getting there by what each advances against what it costs, and say why the chosen one won. Then plan.",
                    boundary:
                        "Worth is not computed here. Nothing evaluates utility minus cost over branches for you. The gate is judgement I apply and write down, and naming that absence is what keeps it from being assumed as a mechanism.",
                    cause: "Starting is cheaper than deciding, and a model will always start if you let it.",
                    decision:
                        "Rank the admissible branches before any effort, rather than take the first workable one.",
                    failureMode:
                        "Three days into a refactor, the question of whether anyone needed the refactor comes up for the first time.",
                    kind: "lesson",
                    principle: "Worth comes before work, and a non-goal is stated as plainly as a goal.",
                    problem: "Work that skips the question of worth is done well and needed by nobody.",
                    validation:
                        "Read the objective back after the work. The result must be the thing the sentence named. A result that needs a new sentence to describe it answered a different question.",
                },
                {
                    kind: "text",
                    text: `The gate has a shape, and the shape is why it holds. Intent yields an objective and a ranking, never a yes. A ranking needs more than one branch, so a plan with one option has not ranked anything and has not passed the gate. Each branch carries what it advances and what it costs, and the chosen branch is the one where that difference is largest among the branches that are admissible at all. A branch that would cross a hard limit is not a worse option, it is not an option, and admissibility is asked again at the ${stage("constrain")} node after the work exists, because a plan that was admissible on paper can produce a change that is not. When rules collide is the same gate applied to two rules on one construct.`,
                },
                {
                    kind: "text",
                    text: "A non-goal does more work than a goal. A unit's stated scope is what its author intended, and its unstated scope is whatever accretes onto it because nothing said no; the ontology calls the accretion speculative generality. Writing down the nearest thing the change will not do is what makes the next reader able to refuse the addition that would have turned a focused unit into a god object. The same test applies to every surface, record or field a plan proposes: it names a consumer that breaks without it, rather than one that would merely read it, and a thing that cannot break either way is the finding.",
                },
                {
                    kind: "text",
                    text: "The same task reads differently once worth is decided. Without it: <em>clean up the config and the checker, they have gotten messy</em>. With it: <em>objective, one limit with one home; not in scope, the checker's other options; chosen, derive it from the config, because the two other homes cannot be deleted otherwise</em>. The second version can be finished. The first cannot.",
                },
                { caption: "the worth gate", kind: "mermaid", text: WORTH_DIAGRAM },
            ],
            title: "What is this for",
        },
    ],
    title: "Worth before work",
};

const FLAT_LIST_SECTION: Section = {
    icon: FLAT_LIST_SECTION_ICON,
    id: FLAT_LIST_SECTION_ID,
    intro: "Ask an AI for a plan and you get a flat list. Ten items, no order that matters, no gate between them, and a checkbox after each one that the AI ticks itself. A plan is a directed acyclic graph whose phases pass evidence to each other, whose tasks carry contracts, and whose closed tasks are deleted rather than ticked, the difference <cite>list against graph</cite> draws. It is the same claim the architecture page makes of the code, that a system is a graph, applied to the work on the code.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Order the phases by what depends on what, and within that by what has to exist before what can be built on it. Put a gate between phases that names the evidence the next phase reads before it starts. Give every task a contract: the file it touches, the evidence that proves it, the verifier that reads that evidence, and the thing it deliberately leaves alone. Let severity route a failure to its handler and never order the list.",
                    boundary:
                        "Priority and sprint are metadata on a phase, useful for routing attention, and they never become the section structure. A plan ordered by urgency is a plan whose dependencies are hidden.",
                    cause: "A flat list is the cheapest structure to generate and the cheapest to tick, so both the model and the person prefer it.",
                    decision: "Refuse a plan that has no dependency order and no gates.",
                    failureMode:
                        "Item four depends on item seven, the AI does them in list order, and the plan reaches the end with three items silently undone.",
                    kind: "lesson",
                    principle: "A checklist is a dependency-ordered graph with gated phases, not a list of tasks.",
                    problem:
                        "A task compiled straight into a flat checklist is ungated and unordered, and the ticks on it mean nothing.",
                    validation:
                        "Ask what each phase needs from the one before it. A phase that needs nothing from its predecessor is in the wrong place or the wrong plan.",
                },
                {
                    kind: "text",
                    text: "Ordering has two axes and they are applied in order. The first is dependency: a phase comes after every phase whose output it reads. The second is genesis: a thing exists before it is distinguished, is distinguished before it is related, is related before it is structured, is structured before it is transformed, and is transformed before it is constrained. A phase never depends on an output later in that cycle than the one it produces, so a plan that builds a transformation on a structure that does not exist yet is inverted, and the inversion is a decomposition defect rather than a tie to break.",
                },
                {
                    kind: "text",
                    text: "Impact analysis is recorded as names, never as counts. A row that says three files are affected carries nothing a reader can act on; the three names do. A dimension with no impact carries the evidence that it was assessed and found empty, because a silent cell and an unassessed cell look identical and only one of them is safe. Every task carries a unique id and every citation of an id resolves to a declared task, so a dependency note cannot point at a task that was deleted while reading as live.",
                },
                {
                    kind: "text",
                    text: "The plan carries what is true now and what remains, and nothing else. No findings about defects already repaired, no narrative about how the plan came to be, no inventory of what exists, no closed task left in place with a note. A closed task is deleted, because deleting it is what makes the remaining set the work, and because past on a checklist invites re-implementing what is already done; the planning templates on the grammar page are produced by stages and derived by deletion for that reason. A count written into the plan is written state, and derived state says what happens to it.",
                },
                { caption: "list against graph", kind: "mermaid", text: PLAN_SHAPE_DIAGRAM },
            ],
            title: "The list that ticks itself",
        },
    ],
    title: "The plan is a graph",
};

const TEMPLATE_SECTION: Section = {
    icon: TEMPLATE_SECTION_ICON,
    id: TEMPLATE_SECTION_ID,
    intro: "A plan is executed from a template and never written to look like one, as <cite>draft, compare, restructure</cite> draws. The template is a program: it walks the ten nodes of the loop, asks the questions in order, worth, admissibility, evidence, termination, and emits the artifact the loop terminates on, the node <cite>a node contract</cite> types and the shape <cite>a plan's shape</cite> shows. There is one template per genesis question, as <cite>one per question</cite> draws. The grammar page publishes the template families this chapter executes, and core templates states the rule they all obey: contract, not content.",
    subsections: [
        {
            blocks: [
                {
                    application:
                        "Draft the first plan from the task. Compare the draft against the template node by node and gate by gate. Restructure the draft to what the template enforces, and treat the draft as raw material rather than as something to defend. Keep only current and future work in the result, and delete a task the moment it closes.",
                    boundary:
                        "Only an executed artifact takes the full loop. A reference, a specification, a contract or a note is descriptive, and forcing the loop onto it is the failure of fitting a thing to a shape it does not have.",
                    cause: "A template copied as a shape gives the reader the look of rigour without one of its questions answered.",
                    decision: "Restructure the draft to the template rather than defend the draft.",
                    failureMode:
                        "The plan has all the right headings and none of the right answers, and the reader trusts the headings.",
                    kind: "lesson",
                    principle:
                        "A recurring shape is a template, and a template runs as a procedure rather than serving as a copy.",
                    problem: "A plan that imitates a template's shape carries none of the template's guarantees.",
                    validation:
                        "Read the plan for its answers, not its headings. Every heading must be followed by a decision that could have gone the other way.",
                },
                {
                    kind: "text",
                    text: "The restructure adds what the draft lacks: the ranking worth before work demands, the ordering the plan is a graph demands, an evidence contract on every material claim with a named refuter and a confidence at or above the threshold, and explicit termination. No contradiction found is not support, and termination is saturation and completion and verification together, never a feeling that the work is finished.",
                },
                {
                    kind: "text",
                    text: "A template is chosen by its genesis question, and there is one template per question. How does anything come to be produces a plan, a checklist or a task set. How does a verdict come to be produces an audit or a context check. How does a base abstraction come to be produces a shared pattern from repeated evidence. How does an agent come to be produces a reusable investigator, the agent templates the grammar page carries. How does a template come to be produces a template from an executed document. When two could apply, the artifact being terminated on decides, and when none applies that is stated rather than one being forced.",
                },
                {
                    kind: "text",
                    text: "The second instance of any shape is the trigger to write its template. One instance is an artifact and two is a shape, and the second is authored from a template or it is authored twice, because a party who reads a sibling to learn the format inherits that sibling's accidents as a contract. The template carries the constraint and never one instance's content, and the checks read their contracts from it, as the drop-in describes. Each template inlines its whole structure, which is the one place duplication is deliberate: the shared spine is what makes each template independently executable, and refactoring them toward an import would make none of them so.",
                },
                {
                    kind: "text",
                    text: "A template's loop, typing and gates are domain-neutral and transfer to any tree unchanged; its catalogues are re-derived against what exists, the rule the drop-in states for every core. Gates resolved while producing an artifact are also separated from the gates that run when it executes: an artifact whose generation gates passed is not an artifact whose execution gates passed, and saying so is what keeps the two from being confused.",
                },
                {
                    kind: "text",
                    text: "Every node of a template carries the same contract, and the contract is what makes a template a program rather than a document. A node declares its layer, the mathematical shape its decision yields, the input it reads, which is only the prior node's output, the transformation it applies, the constraints stated at that step, its output, and one evidence-bearing handoff gate. The gate names its checks with the evidence each reads, the node it passes to, and the earliest node a failure routes back to, bounded. The yields type is a discriminated union, so a gate that owes a ranking cannot be satisfied by a boolean and the compiler says so, and the four gates that never fold are a closed subset of the node names rather than a convention a reader remembers. Written this way, a template is checkable by a walk that reads its own declarations: a node without a gate, a gate without evidence, or a decision without a shape fails before anything runs.",
                },
                { code: NODE_CONTRACT_SHAPE, kind: "code", language: TYPESCRIPT_LANGUAGE, title: "a node contract" },
                { code: PLAN_TEMPLATE, kind: "code", language: MARKDOWN_LANGUAGE, title: "a plan's shape" },
                { caption: "draft, compare, restructure", kind: "mermaid", text: TEMPLATE_DIAGRAM },
                { caption: "one per question", kind: "mermaid", text: GENESIS_DIAGRAM },
            ],
            title: "Executed, not imitated",
        },
    ],
    title: "Execute the template",
};

export const PLAN_SECTIONS: readonly Section[] = [WORTH_SECTION, FLAT_LIST_SECTION, TEMPLATE_SECTION];