ahead-pi 0.2.0 → 0.2.1

package/generated/reference/index.json

@@ -0,0 +1,180 @@
+{
+  "generated_from": [
+    "CONSTITUTION.md",
+    "docs/acceptable-ai-use.md",
+    "docs/design/debugging-and-operations.md",
+    "docs/design/executable-workflows.md",
+    "docs/design/process-taxonomy.md",
+    "docs/engineering-practice.md",
+    "docs/evidence/evidence-standard.md",
+    "docs/evidence/research-map.md",
+    "docs/rationale.md",
+    "docs/references/pragmatic-programmer-page-index.md",
+    "docs/references/submitted-engineering-notes.md",
+    "docs/releasing-pi.md",
+    "docs/workflows/README.md",
+    "docs/workflows/corrective-debugging.md",
+    "docs/workflows/decision.md",
+    "docs/workflows/internal-improvement.md",
+    "docs/workflows/investigation.md",
+    "docs/workflows/operational-stabilization.md",
+    "docs/workflows/product-change.md"
+  ],
+  "references": [
+    {
+      "id": "constitution",
+      "path": "CONSTITUTION.md",
+      "title": "AHEAD Constitution",
+      "summary": "This constitution records the durable principles of **Assisted Human Engineering and Development**. Workflows and tools may evolve. These principles define what makes them AHEAD.",
+      "phases": [
+        "*"
+      ]
+    },
+    {
+      "id": "acceptable-ai-use",
+      "path": "docs/acceptable-ai-use.md",
+      "title": "Acceptable AI Use in AHEAD",
+      "summary": "This policy is binding for AHEAD pilot workflows. The [AHEAD Constitution](../CONSTITUTION.md) is the highest authority; this policy interprets its human-ownership boundaries; workflow profiles apply both and may narrow AI permissions for a",
+      "phases": [
+        "*"
+      ]
+    },
+    {
+      "id": "design:debugging-and-operations",
+      "path": "docs/design/debugging-and-operations.md",
+      "title": "Debugging and Operational Investigation",
+      "summary": "The minimal [corrective-debugging](../workflows/corrective-debugging.md) and [operational-stabilization](../workflows/operational-stabilization.md) profiles translate this discussion into pilotable flows. This document retains the reasoning",
+      "phases": []
+    },
+    {
+      "id": "design:executable-workflows",
+      "path": "docs/design/executable-workflows.md",
+      "title": "Executable AHEAD Workflows",
+      "summary": "The executable layer makes AHEAD workflow state durable and makes selected human/AI boundaries enforceable across integrations. It does not turn judgment into a checklist or make workflow artifacts proof of understanding.",
+      "phases": [
+        "*"
+      ]
+    },
+    {
+      "id": "design:process-taxonomy",
+      "path": "docs/design/process-taxonomy.md",
+      "title": "AHEAD Process Taxonomy",
+      "summary": "AHEAD should not create a workflow for every issue label. “Security,” “performance,” “data,” “incident,” and “technical debt” often describe risk, domain, urgency, or cause—not the kind of reasoning needed to complete the work.",
+      "phases": []
+    },
+    {
+      "id": "engineering-practice",
+      "path": "docs/engineering-practice.md",
+      "title": "AHEAD Engineering Practice",
+      "summary": "AHEAD is not only a sequence of AI gates. It is a way of practicing engineering. This guide distills general habits from the submitted starting list into a smaller set of principles that can be remembered, applied, and evaluated.",
+      "phases": [
+        "*"
+      ]
+    },
+    {
+      "id": "evidence:evidence-standard",
+      "path": "docs/evidence/evidence-standard.md",
+      "title": "AHEAD Evidence Standard",
+      "summary": "AHEAD should be supported by the best available evidence without claiming more certainty than software-engineering research can provide. A credible methodology must distinguish evidence for a descriptive claim from evidence that a particula",
+      "phases": [
+        "research",
+        "questions",
+        "decision",
+        "plan",
+        "ai-review",
+        "human-review",
+        "verify",
+        "ai-audit",
+        "outcome"
+      ]
+    },
+    {
+      "id": "evidence:research-map",
+      "path": "docs/evidence/research-map.md",
+      "title": "AHEAD Research Map",
+      "summary": "This document maps current AHEAD design claims to available evidence. It is not a bibliography of everything related to software engineering. It focuses on claims that materially shape the methodology.",
+      "phases": []
+    },
+    {
+      "id": "rationale",
+      "path": "docs/rationale.md",
+      "title": "Why AHEAD",
+      "summary": "AI can make software engineering faster. It can search broadly, synthesize information, identify omissions, generate alternatives, produce routine code, explain unfamiliar systems, and review more material than a person can inspect unaided.",
+      "phases": [
+        "*"
+      ]
+    },
+    {
+      "id": "references:pragmatic-programmer-page-index",
+      "path": "docs/references/pragmatic-programmer-page-index.md",
+      "title": "*The Pragmatic Programmer* Page Index",
+      "summary": "This index preserves the page-level provenance from the original AHEAD engineering-practice notes for:",
+      "phases": []
+    },
+    {
+      "id": "references:submitted-engineering-notes",
+      "path": "docs/references/submitted-engineering-notes.md",
+      "title": "Submitted Engineering Notes",
+      "summary": "This document preserves submitted engineering tips, checklists, and practices that are intentionally condensed in the [AHEAD Engineering Practice](../engineering-practice.md) guide. It is a source record, not a claim that every item is an e",
+      "phases": []
+    },
+    {
+      "id": "releasing-pi",
+      "path": "docs/releasing-pi.md",
+      "title": "Releasing the Pi Extension",
+      "summary": "- npm package: `ahead-pi` - package source: `integrations/pi` - release workflow: `.github/workflows/publish-pi.yml` - release tag: `pi-v<package-version>` - stable npm dist-tag: `latest` - prerelease npm dist-tag: `next` - registry: `https",
+      "phases": []
+    },
+    {
+      "id": "workflows:readme",
+      "path": "docs/workflows/README.md",
+      "title": "AHEAD Pilot Workflows",
+      "summary": "These six minimal workflow profiles are meant to be used on real engineering work before AHEAD builds a workflow engine, editor extension, or CI enforcement. They are deliberately small. The pilot should reveal which phases, gates, and reco",
+      "phases": []
+    },
+    {
+      "id": "workflows:corrective-debugging",
+      "path": "docs/workflows/corrective-debugging.md",
+      "title": "Corrective Debugging Workflow",
+      "summary": "Use this flow when observed behavior conflicts with intended behavior and the dominant work is causal diagnosis plus correction. It ends with a verified correction or an explicit human acceptance of remaining uncertainty.",
+      "phases": []
+    },
+    {
+      "id": "workflows:decision",
+      "path": "docs/workflows/decision.md",
+      "title": "Decision Workflow",
+      "summary": "Use this flow when the deliverable is an accountable human choice among alternatives: architecture, buy versus build, technology selection, platform direction, policy, or another consequential course.",
+      "phases": []
+    },
+    {
+      "id": "workflows:internal-improvement",
+      "path": "docs/workflows/internal-improvement.md",
+      "title": "Internal Improvement Workflow",
+      "summary": "Use this flow when externally required behavior should remain invariant while an internal quality improves: maintainability, comprehensibility, performance, reliability margin, operability, testability, cost, or preventive risk reduction.",
+      "phases": []
+    },
+    {
+      "id": "workflows:investigation",
+      "path": "docs/workflows/investigation.md",
+      "title": "Investigation Workflow",
+      "summary": "Use this flow when the primary deliverable is knowledge or reduced uncertainty and no intervention has yet been selected. It may answer feasibility, causal, capacity, vendor, architectural, or technical questions.",
+      "phases": []
+    },
+    {
+      "id": "workflows:operational-stabilization",
+      "path": "docs/workflows/operational-stabilization.md",
+      "title": "Operational Stabilization Workflow",
+      "summary": "Use this flow when a live system is outside an acceptable operating state and the immediate outcome is restoration, stabilization, or demonstrated convergence. It covers code and non-code causes such as reconciliation storms, configuration ",
+      "phases": []
+    },
+    {
+      "id": "workflows:product-change",
+      "path": "docs/workflows/product-change.md",
+      "title": "Product Change Workflow",
+      "summary": "Use this flow when the dominant outcome is new, changed, adapted, migrated, or retired externally meaningful behavior. It ends with verified intended behavior and an accountable human outcome decision.",
+      "phases": [
+        "*"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ahead-pi",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "AHEAD workflow enforcement and context for Pi",
   "license": "MIT",
   "type": "module",
@@ -49,10 +49,12 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
     "@types/node": "24.12.4",
     "typebox": "1.1.38",
     "typescript": "5.9.3"

package/src/guidance.ts

@@ -110,8 +110,8 @@ const guides: Record<string, PhaseGuide> = {
   },
   implement: {
     objective: "Produce a change the engineer understands and can defend.",
-    human: "Own the implementation, understand every lasting change, run the planned checks, and record deviations.",
-    ai: "Assist within the approved plan, explain changes, run authorized checks, and surface reasons to revisit earlier phases.",
+    human: "Make the first attempt, ask questions freely, own the implementation, understand every lasting change, run the planned checks, and record deviations.",
+    ai: "Coach, explain, help diagnose, and suggest bounded next steps within the approved plan. Do not turn a question into taking over the implementation.",
     artifactPrompts: {
       changeset: [
         "What exact commit, branch, pull request, or diff identifies the current change?",
@@ -252,7 +252,9 @@ export function nextAction(state: RunState, workflow: WorkflowDefinition): Guide
         ? "ai"
         : "human";
     if (actor === "human") {
-      const label = state.phase.id === "human-review"
+      const label = state.phase.id === "implement" && artifact.kind === "changeset"
+        ? "Implement first, then record the exact changeset"
+        : state.phase.id === "human-review"
         ? "Independent reviewer records the current human review"
         : `Write ${artifact.title}`;
       return { actor, label, artifactKind: artifact.kind };
@@ -323,7 +325,7 @@ export function buildWidgetLines(run: Run, state: RunState, workflow: WorkflowDe
     `AI: ${guide.ai}`,
     `Required: ${checklist}`,
     `Next (${action.actor === "human" ? "you" : "AI"}): ${action.label}`,
-    "Run /ahead for the guided action.",
+    "Run /ahead for the guided action · /ahead-guide for framework docs.",
   ];
 }
 

package/src/index.ts

@@ -14,6 +14,13 @@ import {
   phaseGuide,
   phasePosition,
 } from "./guidance.js";
+import {
+  findReference,
+  loadReferenceIndex,
+  readReference,
+  relevantReferences,
+} from "./reference.js";
+import { showReferenceViewer } from "./reference-viewer.js";
 import { humanActor, projectRoot, RunStore } from "./storage.js";
 import type { Actor, Capability, EventAction, Run, RunState } from "./types.js";
 
@@ -38,6 +45,9 @@ const RecordArtifactParams = Type.Object({
   kind: Type.String({ description: "Artifact kind permitted for AI in the active phase" }),
   content: Type.String({ description: "Complete Markdown artifact content", maxLength: 100_000 }),
 });
+const ReferenceParams = Type.Object({
+  topic: Type.Optional(Type.String({ description: "Reference id, path, or title; omit to list phase-relevant references" })),
+});
 
 export default function aheadExtension(pi: ExtensionAPI): void {
   pi.registerCommand("ahead", {
@@ -47,6 +57,13 @@ export default function aheadExtension(pi: ExtensionAPI): void {
     }),
   });
 
+  pi.registerCommand("ahead-guide", {
+    description: "Read the AHEAD framework guidance relevant to the active phase",
+    handler: async (args, ctx) => command(ctx, async () => {
+      await showAheadGuide(ctx, args);
+    }),
+  });
+
   pi.registerCommand("ahead-start", {
     description: "Advanced: start a Product Change run directly",
     handler: async (args, ctx) => command(ctx, async () => {
@@ -137,6 +154,7 @@ export default function aheadExtension(pi: ExtensionAPI): void {
       ctx.ui.notify(
         [
           "/ahead [title] — enter, resume, or act in guided AHEAD mode",
+          "/ahead-guide [topic] — read the applicable AHEAD framework Markdown",
           "",
           "Once started, the repository run remains in AHEAD mode until an accountable human closes the outcome.",
           "Use normal conversation to think and work with AI. Run /ahead whenever you want the next valid action.",
@@ -165,6 +183,34 @@ export default function aheadExtension(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: "ahead_get_reference",
+    label: "AHEAD framework reference",
+    description: "List or read packaged AHEAD Constitution, philosophy, acceptable-use, engineering-practice, workflow, and evidence Markdown.",
+    promptSnippet: "Retrieve relevant AHEAD framework guidance when the phase or policy is unclear.",
+    parameters: ReferenceParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      return toolResult(async () => {
+        const run = await storeFor(ctx).loadCurrent();
+        const phase = run && !(await enginePromise).deriveState(run).closed
+          ? (await enginePromise).deriveState(run).phase.id
+          : undefined;
+        if (!params.topic?.trim()) {
+          const index = await loadReferenceIndex();
+          return {
+            phase: phase ?? null,
+            recommended: await relevantReferences(phase),
+            available: index.references.map(({ id, title, path }) => ({ id, title, path })),
+            instruction: "Request one reference by id, path, or title. Load only what is relevant.",
+          };
+        }
+        const entry = await findReference(params.topic);
+        if (!entry) throw new Error(`No packaged AHEAD reference matches ${params.topic}`);
+        return { reference: entry, content: await readReference(entry) };
+      });
+    },
+  });
+
   pi.registerTool({
     name: "ahead_record_artifact",
     label: "Record AHEAD artifact",
@@ -277,6 +323,8 @@ export default function aheadExtension(pi: ExtensionAPI): void {
       "- Never author a human-owned artifact, make a human decision, accept a gate, transition the run, approve a change, or claim accountability.",
       "- When required AI-owned work is ready, record it with ahead_record_artifact and explain what the human must validate or decide.",
       "- Treat AI review findings as hypotheses. Independent human review remains required for lasting engineering changes.",
+      "- Humans may ask questions at any phase. During implementation, help them understand or solve the problem without taking over; if their first attempt or current model is missing, ask for it.",
+      "- When AHEAD policy or rationale is unclear, use ahead_get_reference to retrieve only the applicable packaged Markdown.",
     ].join("\n");
     return { systemPrompt: `${event.systemPrompt}\n\n${phaseInstructions}\n\n${liveContext}\n` };
   });
@@ -378,6 +426,7 @@ async function openAheadMode(pi: ExtensionAPI, args: string, ctx: ExtensionComma
     state.allowed_ai_capabilities.length > 0
     && action.actor !== "ai"
     && !missingRequired.some((artifact) => artifact.actor === "ai")
+    && state.phase.id !== "implement"
   ) {
     actions.push({
       label: `Ask AI to assist · ${state.phase.title}`,
@@ -385,6 +434,13 @@ async function openAheadMode(pi: ExtensionAPI, args: string, ctx: ExtensionComma
     });
   }
 
+  if (state.phase.id === "implement") {
+    actions.push({
+      label: "Ask AI for help understanding or solving a problem",
+      run: async () => askImplementationQuestion(pi, ctx, state),
+    });
+  }
+
   if (state.return_targets.length > 0) {
     actions.push({
       label: "Return to an earlier phase",
@@ -392,6 +448,11 @@ async function openAheadMode(pi: ExtensionAPI, args: string, ctx: ExtensionComma
     });
   }
 
+  actions.push({
+    label: "Read AHEAD framework guidance for this phase",
+    run: async () => showAheadGuide(ctx, ""),
+  });
+
   actions.push({
     label: "Explain this phase and its expectations",
     run: async () => {
@@ -416,6 +477,73 @@ async function openAheadMode(pi: ExtensionAPI, args: string, ctx: ExtensionComma
   if (chosen) await chosen.run();
 }
 
+async function askImplementationQuestion(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  state: RunState,
+): Promise<void> {
+  if (!ctx.hasUI) throw new Error("Implementation coaching requires interactive or RPC UI support");
+  const question = await ctx.ui.editor(
+    "AHEAD implementation help · human first",
+    [
+      "## What are you trying to understand or solve?",
+      "",
+      "",
+      "## What do you currently think is happening or should happen?",
+      "",
+      "",
+      "## What have you tried or inspected so far?",
+      "",
+      "",
+      "## What kind of help would be useful?",
+      "",
+      "<!-- Ask for explanation, a hint, competing approaches, debugging help, or a bounded suggestion. -->",
+      "",
+    ].join("\n"),
+  );
+  if (!question?.trim()) return;
+  pi.sendUserMessage([
+    `AHEAD mode: help me with this ${state.phase.title} question while I remain the implementer.`,
+    "Use my current model and first attempt below. Help me understand or solve the problem with questions, explanation, evidence, hints, and bounded next steps.",
+    "Do not convert this question into autonomous implementation or author my human-owned records. If I later request a bounded mechanical edit, explain it so I can inspect and own it.",
+    "",
+    question.trim(),
+  ].join("\n"));
+}
+
+async function showAheadGuide(ctx: ExtensionCommandContext, requestedTopic: string): Promise<void> {
+  if (!ctx.hasUI) throw new Error("Reading AHEAD framework guidance requires interactive or RPC UI support");
+  const run = await storeFor(ctx).loadCurrent();
+  const phase = run && !(await enginePromise).deriveState(run).closed
+    ? (await enginePromise).deriveState(run).phase.id
+    : undefined;
+  const index = await loadReferenceIndex();
+  let entry = requestedTopic.trim() && requestedTopic.trim().toLowerCase() !== "all"
+    ? await findReference(requestedTopic)
+    : undefined;
+
+  if (requestedTopic.trim() && requestedTopic.trim().toLowerCase() !== "all" && !entry) {
+    throw new Error(`No packaged AHEAD reference matches ${requestedTopic.trim()}`);
+  }
+
+  if (!entry) {
+    const recommended = requestedTopic.trim().toLowerCase() === "all"
+      ? index.references
+      : await relevantReferences(phase);
+    const browseAll = "Browse all packaged AHEAD Markdown";
+    const selected = await ctx.ui.select(
+      phase ? `AHEAD guidance · ${phase}` : "AHEAD framework guidance",
+      [...recommended.map((candidate) => candidate.title), ...(recommended.length < index.references.length ? [browseAll] : [])],
+    );
+    if (!selected) return;
+    if (selected === browseAll) return showAheadGuide(ctx, "all");
+    entry = recommended.find((candidate) => candidate.title === selected);
+  }
+  if (!entry) return;
+
+  await showReferenceViewer(ctx, `AHEAD reference · ${entry.title}`, await readReference(entry));
+}
+
 async function startRun(ctx: ExtensionCommandContext, requestedTitle: string): Promise<Run | undefined> {
   const engine = await enginePromise;
   const store = storeFor(ctx);

package/src/reference-viewer.ts

@@ -0,0 +1,71 @@
+import {
+  getMarkdownTheme,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+  Markdown,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+
+export async function showReferenceViewer(
+  ctx: ExtensionCommandContext,
+  title: string,
+  content: string,
+): Promise<void> {
+  await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+    const markdown = new Markdown(content.trim(), 0, 0, getMarkdownTheme());
+    let scrollOffset = 0;
+    let pageSize = 10;
+    let totalLines = 0;
+
+    const component = {
+      render(width: number): string[] {
+        const innerWidth = Math.max(20, width - 2);
+        const contentWidth = Math.max(18, innerWidth - 2);
+        const rendered = markdown.render(contentWidth);
+        totalLines = rendered.length;
+        pageSize = Math.max(6, Math.min(30, tui.terminal.rows - 7));
+        const maxOffset = Math.max(0, totalLines - pageSize);
+        scrollOffset = Math.min(scrollOffset, maxOffset);
+        const visible = rendered.slice(scrollOffset, scrollOffset + pageSize);
+        const remaining = Math.max(0, totalLines - pageSize - scrollOffset);
+        const border = (value: string) => theme.fg("border", value);
+        const pad = (value: string): string => {
+          const truncated = truncateToWidth(value, innerWidth, "…", true);
+          return `${truncated}${" ".repeat(Math.max(0, innerWidth - visibleWidth(truncated)))}`;
+        };
+        const lines = [
+          border(`╭${"─".repeat(innerWidth)}╮`),
+          `${border("│")}${pad(` ${theme.fg("accent", theme.bold(title))}`)}${border("│")}`,
+          `${border("│")}${pad(theme.fg("dim", ` ↑ ${scrollOffset} lines · ↓ ${remaining} lines`))}${border("│")}`,
+        ];
+        for (const line of visible) lines.push(`${border("│")}${pad(` ${line}`)}${border("│")}`);
+        for (let index = visible.length; index < pageSize; index += 1) {
+          lines.push(`${border("│")}${pad("")}${border("│")}`);
+        }
+        lines.push(
+          `${border("│")}${pad(theme.fg("dim", " ↑↓ scroll · PgUp/PgDn page · Home/End jump · Esc close"))}${border("│")}`,
+          border(`╰${"─".repeat(innerWidth)}╯`),
+        );
+        return lines;
+      },
+      invalidate(): void {
+        markdown.invalidate();
+      },
+      handleInput(data: string): void {
+        const maxOffset = Math.max(0, totalLines - pageSize);
+        if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) done();
+        else if (matchesKey(data, "up")) scrollOffset = Math.max(0, scrollOffset - 1);
+        else if (matchesKey(data, "down")) scrollOffset = Math.min(maxOffset, scrollOffset + 1);
+        else if (matchesKey(data, "pageUp")) scrollOffset = Math.max(0, scrollOffset - pageSize);
+        else if (matchesKey(data, "pageDown")) scrollOffset = Math.min(maxOffset, scrollOffset + pageSize);
+        else if (matchesKey(data, "home")) scrollOffset = 0;
+        else if (matchesKey(data, "end")) scrollOffset = maxOffset;
+        tui.requestRender();
+      },
+    };
+    return component;
+  });
+}

package/src/reference.ts

@@ -0,0 +1,56 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const referenceDirectory = fileURLToPath(new URL("../generated/reference/", import.meta.url));
+
+export interface ReferenceEntry {
+  id: string;
+  path: string;
+  title: string;
+  summary: string;
+  phases: string[];
+}
+
+interface ReferenceIndex {
+  generated_from: string[];
+  references: ReferenceEntry[];
+}
+
+let indexPromise: Promise<ReferenceIndex> | undefined;
+
+export async function loadReferenceIndex(): Promise<ReferenceIndex> {
+  indexPromise ??= readFile(`${referenceDirectory}index.json`, "utf8")
+    .then((content) => JSON.parse(content) as ReferenceIndex);
+  return indexPromise;
+}
+
+export async function relevantReferences(phaseId?: string): Promise<ReferenceEntry[]> {
+  const { references } = await loadReferenceIndex();
+  if (!phaseId) return references.filter((entry) => entry.phases.includes("*"));
+  return references.filter((entry) => entry.phases.includes("*") || entry.phases.includes(phaseId));
+}
+
+export async function findReference(topic: string): Promise<ReferenceEntry | undefined> {
+  const normalized = normalize(topic);
+  const { references } = await loadReferenceIndex();
+  return references.find((entry) =>
+    normalize(entry.id) === normalized
+    || normalize(entry.path) === normalized
+    || normalize(entry.title) === normalized
+  ) ?? references.find((entry) =>
+    normalize(entry.id).includes(normalized)
+    || normalize(entry.path).includes(normalized)
+    || normalize(entry.title).includes(normalized)
+  );
+}
+
+export async function readReference(entry: ReferenceEntry): Promise<string> {
+  if (entry.path.includes("..") || entry.path.startsWith("/")) {
+    throw new Error(`Invalid packaged AHEAD reference path: ${entry.path}`);
+  }
+  return readFile(`${referenceDirectory}${entry.path}`, "utf8");
+}
+
+function normalize(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}