create-pathfinder 4.2.0 → 4.3.0

package/skills/render-artifact/engine/references/specification.md

@@ -0,0 +1,149 @@
+# The specification
+
+One shared contract, and one kind-specific schema selected by `kind`.
+
+Everything here is producer-supplied *content*. Nothing here is presentation.
+If you find yourself wanting a field for a colour, a class, a width, a
+coordinate, an icon, a template, or a theme, the answer is that the renderer
+owns it — and the schema will reject the field rather than ignore it, so the
+attempt fails loudly instead of silently doing nothing.
+
+## The shared contract
+
+`schemas/common.schema.json`.
+
+| Field | Required | What it is |
+| --- | --- | --- |
+| `schema_version` | yes | `"1.0"`. The contract this specification is written against. |
+| `kind` | yes | Selects the kind schema and the renderer. `lesson` and `diagram`. |
+| `artifact` | yes | Metadata about the artifact: `title`, and optionally `subtitle`, `summary`, `locale`. |
+| `source` | see below | Where the claims come from: `repo`, `commit`, and optionally `generated_at`. |
+
+`source` is required by the `lesson` kind unconditionally. For `diagram` it is
+conditional on `provenance`, and the condition is written into
+`diagram.schema.json` rather than into the shared contract — see
+[`provenance`](#provenance) below. The shared `source` definition itself is
+unchanged and is not loosened: a kind that declares a source declares a complete
+one.
+
+### `provenance`
+
+`diagram` only. `"derived"` or `"proposed"`, and required — there is no default,
+because a diagram that did not say would have a trust level assigned to it by the
+engine.
+
+- **`derived`** maps what the repository asserts about itself at the declared
+  commit. `source` is required, every node and edge carries at least one
+  citation, a group, path or view carrying `summary` or `note` prose carries one
+  too, and `artifact.summary` is not permitted.
+- **`proposed`** describes an intended system. Citations are optional, and every
+  one supplied is still resolved. With no `source` at all, citations are refused
+  rather than ignored, and the evidence layer is reported as not run.
+
+`validation.md` has the full table and the diagnostics. The short version: what
+you may assert is decided by what you are willing to cite, and the renderer's
+wording follows from that rather than from anything you can ask for.
+
+### `source`
+
+- `repo` identifies the repository the evidence belongs to, so a diagnostic can
+  say whose commit is missing.
+- `commit` is a full or abbreviated Git object name. **Evidence resolves
+  against this and nothing else** — never the working tree.
+- `generated_at` is optional, supplied by the producer, and part of the
+  deterministic input. The renderer never reads a clock, so if a timestamp
+  appears in an artifact, it came from here.
+
+There is no `theme`, no `theme_default`, and no presentation default of any
+kind. Those belong to the renderer, and the reader's own preference beats both.
+
+### Evidence
+
+One citation shape, used identically wherever evidence appears, in this kind and
+every kind that follows:
+
+```json
+{ "path": "packages/create-pathfinder/src/kit.mjs", "lines": [97, 105] }
+```
+
+- `path` — repository-relative, forward-slashed. Never absolute.
+- `lines` — optional inclusive `[start, end]`, 1-based, and must lie within that
+  file at the resolved commit.
+- `commit` — optional, overrides `source.commit` for this citation alone. Use it
+  when one claim is about a different point in history, not to work around a
+  citation that will not resolve.
+
+## The `lesson` kind
+
+`schemas/lesson.schema.json`.
+
+```
+lesson
+  objectives?  string[]
+  modules      module[]        one or many — nothing branches on the count
+```
+
+`learn-feature` supplies one module. `learn-codebase` supplies many. There is no
+consumer-specific field, no mode flag, and no escape hatch: the same fields
+serve both, and a change made to suit one has to be justified for the other.
+
+### Module
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `id` | yes | Lowercase, digits and hyphens. Becomes a link target, so it is unique across the artifact. |
+| `title` | yes | |
+| `summary` | no | |
+| `requires` | no | Module ids this builds on. Edges must resolve and must not cycle. A flat list with no edges is legal, and is the single-module case. |
+| `sections` | yes | At least one. |
+
+### Sections
+
+Discriminated by `type`.
+
+**`prose`** — `body` paragraphs. For explanation that carries no claim needing
+a citation.
+
+**`concept`** — `title`, `body`, and `evidence`. A claim about the source.
+`evidence` is required and must be non-empty; a concept citing nothing fails the
+evidence layer, because an uncited claim is the renderer asserting domain
+content, which it must never do.
+
+**`code`** — `language`, `lines`, optional `title`, `caption`, `first_line`, and
+`evidence`. Lines are emitted verbatim and escaped. `language` labels the
+excerpt for the reader; it selects no highlighter, because highlighting is
+either a dependency or a hand-rolled tokeniser and both are the renderer
+starting to interpret content it was handed literally.
+
+**`flow`** — `title` and `steps`. Each step has `id`, `title`, and optionally
+`detail`, `next`, `evidence`. The first step is the entry. `next` is optional
+and defaults to the following step, which is what a linear flow means without
+saying so. Every step must be reachable from the first, and the graph must be
+acyclic.
+
+**`quiz`** — `questions`, each with `id`, `prompt`, `options` (2–8, distinct),
+`answer` (an index into that question's own options), and optionally
+`explanation` and `evidence`.
+
+**`exercise`** — `title`, `body`, and optionally `hints` and `evidence`.
+
+## What a producer cannot assert
+
+There is no field for whether the specification was validated, whether its
+evidence checked out, or whether the artifact is trustworthy. Those are claims
+about work the engine performs, and the engine is the only thing entitled to
+make them — see the verification section of `validation.md`.
+
+Nor is there a field for the *wording* of those claims. The three provenance
+sentences are the renderer's, and a producer cannot select one, soften one, or
+request one it has not earned. `provenance` is not an exception: it declares what
+kind of claim the diagram is making and thereby what will be *required* of it. A
+producer choosing `derived` is choosing the stricter rules, not choosing the
+stronger sentence.
+
+## Text is text
+
+No field is Markdown and no field is HTML. Every producer string is escaped on
+the way out, so `<b>bold</b>` in a title renders as those nine characters,
+visibly. That is the boundary working: content that smuggles markup is a
+producer reaching for presentation by another route.

package/skills/render-artifact/engine/references/validation.md

@@ -0,0 +1,268 @@
+# Validation and delivery
+
+Four layers. Each supports a different claim, each is reported separately, and
+none of them is a warning.
+
+```
+structural   the specification satisfies its schema
+composition  identifiers, references, graphs and answers are coherent
+evidence     every citation resolves at the declared commit
+delivery     the artifact was rendered, digested, and committed atomically
+```
+
+Structural runs first and alone: composition and evidence assume a specification
+that already has the right shape, so if structural fails they do not run and the
+report says so rather than showing them as passing. Composition and evidence are
+independent of each other and run together, so one round trip surfaces both.
+
+A layer can also be **not run because it does not apply**, which is reported
+distinctly from both a pass and a skip. A `diagram` declaring no source has no
+evidence layer: there is no commit to resolve against, and the structural layer
+has already refused any citation in it, so there is provably nothing to check.
+The report says `~ evidence: not run` and gives the reason.
+
+That distinction is the whole point of keeping it. Reporting such a layer as
+`ok evidence` would put the strongest word in the report against the weakest
+claim in it, and a reader skimming four green lines would conclude the citations
+had been verified when there were none.
+
+## Commands
+
+```sh
+node engine/bin/render.mjs validate <spec.json> [--repo <dir>] [--json]
+node engine/bin/render.mjs deliver  <spec.json> <out.html> [--repo <dir>] [--json]
+node engine/bin/render.mjs doctor   [--json]
+```
+
+`--repo` names the repository whose history evidence resolves in. It defaults to
+the specification's own directory, which is right when the specification lives
+in the repository it cites, and is exactly what needs overriding when it does
+not.
+
+Exit codes are the contract:
+
+| Code | Meaning |
+| --- | --- |
+| 0 | every layer that ran passed, and the artifact was committed |
+| 1 | a layer failed; nothing was committed |
+| 2 | the command line was wrong |
+
+A non-zero exit is never reported as success.
+
+## Structural
+
+Schema validation, plus two refusals that come before it:
+
+| Code | Meaning |
+| --- | --- |
+| `schema_version_unsupported` | the specification is written against a contract this engine does not implement |
+| `kind_unsupported` | no such artifact kind. Refused — not a reason to improvise HTML |
+| `presentation_control` | a field like `color`, `css`, `class`, `layout` or `theme`. Rejected, never ignored |
+| `unknown_field` | a field this contract does not have |
+| `missing_field` | a required field is absent |
+| `schema_*` | one keyword rejected one value; the message names both |
+| `topology_unsupported` | a `diagram` asked for a layout this renderer does not have |
+| `label_too_long` | a label is wider than its column cap. Refused, never shortened |
+| `source_required_for_derived` | a `derived` diagram does not say which repository or which commit it was derived from |
+| `citation_without_source` | a specification with no source carries a citation. There is nothing to resolve it against |
+| `artifact_summary_forbidden` | a `derived` diagram carries `artifact.summary`, which is the one claim-bearing prose with nowhere to put a citation |
+
+The last three are the provenance contract's structural half — see
+**Provenance** below.
+
+`presentation_control` and `unknown_field` have the same *outcome* —
+`additionalProperties: false` rejects either. They differ in the diagnostic,
+because a producer who wrote `"color"` believed presentation was theirs to set,
+and the error should say so instead of talking about arrays and properties.
+
+## Composition
+
+| Code | Meaning |
+| --- | --- |
+| `duplicate_identifier` | two modules or sections share an id; identifiers become link targets |
+| `duplicate_step_identifier` | two steps of one flow share an id |
+| `duplicate_question_identifier` | two questions of one quiz share an id |
+| `unresolved_reference` | a `requires` or `next` names something that does not exist |
+| `graph_cycle` | a module or flow graph leads back to itself |
+| `orphan_step` | a flow step is unreachable from the flow's first step |
+| `orphan_module` | a module is unreachable from every module without prerequisites |
+| `answer_out_of_range` | a quiz answer does not index its own options |
+| `module_empty` | a module carries no sections |
+
+Note what "orphan" means for modules. With no `requires` anywhere, every module
+is a root and nothing is orphaned — a flat list is a legal graph, and that is
+the single-module case, which must stay legal. Orphans only become possible once
+edges exist.
+
+## Evidence
+
+Resolved against the commit, using local Git. Nothing is fetched, cloned, or
+looked up over a network: a commit that is not present locally is a commit whose
+evidence was not verified, and the engine says so rather than going to find one.
+
+| Code | Meaning |
+| --- | --- |
+| `source_commit_unavailable` | the declared commit cannot be resolved here — wrong repository, unfetched commit, or no repository at all |
+| `evidence_path_absent` | the commit resolves; the file is not in it |
+| `evidence_range_invalid` | the file is there; the cited lines are not |
+| `concept_without_evidence` | a concept cites nothing |
+| `node_without_evidence` | a `derived` diagram says a component exists and cites nothing for it |
+| `edge_without_evidence` | a `derived` diagram asserts a relationship and cites nothing for it |
+| `claim_without_evidence` | a `derived` group, path or view carries `summary` or `note` prose with no citation |
+
+The first three stay apart because they mean three different things to the
+person reading them: a stale fixture, a moved file, and a shifted range are
+three different fixes.
+
+None of them downgrades to a skip. An engine that shrugged at an unresolvable
+commit would deliver an artifact whose provenance block claims its evidence was
+verified when nothing was.
+
+### What this layer establishes, and what it does not
+
+That the cited file exists at the declared commit, that the cited line range
+exists in it, and that the material is there to be read.
+
+Not that the claim resting on it is true.
+
+Repository documentation — a README, an ADR, a runbook — is first-class citation
+material and is checked exactly the same way. That is not a statement that
+documentation carries the same authority as the code it describes; it is a
+statement that the engine can tell you where to look and cannot tell you whether
+what you find is right.
+
+**Pathfinder verifies provenance, not truth.** No diagnostic and no word in any
+artifact may imply otherwise.
+
+## Provenance
+
+A `diagram` declares `provenance`, and it decides how strictly the diagram is
+checked. There is no default: a diagram that did not say would have a trust level
+assigned to it by the engine, and the engine has no business guessing which claim
+its producer meant to make.
+
+| | `derived` | `proposed`, with source | `proposed`, no source |
+| --- | --- | --- | --- |
+| `source` | required | permitted | absent |
+| citations | required on every node and edge | optional | **refused** |
+| claim-bearing group, path or view | must cite | optional | **refused** |
+| label-only group, path or view | needs nothing | needs nothing | needs nothing |
+| `artifact.summary` | refused | permitted | permitted |
+| evidence layer | runs | runs | not run, with the reason |
+
+A `derived` diagram maps what the repository asserts about itself at the declared
+commit, so there is no uncited derived fact. A node says a component exists and
+an edge says two things relate; each is a claim a reader must be able to go and
+check. Evidence is *where a reader goes to check an assertion*, which is not
+always the code implementing it — an actor is cited by the entry point that
+accepts it, an external system by its client or its configuration, a subsystem by
+its manifest or entry module.
+
+A component that appears nowhere in source, configuration, infrastructure or
+repository documentation is not eligible for a `derived` diagram at all. A
+diagram that needs it is `proposed`.
+
+A group, path or view is the one narrower case. Its label is a name, and a name
+asserts nothing its already-cited members do not. Its `summary` or `note` is
+prose making a further claim, and that is what needs backing.
+
+`lesson` has no `provenance` field and is unaffected by any of it. `source`
+remains unconditionally required there: the conditional lives in the diagram
+schema, not in the shared contract, precisely so that making one kind's source
+optional did not make every kind's provenance optional.
+
+## Delivery
+
+Delivery takes the specification as **bytes** and nothing else. It copies them,
+parses that copy, validates the parsed value, renders that same value, and
+reports the digest of those same bytes. There is no parameter through which a
+caller could supply a specification object alongside unrelated bytes, because a
+receipt that described a specification nobody rendered would be undetectable
+downstream.
+
+Rendering then runs against a deep-frozen copy, so a renderer that mutated its
+own input would throw rather than quietly produce output nobody can reproduce
+from the file on disk.
+
+### Verification is earned, not asserted
+
+An artifact carries a sentence saying its evidence was checked against the named
+commit. It carries that sentence only when **both** of these are true:
+
+1. this engine validated the specification and the validation passed, and
+2. at least one citation actually resolved.
+
+The second condition is the guard against a vacuous claim. A specification
+carrying no citations passes the evidence layer by having nothing to fail, and an
+artifact saying "every citation above was verified against the commit named here"
+on the strength of that would be a stronger statement than anybody made — with
+no citation above, and sometimes a commit that does not exist. Nothing to check
+is not the same as everything checking out.
+
+So a `proposed` diagram with a source and no citations gets no sentence, and
+neither does a lesson that cites nothing. Both are still valid, and both still
+deliver; what they do not get is credit for a check that had no subject.
+
+#### The three wordings
+
+Renderer-owned, and different in each state because each supports a different
+claim. **No field in any specification selects, softens, or requests one.** They
+live in the shared shell rather than in a kind renderer because they describe
+what the *engine* did, which is the same whatever kind rendered into it.
+
+| State | What the artifact says |
+| --- | --- |
+| `derived` | the schema, references and graphs checked out, and every component, relationship and claim carried a citation verified at the declared commit. Explicitly **not** a finding that the architecture drawn is correct or complete |
+| `proposed`, source, ≥1 resolved citation | the citations supplied were verified at the declared commit, and explicitly **do not** establish that the system drawn exists |
+| `proposed`, source, no citations | nothing |
+| `proposed`, no source | no verification sentence. Instead: that the diagram describes an intended system, names no repository or commit, and makes no claim about what currently exists |
+| `lesson` | unchanged from what it has always said |
+
+A source-less artifact also carries **no repository row, no commit row and no
+timestamp**. None of them is invented from the working directory, the
+environment, or a clock: there is no honest value, and a plausible one would be
+worse than none, because it would read as provenance.
+
+`render()` is a public export and does not validate. Called directly it emits
+the provenance rows and **no verification language at all** — not "unverified",
+not a placeholder, nothing. An artifact that cannot vouch for itself says
+nothing on the subject, and the absence of the sentence is the signal; saying
+"unverified" would still be the renderer making a claim about a process it did
+not observe.
+
+The claim is gated on an attestation, which only `verification.attest()` mints,
+and only from a validation result this engine branded on the way past. The brand
+is a module-private symbol — not `Symbol.for`, not a string key — so a
+hand-built `{ ok: true }` is refused. `deliver()` validates and mints one
+itself.
+
+There is no producer-facing counterpart, and there must never be one. No
+`verified`, no `validation_status`, no field of any name in the specification
+can influence this. A producer asserting that its own work was checked is
+exactly the claim this design exists to make impossible.
+
+The artifact is written to a temporary file beside the destination, flushed with
+`fsync`, and renamed over it. A rename within a directory is atomic, so a reader
+never sees a half-written page. The `fsync` matters as much as the rename:
+without it the rename can be durable while the content behind it is not, which
+is how a crash leaves a correctly named, empty artifact.
+
+A failure at any point leaves a previously delivered artifact exactly as it was.
+
+| Code | Meaning |
+| --- | --- |
+| `render_failed` | rendering threw; nothing was written |
+| `carriage_return_in_output` | output contains `\r`; artifacts use `\n` only |
+| `byte_order_mark_in_output` | output begins with a BOM; artifacts are UTF-8 without one |
+| `commit_failed` | the artifact could not be written or renamed |
+
+The receipt names the renderer version and the SHA-256 and byte count of both
+the specification and the artifact.
+
+## What a green result is not
+
+It is not a judgement that the artifact looks right. Nobody has looked at it.
+
+Report the two separately, always. A human opening the artifact in a browser is
+a different kind of evidence about a different question, and neither result
+supports the other.

package/skills/render-artifact/engine/render/behavior.mjs

@@ -0,0 +1,128 @@
+/**
+ * The artifact's inline behaviour: theme choice, navigation position, and quiz
+ * feedback.
+ *
+ * All three are enhancements. With scripting off the artifact is still a
+ * complete, readable, keyboard-navigable document: the theme follows the
+ * reader's system through `prefers-color-scheme`, navigation is a list of
+ * ordinary anchors, and every quiz answer is already reachable inside a
+ * `<details>`. Nothing here is load-bearing, which is what lets the artifact
+ * open from `file://` with no network, no server, and no build step.
+ *
+ * Storage is wrapped: `localStorage` throws outright in some `file://` and
+ * private-window configurations, and a theme preference is not worth a page
+ * that fails to run.
+ */
+
+export const BEHAVIOR_JS = `
+(function () {
+  "use strict";
+
+  var root = document.documentElement;
+  var MODES = ["auto", "light", "dark"];
+  var LABELS = { auto: "Theme: auto", light: "Theme: light", dark: "Theme: dark" };
+  var KEY = "pathfinder.artifact.theme";
+
+  function stored() {
+    try {
+      var value = window.localStorage.getItem(KEY);
+      return MODES.indexOf(value) >= 0 ? value : null;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  function remember(mode) {
+    try {
+      window.localStorage.setItem(KEY, mode);
+    } catch (error) {
+      /* A reader who cannot store a preference still gets to use it. */
+    }
+  }
+
+  function apply(mode, button) {
+    root.setAttribute("data-pf-theme", mode);
+    if (button) {
+      button.textContent = LABELS[mode];
+      button.setAttribute("aria-label", LABELS[mode] + ". Activate to change.");
+    }
+  }
+
+  var toggle = document.getElementById("pf-theme-toggle");
+  var initial = stored() || "auto";
+  apply(initial, toggle);
+
+  if (toggle) {
+    toggle.hidden = false;
+    toggle.addEventListener("click", function () {
+      var next = MODES[(MODES.indexOf(root.getAttribute("data-pf-theme")) + 1) % MODES.length];
+      apply(next, toggle);
+      remember(next);
+    });
+  }
+
+  /* Mark the module the reader is in. Falls back to doing nothing where
+     IntersectionObserver is unavailable; the nav still navigates. */
+  var links = Array.prototype.slice.call(document.querySelectorAll("[data-pf-nav]"));
+  if (links.length > 0 && "IntersectionObserver" in window) {
+    var byId = {};
+    links.forEach(function (link) { byId[link.getAttribute("data-pf-nav")] = link; });
+
+    var visible = {};
+    var observer = new IntersectionObserver(function (entries) {
+      entries.forEach(function (entry) {
+        visible[entry.target.id] = entry.isIntersecting;
+      });
+      var current = null;
+      for (var i = 0; i < links.length; i += 1) {
+        var id = links[i].getAttribute("data-pf-nav");
+        if (visible[id]) { current = id; break; }
+      }
+      links.forEach(function (link) {
+        var isCurrent = link.getAttribute("data-pf-nav") === current;
+        if (isCurrent) {
+          link.setAttribute("aria-current", "true");
+        } else {
+          link.removeAttribute("aria-current");
+        }
+      });
+    }, { rootMargin: "-30% 0px -60% 0px" });
+
+    Object.keys(byId).forEach(function (id) {
+      var target = document.getElementById(id);
+      if (target) observer.observe(target);
+    });
+  }
+
+  /* Quiz feedback. The correct answer is in the document either way; choosing
+     an option just says so sooner, and opens the explanation that was always
+     one click away. */
+  document.addEventListener("change", function (event) {
+    var input = event.target;
+    if (!input || input.type !== "radio" || !input.hasAttribute("data-pf-answer")) return;
+
+    var question = input.closest("[data-pf-question]");
+    if (!question) return;
+
+    var chosenIsCorrect = input.getAttribute("data-pf-answer") === "correct";
+    Array.prototype.forEach.call(question.querySelectorAll(".pf-option"), function (option) {
+      var field = option.querySelector("input[type=radio]");
+      var verdict = option.querySelector(".pf-verdict");
+      var correct = field.getAttribute("data-pf-answer") === "correct";
+      if (field.checked && !correct) {
+        option.setAttribute("data-pf-verdict", "incorrect");
+        if (verdict) verdict.textContent = "Not this one";
+      } else if (correct && (field.checked || !chosenIsCorrect)) {
+        option.setAttribute("data-pf-verdict", "correct");
+        if (verdict) verdict.textContent = "Correct";
+      } else {
+        option.removeAttribute("data-pf-verdict");
+        if (verdict) verdict.textContent = "";
+      }
+    });
+
+    var reveal = question.querySelector(".pf-reveal");
+    if (reveal) reveal.open = true;
+  });
+})();
+`.trim();