@kidlat-dakila/flightplan 0.1.6 → 0.1.8

package/backend/configurations/system-instructions/artifactFormat.md

@@ -20,9 +20,9 @@ diff marks. The reviewer is already reading it while you write.
 | You write | Flight Plan already set |
 |---|---|
 | A segment's title and its context | The title, copied from the change |
-| A File Section's title and summary, and the order of the File Sections | Which files have a section, and their paths |
-| A waypoint's title, reading, needs-attention note and findings | Which waypoints exist, the declaration each is about, and its lines |
-| A Journey Flow Diagram's description, a node's label and description, and the label of each of its trigger labels | Which nodes exist, how they connect, which node is inside which, and which trigger labels a node has |
+| | Which files have a section, their paths and their order |
+| A waypoint's title, reading, core-change note and findings | Which waypoints exist, the declaration each is about, and its lines |
+| A Trace Diagram's description, a node's label and description, and the label of each of its trigger labels | Which nodes exist, how they connect, which node is inside which, and which trigger labels a node has |
 | A Blast Diagram file's impact type and impact reason, on a file the change did not touch | Which files exist, which the change touched and how they import each other |
 | A context code block's description, where the block is required | Which code blocks are listed, and which are required |
 | A `code:` link in a sentence | The code a link shows, and every diff mark |
@@ -31,6 +31,16 @@ diff marks. The reviewer is already reading it while you write.
 So: **you change words, never structure.** No tool can add, remove or reparent a
 file, a waypoint or a node, and no tool takes a line number for a waypoint.
 
