# configuration/strings/plan.strings.ts > 160 lines of code and 10 definitions. Tree: Site tree Language: typescript Layer: product Canonical: https://banes-lab.com/anatomy/tree#file-configuration-strings-plan-strings-ts Source text: https://banes-lab.com/assets/sources/source.d21a9f0e301c396fd83e985fa66a4c91d91a4404a26e16482d24a0c0552e12fe.generated.txt ## Definitions - `NODE_CONTRACT_SHAPE` (lexical_declaration, line 7) - `PLAN_TEMPLATE` (lexical_declaration, line 10) - `WORTH_DIAGRAM` (lexical_declaration, line 13) - `PLAN_SHAPE_DIAGRAM` (lexical_declaration, line 16) - `TEMPLATE_DIAGRAM` (lexical_declaration, line 19) - `GENESIS_DIAGRAM` (lexical_declaration, line 22) - `WORTH_SECTION` (lexical_declaration, line 25) - `FLAT_LIST_SECTION` (lexical_declaration, line 70) - `TEMPLATE_SECTION` (lexical_declaration, line 114) - `PLAN_SECTIONS` (lexical_declaration, line 170, exported) ## Source ```typescript 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 {\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 {\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;\n}\n\nexport type Mandatory = "intent" | "constrain" | "verify" | "terminate";'; const PLAN_TEMPLATE = "# \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: \nNeeds: nothing.\nGate: the evidence Phase 2 reads before it starts.\n- [ ] task: — file: — evidence: — verifier: — not: \n\n### Phase 2: \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 allowed approaches"]\n rank{"Highest worth · utility minus cost?"}\n chosen["The chosen approach, 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. It asks three questions, as shown in the worth gate: what the work is for, what finished looks like, and whether this is the most worthwhile of the approaches that are allowed. This gate is the ${stage("intent")} node of the loop, and on the ontology page it rests on four records: 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 these questions is not ready to be a task.`, subsections: [ { blocks: [ { application: "In practice, the objective is written in one sentence before the first step, worded so the result can be checked against it. What is out of scope is written beside it, because scope that is never stated grows quietly. Each approach is weighed by what it achieves against what it costs, the reason the chosen one won is written down, and only then does planning begin.", boundary: "Worth is not computed anywhere in this method: no tool weighs utility against cost across the approaches for you. The gate is a judgement I make and write down, and saying so openly is what stops it from being mistaken for a mechanism.", cause: "Starting is cheaper than deciding, and a model tends to start as soon as you let it.", decision: "The approaches that are allowed are ranked before any effort is spent, rather than the first workable one being taken.", failureMode: "Three days into a refactor, the question of whether the refactor was needed comes up for the first time.", kind: "lesson", principle: "For this reason worth is decided before any work begins, and what the work will not do is stated as plainly as what it will.", problem: "Work that skips the question of worth can be done well and still turn out to be unnecessary.", validation: "To check this, read the objective again once the work is done. The result should 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 particular shape, and the shape is what makes it hold. The intent node produces an objective and a ranking, never a simple yes. A ranking needs more than one option, so a plan with only one option has not ranked anything and has not passed the gate. Each option records what it achieves and what it costs, and the chosen one is the option where that difference is largest among those that are allowed at all. An option that would cross a hard limit is not a worse option; it is not an option. Whether a change is allowed is asked again at the ${stage("constrain")} node once the work exists, because a plan that looked acceptable on paper can still produce a change that is not. When rules collide applies the same gate to two rules that meet on one piece of code.`, }, { kind: "text", text: "Stating what the work will not do often matters more than stating what it will. The stated scope of a unit is what its author intended, and its unstated scope is whatever collects around it because nothing ruled it out; the ontology calls that speculative generality. Writing down the nearest thing the change will not do is what lets the next reader turn down the addition that would have made a focused unit into a god object. The same test applies to every surface, record or field a plan proposes: it has to name something that would break without it, not merely something that would read it, and an addition that breaks nothing either way is the problem.", }, { kind: "text", text: "The same task reads differently once worth has been decided. Without it: clean up the config and the checker, they have gotten messy. With it: 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. 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: "When you ask a model for a plan, it usually comes back as a flat list of about ten items, in no order that matters, with no gate between them, and with a checkbox after each one that the model ticks itself. In this method a plan is a directed acyclic graph instead. Its phases pass evidence to each other, its tasks carry contracts, and a finished task is deleted rather than ticked, as list against graph shows. The architecture page claims that a system is a graph, and this section applies the same claim to the work done on the code.", subsections: [ { blocks: [ { application: "In practice, the phases are ordered by what depends on what, and within that by what has to exist before something else can be built on it. A gate between two phases names the evidence the next phase reads before it starts. Every task has a contract with four parts: the file it touches, the evidence that proves it, the verifier that reads that evidence, and the thing it deliberately leaves alone. Severity decides which handler a failure goes to, and never the order of the list.", boundary: "Priority and sprint are labels on a phase. They help decide where attention goes, but they never become the plan's structure, because a plan ordered by urgency hides its dependencies.", cause: "A flat list is the cheapest structure to write and the cheapest to tick, which is why the model and the developer both reach for it.", decision: "A plan with no dependency order and no gates is sent back rather than started.", failureMode: "Item four depends on item seven, but the model works through them in list order, and the plan reaches the end with three items quietly left undone.", kind: "lesson", principle: "For this reason I treat a plan as a set of phases with gates between them, not as a list of tasks.", problem: "A task turned straight into a flat checklist has no order and no gates, so the ticks on it say nothing about whether the work is done.", validation: "To check this, ask what each phase needs from the one before it. A phase that needs nothing from its predecessor is either in the wrong place or in the wrong plan.", }, { kind: "text", text: "The two orderings in that practice are dependency and genesis, applied in that sequence. Under dependency, a phase comes after every phase whose output it reads. Genesis is the order in which things come into being: a thing exists, it is told apart from other things, it is related to them, it is structured, it is transformed, and it is constrained. A phase should never depend on something that comes later in that order than what it produces. A plan that builds a transformation on a structure that does not exist yet is inverted, and that is a fault in the decomposition, not a tie to settle.", }, { kind: "text", text: "Impact analysis records names, never counts. A row saying three files are affected gives the reader nothing to act on, while the three file names do. When a dimension has no impact, the row records the evidence that it was checked and found empty, because a blank cell looks the same whether it was checked or skipped, and only the checked one is safe. Every task has a unique id, and every mention of an id has to point to a task that exists, so a dependency note cannot keep pointing at a deleted task while still looking current.", }, { kind: "text", text: "The plan holds what is true now and what is left to do, and nothing else. It holds no findings about defects already fixed, no account of how the plan came about, no inventory of what already exists, and no finished task kept in place with a note. A finished task is deleted, which keeps the remaining tasks equal to the remaining work, and past work left on a checklist invites doing it a second time. The planning templates on the grammar page are built in stages and trimmed by deletion for the same reason. A count written into the plan is written state that goes stale, as derived state explains.", }, { 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 in this method is produced by running a template against the task, as shown in draft, compare, restructure, rather than by writing a document that copies the template's headings. The template works like a program. It walks the ten nodes of the loop and asks its questions in a fixed order, from worth through admissibility and evidence to termination, and it produces the artifact the loop ends on. Each node is typed as shown in a node contract, and the resulting plan has the shape shown in a plan's shape. There is one template for each genesis question, as shown in one per question. The grammar page publishes the template families used here, and core templates states the rule they all follow: a template carries the contract, never the content.", subsections: [ { blocks: [ { application: "In practice, the first plan is drafted from the task and then compared with the template node by node and gate by gate, with the draft treated as raw material for the restructure. Only current and future work stays in the result, and a task is deleted as soon as it is finished.", boundary: "The full loop applies only to an artifact that is executed. A reference, a specification, a contract or a note describes something rather than runs, and forcing the loop onto it fits it to a shape it does not have.", cause: "This happens because a template copied for its shape gives the look of rigour without any of its questions being answered.", decision: "When the draft and the template disagree, the draft is restructured to fit the template rather than defended.", failureMode: "It can have every right heading and none of the right answers, and the reader still trusts it because of the headings.", kind: "lesson", principle: "For this reason, when a shape recurs I turn it into a template, and I run the template as a procedure rather than copying it.", problem: "A plan that copies a template's headings gets none of the guarantees the template was written to give.", validation: "To check this, read the plan for its answers rather than its headings, and ask of each heading whether the decision under it could have gone the other way.", }, { kind: "text", text: "The restructure adds what the draft is missing: the ranking asked for in worth before work, the ordering asked for in the plan is a graph, an evidence contract on every material claim, and explicit termination. Each evidence contract names what would refute the claim and carries a confidence at or above the threshold, and finding no contradiction does not count as support. Termination requires saturation, completion and verification together, so a feeling that the work is finished does not end it.", }, { kind: "text", text: "Each template answers one genesis question, and a template is chosen by the question the work raises. The question of how anything comes to be leads to a plan, a checklist or a task set. How a verdict comes to be leads to an audit or a context check, and how a base abstraction comes to be leads to a shared pattern drawn from repeated evidence. How an agent comes to be leads to a reusable investigator, built from the agent templates on the grammar page. How a template comes to be leads to a template drawn from a document that has already been executed. When two templates could apply, the artifact the work ends on decides between them, and when none applies, I say so rather than force one to fit.", }, { kind: "text", text: "The time to write a template is when a shape appears for the second time. A single instance is only an artifact, but a second one makes a shape, and unless the second is written from a template, the shape ends up written twice. When the developer or the model reads a sibling file to learn the format, they pick up that sibling's accidents as though they were rules. The template therefore carries the constraint and never the content of one instance, and the checks read their contracts from it, as described in the drop-in. Each template also spells out its whole structure. This is the one place where I duplicate on purpose, because the shared structure is what lets each template run on its own, and moving it into an import would take that away from all of them.", }, { kind: "text", text: "A template's loop, types and gates name no domain, so they carry over to any tree unchanged. Its catalogues are worked out again against what exists there, which is the rule the drop-in states for every core. I also keep the gates that run while an artifact is produced apart from the gates that run when it executes, because an artifact that passed its generation gates has not yet passed its execution gates.", }, { kind: "text", text: "Every node of a template carries the same contract, and that contract is what lets a template run as a program rather than be read as a document. A node declares its layer, the mathematical shape its decision yields, the input it reads, which is only the previous node's output, the transformation it applies, the constraints stated at that step, its output, and one handoff gate that carries evidence. The gate in turn names its checks and the evidence each one reads, the node it passes to, and the earliest node a failure is sent back to, with a limit on how far back that can be. Because the yields type is a discriminated union, a gate that owes a ranking cannot be satisfied by a boolean, and the compiler reports the mismatch. The four gates that can never be skipped are a closed subset of the node names rather than a convention the reader has to remember. As a result, a template can be checked by walking its own declarations, and 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]; ```