+## What this review asks you to write
+
+Each node says whether this review asks you to write it: `isRequired` on a
+waypoint, a Trace Diagram node, a Trace Diagram (its description) and a Blast
+Diagram file, and `isContextRequired` on a segment (its title and context).
+Write only the nodes marked `true`. A write to any other node is refused.
+`nodes` lists only the work on required nodes, and `complete` succeeds once
+every required node is written. The reviewer can ask for more later; those
+nodes are then marked required, and Flight Plan tells you.
+
 ## The shape
 
 ```jsonc
@@ -43,11 +53,10 @@ file, a waypoint or a node, and no tool takes a line number for a waypoint.
       "id": "3f9a1c2e",
       "title": "<a very short text of the context>",
       "context": "<Markdown>",
-      "journey": { "description": "…", "nodes": [...], "edges": [...] }, // or null when the segment has none
-      "blast": { "nodes": [...], "edges": [...], "importBound": { "nodes": [...], "edges": [...] } },   // or null when the segment has none
+      "traceDiagram": { "description": "…", "nodes": [...], "edges": [...] }, // or null when the segment has none
+      "blastDiagram": { "nodes": [...], "edges": [...], "importBound": { "nodes": [...], "edges": [...] } },   // or null when the segment has none
       "walkthrough": {
-        "intro": "…",
-        "files": [{ "path": "…", "title": "…", "summary": ["…"], "waypoints": [...] }]
+        "files": [{ "path": "…", "waypoints": [...] }]
       }
     }
   ],
@@ -73,7 +82,7 @@ names a `segmentId`, and any segment of the artifact will do.
 | `get-instructions` | How to write each field, for the configuration the reviewer chose |
 | `read` | One part of the artifact: `overview` to get oriented, `diff` for the change |
 | `nodes` | What is still unwritten, each piece with the code it covers |
-| `update-nodes` | Every word you write, on one segment, in one batch: its title, context, intro, file order and Journey Flow Diagram description by name, and its waypoints, File Sections, diagram nodes and context code blocks by id. Answers with how many nodes are complete and how many are not |
+| `update-nodes` | Every word you write, on one segment, in one batch: its title, context and Trace Diagram description by name, and its waypoints, diagram nodes and context code blocks by id. Answers with how many nodes are complete and how many are not |
 | `complete` | Says the artifact is finished, and checks it |
 
 ## What is refused
@@ -81,10 +90,6 @@ names a `segmentId`, and any segment of the artifact will do.
 A refused write changes nothing. A batch is all or nothing: one bad entry writes
 none of it, and the refusal names the entry.
 
-- Anything of a section the reviewer chose not to generate: a Journey Flow
-  Diagram node or description, a Blast Diagram file, a finding. `get-instructions`
-  with no fields says which sections are on. A section that is off is not asked
-  of you on `complete` either.
 - An id or a path the artifact does not have.
 - A `segmentId` the artifact does not have, or an id that is not in the segment
   the call names.
@@ -93,11 +98,10 @@ none of it, and the refusal names the entry.
 - A `question` carrying a trace or a solution.
 - An `impactType` or an `impactReason` on a file of the change.
 - A `breaks` or a `behaviour-changes` with no `impactReason`, or an `impactReason` on an `unaffected` file.
-- A file order that does not name every File Section exactly once.
-- A `journeyDescription` on a segment that has no Journey Flow Diagram.
+- A `traceDiagramDescription` on a segment that has no Trace Diagram.
 - A `position` on a nested waypoint, past the end of its file, or given to two
   waypoints of one file.
-- On `complete`: an empty context, a segment with no title, a File Section still titled with its path, a
-  waypoint with no title or no reading, a Journey Flow Diagram with no description, a Journey Flow Diagram node or one of its trigger labels with no
+- On `complete`: an empty context, a segment with no title, a
+  waypoint with no title or no reading, a Trace Diagram with no description, a Trace Diagram node or one of its trigger labels with no
   label, a file the change reaches that nobody assessed, or a `bug`, `risk` or
   `nit` with no solution.

package/backend/configurations/system-instructions/{blast.md → blastDiagram.md}

@@ -1,8 +1,8 @@
 The Blast Diagram: the files the change is connected to through imports. A
-segment's `blast` is an object with `nodes` and `edges`, or `null` when the
+segment's `blastDiagram` is an object with `nodes` and `edges`, or `null` when the
 segment has no diagram.
 
-It answers a different question from the Journey Flow Diagram. The journey is a
+It answers a different question from the Trace Diagram. The trace is a
 **trace**: one path through the change, in the order the code runs. The blast is
 **reach**: every file that uses what changed in a changed file, directly or
 through other files.
@@ -11,7 +11,7 @@ It exists for one question the reviewer cannot answer from the diff: **did the
 author forget something?** A file nobody touched can stop working, or start
 doing something else, because of what changed under it.
 
-A `blast` can also hold `importBound`, with `nodes` and `edges` of its own: the
+A `blastDiagram` can also hold `importBound`, with `nodes` and `edges` of its own: the
 files the change uses, and the files those use. It is the other direction of
 the same diagram. Read it to see what the change relies on. Write nothing in
 it: a file the change uses cannot be affected by the change.
@@ -30,8 +30,8 @@ You write two fields, only on a file the change did not touch:
 | `impactType` | What the change does to this file: `breaks`, `behaviour-changes` or `unaffected`. |
 | `impactReason` | On `breaks` and `behaviour-changes` only: why, in one or two sentences a reviewer can check against the code. |
 
-Write them with `update-nodes { segmentId, blast: [{ path, impactType, impactReason }] }`,
-and an unaffected file with `update-nodes { segmentId, blast: [{ path, impactType: "unaffected" }] }`.
+Write them with `update-nodes { segmentId, blastDiagram: [{ path, impactType, impactReason }] }`,
+and an unaffected file with `update-nodes { segmentId, blastDiagram: [{ path, impactType: "unaffected" }] }`.
 A file of the change takes neither: it is the change.
 
 An unaffected file takes no reason. The page says the same sentence for every

package/backend/configurations/system-instructions/context.md

@@ -1,22 +1,31 @@
 The Context Section, the first thing a reviewer reads, before any code: one
-string of Markdown. It says what the change is about and why it matters, what
-changes from outside the code, and what changed inside it. How it is laid out is
-the configuration's to say.
+string of Markdown per segment. It says what the segment's change does. What
+changed in the segment's files is Flight Plan's to show: the Change Overview
+under the context lists every piece of code the segment adds, modifies and
+removes. How the context is laid out is the configuration's to say.
 
 Write it with `update-nodes { segmentId, context }`. Writing it replaces the whole
-string, and a finished artifact has one that is not empty.
+string of that segment, and a finished artifact has one that is not empty in
+every segment whose context is required.
+
+When the reviewer turned segments off, the page shows the whole change as one
+segment, and only the first segment's context is required. It is the one
+Context the reviewer reads, so it covers every segment's change.
 
 ## The Markdown that is shown
 
 | Written | Shown as |
 |---|---|
-| `## Heading` | a heading inside the section |
+| `## Heading` or `### Heading` | a heading inside the section |
 | a paragraph | a paragraph |
-| `- item` or `1. item` | a list, one level deep |
+| `- item` or `1. item` | a list, with one level of sub-items |
 | `**bold**` | bold text |
 | `` `code` `` | inline code |
 | `[label](code:path#target)` | a code link |
+| `:::accordion`, then `::section <name>` lines, then `:::` | an accordion, collapsed, one section per `::section` line, each holding the lines under it |
+| `:::tabs`, then `::tab <name>` lines, then `:::` | tabs, one per `::tab` line, each holding the lines under it |
 
-Nothing else is shown: a fenced code block, a table, an image, a quote and a
-list inside a list are dropped or flattened. The section's own heading is
-already there, so the string never opens with one.
+Nothing else is shown: a fenced code block, a table, an image and a quote are
+dropped or flattened. A sub-item holds no list of its own, and neither a section
+nor a tab holds an accordion or tabs. The section's own heading is already there, so the string never
+opens with one.

package/backend/configurations/system-instructions/title.md

@@ -1,8 +1,40 @@
-The segment's title: a very short text of what the segment's `context` is
-about, a few words long. One string, with no code link and no full stop.
+The segment's title: a few words that say what the segment changes. One string,
+with no code link and no full stop. It names what changed and leaves why to the
+`context`.
 
-A segment arrives with no title. Write it with `update-document { segmentId, title }`,
-after the context it sums up, and a finished artifact has one on every segment.
+A segment arrives with no title. Write it with `update-nodes { segmentId, title }`,
+after the context, and a finished artifact has one on every segment. When the
+reviewer turned segments off, no segment is shown, and none needs a title.
 
 The review page shows it as the segment's heading when a change is split into
 several segments, and the section rail lists the segment under it.
+
+## A segment the other segments build on
+
+A segment is groundwork when code in the other segments of the change imports its
+files: the review shows it first because they use it. Its blast and the imports
+of the other segments' files show what uses it. Title it after that code, not
+after its own changes, and write names as the code writes them:
+
+- One or two users: their names. `Groundwork for CreateOrderPage and EditOrderPage`
+- More than two of one kind: the kind in the plural, with `new` when all of them
+  are new. `Groundwork for the new pages`, `Groundwork for the cart components`
+- More than two of different kinds: both kinds. `Groundwork for the new pages and components`
+
+## Any other segment
+
+Say what the segment adds, then what it modifies, then what it removes, as
+`New …`, `modified …` and `removed …` joined by commas. Only the first part
+starts with a capital letter, and a part with nothing in it is left out.
+
+- One thing of a kind: its name as the code writes it, followed by its kind when
+  the name does not already say it. `New EditOrderPage`, `Modified CartSummary component`
+- Two things: both names. `New PromoForm and useApplyPromo, modified CartSummary`
+- More than two of one kind: the kind in the plural. `New pages, modified components`
+
+| The segment | Its title |
+|---|---|
+| Adds one page | `New EditOrderPage` |
+| Adds a component and a hook, and changes a component | `New PromoForm and useApplyPromo, modified CartSummary` |
+| Adds three pages and changes two components | `New pages, modified components` |
+| Deletes a component and changes the one that showed it | `Modified CartSummary, removed Dialog component` |

package/backend/configurations/system-instructions/traceDiagram.description.md

@@ -0,0 +1,14 @@
+The caption of the Trace Diagram, shown above its board: one short paragraph that says what the
+diagram shows before the reviewer follows its lines. Five sentences at most. Required on every segment that has a diagram,
+`null` on arrival, and `complete` refuses an artifact where one is missing.
+
+Written with `update-nodes { segmentId, traceDiagramDescription }`. Writing it
+replaces the one that was there. A segment with `trace: null` has none, and
+a write to it is refused.
+
+`nodes { unfilled: true, needs: ["trace-description"] }` hands it out with
+the diagram's nodes and edges. Write it after the labels of the nodes, so it
+uses the same words as they do.
+
+It is one paragraph of plain sentences. Inline code and a code link are shown.
+A heading, a list and a table are not.

package/backend/configurations/system-instructions/{journey.md → traceDiagram.md}

@@ -1,6 +1,6 @@
-The Journey Flow Diagram: how execution reaches the change, read like a
+The Trace Diagram: how execution reaches the change, read like a
 debugging trace, from the code that starts a path to the changed code. A
-segment's `journey` is an object with a `description`, `nodes` and `edges`, or
+segment's `traceDiagram` is an object with a `description`, `nodes` and `edges`, or
 `null` when the segment has no diagram.
 
 **Flight Plan draws it, and you write the words on it.** The nodes and the edges
@@ -89,7 +89,7 @@ rendered, and it does not say whether the connection is proven or assumed.
 ## What the reviewer sees
 
 - **The description is read first.** It is shown above the board: the
-  diagram told in words, in five sentences at most. Until it is written
+  caption of the diagram, in five sentences at most. Until it is written
   the page says so.
 - **Every edge is the same line, with no label.** Where something about a
   connection matters to the reviewer, such as a prop passed through three
@@ -118,7 +118,7 @@ rendered, and it does not say whether the connection is proven or assumed.
 
 ## What you write
 
-With `update-nodes { segmentId, journey: [{ id, label, description, triggerLabels, blockLabels }] }`:
+With `update-nodes { segmentId, traceDiagram: [{ id, label, description, triggerLabels, blockLabels }] }`:
 
 - `label` — what the step does. Required on every node.
 - `description` — how the node is reached and what it runs next. Not the
@@ -130,15 +130,15 @@ With `update-nodes { segmentId, journey: [{ id, label, description, triggerLabel
 
 A node inside another is written by its own `id`, like any other.
 
-With `update-nodes { segmentId, journeyDescription }`:
+With `update-nodes { segmentId, traceDiagramDescription }`:
 
-- `journeyDescription` — the diagram told in words, in five sentences at
+- `traceDiagramDescription` — the caption of the diagram, in five sentences at
   most. Required on every segment that has a diagram. See
-  `journey.description`.
+  `traceDiagram.description`.
 
 ## When there is no diagram
 
-A segment with `journey: null` has no Journey Flow Diagram, and the page shows
+A segment with `trace: null` has no Trace Diagram, and the page shows
 the heading of the band alone. Flight Plan decides whether a segment has a
 diagram, and no tool changes it. Where a change that runs code has none, tell
 the reviewer with `send-message`.

package/backend/configurations/system-instructions/traceDiagram.nodes.blockLabels.label.md

@@ -0,0 +1,6 @@
+The label of one argument, state, hook, effect, call or step of a node, drawn as a
+row inside the node. It says what that block does in the reader's terms, starting
+with a verb: what the node does with the value, or what the step does. A step is a
+statement with all that is written inside it, or several statements that follow
+each other, listed by the block of the first. Until it is written the row
+shows the name of the code, such as `useApplyPromo`, marked as a draft.

package/backend/configurations/system-instructions/walkthrough.files.md

@@ -1,18 +1,12 @@
 The File Sections of the tour, in reading order: an array of objects, each a
-file `path`, a `title`, its `summary` lines and its `waypoints`.
-
-Write a section's `title` and `summary` with
-`update-nodes { segmentId, files: [{ path, title, summary }] }`. A File Section arrives
-titled with its own path, and `complete` refuses one that still is.
+file `path` and its `waypoints`. A File Section is headed by its path, so it
+has nothing to write.
 
 ## Ordering the files
 
-**Use the order the reviewer chose.** The request that started the review names
-it. Where it leaves a choice, order the files so a reader never meets a name
-before it is defined: the shape that changed first, then the code that uses it,
-then what wires them together, then configuration. What the order can never be
-is alphabetical or diff order by accident: the scaffold lists the files by path,
-so an order nobody wrote is that.
+**Flight Plan orders the files.** It sorts the File Sections by the import graph,
+or puts the reviewer's spotlight and the core changes first, as the reviewer
+chose. Write no order.
 
 **No test file gets a waypoint, and none gets a section.** A tour is a tour of
 the change, and a test is the evidence the change works. Flight Plan sets test

package/backend/configurations/system-instructions/walkthrough.files.waypoints.coreChange.md

@@ -0,0 +1,7 @@
+Where the pull request does its real work: one or two sentences saying why this
+waypoint is the core change of the branch. Optional, and absent on most
+waypoints. It marks importance, not a defect; a defect is a finding.
+
+Its presence is the flag. A waypoint that carries it draws a Core change chip
+beside its title and a Core change note above its reading; a waypoint without it
+draws neither. Write `null` to take one back.

package/backend/configurations/system-instructions/walkthrough.files.waypoints.md

@@ -11,7 +11,7 @@ of one piece of the change, placed on top of its lines.
   "declaration": "hasStock",
   "codeBlockIds": ["src/checkout/hasStock.ts#function@12:1", "src/checkout/hasStock.ts#condition@15:3"],
   "reading": "The author replaced the per-line stock lookup in `hasStock()` with one query for the whole basket, and it now returns every line that falls short, not the first. [`placeOrder()`](code:src/checkout/placeOrder.ts#placeOrder) calls it before it charges the card, so that a customer sees every short item in one refusal.",
-  "needsAttention": "This is the rule the pull request exists for: stock is now checked against one read for the whole basket, and the other waypoints wire it in.",
+  "coreChange": "This is the rule the pull request exists for: stock is now checked against one read for the whole basket, and the other waypoints wire it in.",
   "findings": [],
   "children": []
 }
@@ -25,11 +25,11 @@ of one piece of the change, placed on top of its lines.
 - **`codeBlockIds`** are the blocks of the waypoint: the block it stops at
   first, then the changed blocks inside it, in the order they are written. An
   id names its file, its type and where it starts, as the `codeBlockIds` of a
-  Journey Flow Diagram node do, so the same id is the same block. Flight Plan
+  Trace Diagram node do, so the same id is the same block. Flight Plan
   sets them, and a waypoint in a file it does not trace has none.
 - **`title`** and **`reading`** are yours, and arrive empty. `nodes` hands you
   each waypoint that still needs one, with the code it covers.
-- **`needsAttention`** and **`findings`** are yours, and most waypoints carry
+- **`coreChange`** and **`findings`** are yours, and most waypoints carry
   neither.
 
 **The structure is not yours to change.** Flight Plan makes one waypoint per

package/backend/configurations/system-instructions/walkthrough.md

@@ -1,14 +1,12 @@
-The Code Walkthrough: an object with an optional `intro` that frames the whole
-tour and a `files` array, one File Section per toured file in reading order.
+The Code Walkthrough: an object with a `files` array, one File Section per
+toured file in reading order.
 
 ## Reading order
 
-**A tour reads top to bottom, and so does the code it points at.** File Sections
-in the order the reviewer asked for; inside a file, waypoints in the order the
+**A tour reads top to bottom, and so does the code it points at.** Flight Plan
+orders the File Sections itself, as the reviewer chose, so write no order and do
+not ask the reviewer for one. Inside a file, waypoints come in the order the
 file declares their code.
 
-The order of the File Sections is the reviewer's choice, and it reaches you in
-the request that started the review. Apply it with
-`update-nodes { segmentId, order: { files: [...] } }`, naming every File Section exactly
-once. Inside one file, `update-nodes { segmentId, waypoints: [{ id, position }] }` moves a
+Inside one file, `update-nodes { segmentId, waypoints: [{ id, position }] }` moves a
 top-level waypoint among its siblings, and is rarely needed.