@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/templates/epic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epic.d.ts","sourceRoot":"","sources":["../../src/templates/epic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,YAAY,GACZ,qBAAqB,GACrB,cAAc,GACd,aAAa,GACb,eAAe,CAAC;AAEpB,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,cAAc,CAAC;IACpB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,eAAe,EA2CnD,CAAC;AAEF,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,eAAe,CAIpE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAO7C"}

package/dist/templates/epic.js

@@ -0,0 +1,67 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Epic template (EPIC-059, design v6.1 §2): the sections an epic carries, the headings
+ * readers accept for each, and the skeleton `add` writes for an epic without description.
+ */
+export const EPIC_SECTIONS = [
+    {
+        key: 'context',
+        heading: 'Context',
+        aliases: ['Context', 'Background', 'Problem'],
+        optional: false,
+        hint: 'why now, which problem, for whom',
+    },
+    {
+        key: 'user-story',
+        heading: 'User story',
+        aliases: ['User story'],
+        optional: false,
+        hint: 'As a <role> I want <goal>, so that <benefit>',
+    },
+    {
+        key: 'acceptance-criteria',
+        heading: 'Acceptance criteria',
+        aliases: ['Acceptance criteria', 'Success criteria'],
+        optional: false,
+        hint: 'rough, observable signals that the whole epic is done',
+    },
+    {
+        key: 'out-of-scope',
+        heading: 'Out of scope',
+        aliases: ['Out of scope', 'Non-goals', 'Not in scope', 'Excluded', 'Deliberately left out'],
+        optional: false,
+        hint: 'one exclusion per line, with a reason when not obvious',
+    },
+    {
+        key: 'constraints',
+        heading: 'Constraints',
+        aliases: ['Constraints', 'Non-functional requirements'],
+        optional: false,
+        hint: 'a binding rule per line, optionally with "Check:" saying how it is verified',
+    },
+    {
+        key: 'working-rules',
+        heading: 'Working rules',
+        aliases: ['Working rules'],
+        optional: true,
+        hint: 'optional; rules for how sessions build this epic beyond the defaults',
+    },
+];
+export function epicSectionSpec(key) {
+    const spec = EPIC_SECTIONS.find((section) => section.key === key);
+    if (!spec)
+        throw new Error(`Unknown epic section: ${key}`);
+    return spec;
+}
+/**
+ * The skeleton an epic gets when it is added without a description. Placeholders are HTML
+ * comments, so an untouched section reads as empty and is still reported as missing.
+ */
+export function generateEpicTemplate() {
+    const sections = EPIC_SECTIONS.map((section) => `## ${section.heading}\n\n<!-- ${section.hint} -->`);
+    const footer = '<!-- Children implement this epic; decisions and open points are decision and question items linked with relates-to, never sections. -->';
+    return `${[...sections, footer].join('\n\n')}\n`;
+}
+//# sourceMappingURL=epic.js.map

package/dist/templates/epic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epic.js","sourceRoot":"","sources":["../../src/templates/epic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsBH,MAAM,CAAC,MAAM,aAAa,GAA+B;IACvD;QACE,GAAG,EAAE,SAAS;QACd,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC;QAC7C,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,kCAAkC;KACzC;IACD;QACE,GAAG,EAAE,YAAY;QACjB,OAAO,EAAE,YAAY;QACrB,OAAO,EAAE,CAAC,YAAY,CAAC;QACvB,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,8CAA8C;KACrD;IACD;QACE,GAAG,EAAE,qBAAqB;QAC1B,OAAO,EAAE,qBAAqB;QAC9B,OAAO,EAAE,CAAC,qBAAqB,EAAE,kBAAkB,CAAC;QACpD,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,uDAAuD;KAC9D;IACD;QACE,GAAG,EAAE,cAAc;QACnB,OAAO,EAAE,cAAc;QACvB,OAAO,EAAE,CAAC,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,uBAAuB,CAAC;QAC3F,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,wDAAwD;KAC/D;IACD;QACE,GAAG,EAAE,aAAa;QAClB,OAAO,EAAE,aAAa;QACtB,OAAO,EAAE,CAAC,aAAa,EAAE,6BAA6B,CAAC;QACvD,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,6EAA6E;KACpF;IACD;QACE,GAAG,EAAE,eAAe;QACpB,OAAO,EAAE,eAAe;QACxB,OAAO,EAAE,CAAC,eAAe,CAAC;QAC1B,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,sEAAsE;KAC7E;CACF,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,GAAmB;IACjD,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAClE,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,EAAE,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAChC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,OAAO,CAAC,OAAO,YAAY,OAAO,CAAC,IAAI,MAAM,CACjE,CAAC;IACF,MAAM,MAAM,GACV,0IAA0I,CAAC;IAC7I,OAAO,GAAG,CAAC,GAAG,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AACnD,CAAC"}

package/dist/templates/madr.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * MADR 4.0 template generator for ADR-type DOC items
+ */
+/**
+ * Generate a MADR 4.0-compliant skeleton description for an ADR document.
+ * Called when `type === 'doc'` and the item is identified as an ADR
+ * (tags include 'adr' or title starts with 'ADR').
+ */
+export declare function generateMadrTemplate(id: string, title: string, date: string): string;
+/**
+ * Detect whether an item should receive a MADR template based on tags and title.
+ */
+export declare function isMadrCandidate(tags: string[], title: string): boolean;
+//# sourceMappingURL=madr.d.ts.map

package/dist/templates/madr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"madr.d.ts","sourceRoot":"","sources":["../../src/templates/madr.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA2CpF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtE"}

package/dist/templates/madr.js

@@ -0,0 +1,61 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * MADR 4.0 template generator for ADR-type DOC items
+ */
+/**
+ * Generate a MADR 4.0-compliant skeleton description for an ADR document.
+ * Called when `type === 'doc'` and the item is identified as an ADR
+ * (tags include 'adr' or title starts with 'ADR').
+ */
+export function generateMadrTemplate(id, title, date) {
+    // Strip "ADR-NNN: " or "ADR-NNN " prefix from title if present
+    const cleanTitle = title.replace(/^ADR-\d+[:\s]\s*/i, '').trim();
+    return `# ${id}: ${cleanTitle}
+
+## Status
+
+Proposed
+
+## Date
+
+${date}
+
+## Context and Problem Statement
+
+<!-- What is the issue motivating this decision? What problem are we solving? -->
+
+## Decision Drivers
+
+- <!-- Driver 1 -->
+- <!-- Driver 2 -->
+
+## Considered Options
+
+| Option | Description | Pros | Cons |
+|--------|------------|------|------|
+| Option A | <!-- describe --> | <!-- pros --> | <!-- cons --> |
+| Option B | <!-- describe --> | <!-- pros --> | <!-- cons --> |
+
+## Decision Outcome
+
+Chosen option: **"<!-- option -->"**, because <!-- justification -->.
+
+### Positive Consequences
+
+- <!-- Benefit 1 -->
+
+### Negative Consequences
+
+- <!-- Drawback 1 -->
+- Mitigation: <!-- how to address -->
+`;
+}
+/**
+ * Detect whether an item should receive a MADR template based on tags and title.
+ */
+export function isMadrCandidate(tags, title) {
+    return tags.includes('adr') || /^ADR[-\s]/i.test(title);
+}
+//# sourceMappingURL=madr.js.map

package/dist/templates/madr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"madr.js","sourceRoot":"","sources":["../../src/templates/madr.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAU,EAAE,KAAa,EAAE,IAAY;IAC1E,+DAA+D;IAC/D,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAEjE,OAAO,KAAK,EAAE,KAAK,UAAU;;;;;;;;EAQ7B,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BL,CAAC;AACF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAc,EAAE,KAAa;IAC3D,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC"}

package/dist/templates/reminders.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Texts of the write-time reminders (EPIC-059, design v6.1 §1, §2 and §5): what add, update and
+ * link answer in their warnings. Every text is a template for any project.
+ */
+/** The section a story, task or bug states before its code changes (design v6.1 §5). */
+export declare const APPROACH_TEMPLATE: string;
+/** The reminder when an item goes to in-progress without an Approach section. */
+export declare function approachReminder(id: string): string;
+/** How many review IDs a batch reminder names before it summarises the rest. */
+export declare const BATCH_REMINDER_ID_LIMIT = 5;
+/** The batch run rule (design v6.1 §5), appended to the count of waiting items. */
+export declare const BATCH_RUN_RULE: string;
+/** The reminder when work items wait in review together; `queue` lists all of them. */
+export declare function batchRunReminder(queue: readonly string[]): string;
+/** The reminder when an epic lacks required template sections or holds only placeholders. */
+export declare function epicSectionsReminder(id: string, headings: readonly string[]): string;
+/** The reminder when a story written from the story template leaves required parts empty. */
+export declare function storySectionsReminder(id: string, parts: readonly string[]): string;
+/** The reminder when a title runs past a headline (STORY-504); `parts` names what to move. */
+export declare function titleLengthReminder(id: string, length: number, parts: readonly string[]): string;
+/** What earns a decision item (design v6.1 §1); smaller choices belong in the commit message. */
+export declare const DECISION_FILTER = "An epic carries about 10 to 20 decisions: write one for a deviation, a behavior or interface choice, or a rejected alternative a later reader needs; small choices go into the commit message.";
+/** The decision count of an epic, reported when a decision is linked into it. */
+export declare function decisionCountReminder(epicId: string, count: number): string;
+//# sourceMappingURL=reminders.d.ts.map

package/dist/templates/reminders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminders.d.ts","sourceRoot":"","sources":["../../src/templates/reminders.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,QAOlB,CAAC;AAEb,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,mFAAmF;AACnF,eAAO,MAAM,cAAc,QAGgF,CAAC;AAE5G,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAKjE;AAED,6FAA6F;AAC7F,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEpF;AAED,6FAA6F;AAC7F,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAElF;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGhG;AAED,iGAAiG;AACjG,eAAO,MAAM,eAAe,mMACsK,CAAC;AAEnM,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG3E"}

package/dist/templates/reminders.js

@@ -0,0 +1,54 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Texts of the write-time reminders (EPIC-059, design v6.1 §1, §2 and §5): what add, update and
+ * link answer in their warnings. Every text is a template for any project.
+ */
+/** The section a story, task or bug states before its code changes (design v6.1 §5). */
+export const APPROACH_TEMPLATE = [
+    '## Approach',
+    '',
+    '- Understood: the goal in your own words',
+    '- Approach: the change and the paths it touches',
+    '- Tests: the tests that will prove it',
+    '- Open assumption: what you assume without confirmation',
+].join('\n');
+/** The reminder when an item goes to in-progress without an Approach section. */
+export function approachReminder(id) {
+    return `${id} is in progress without an "## Approach" section. Before you change code, add one through update append_description:\n\n${APPROACH_TEMPLATE}`;
+}
+/** How many review IDs a batch reminder names before it summarises the rest. */
+export const BATCH_REMINDER_ID_LIMIT = 5;
+/** The batch run rule (design v6.1 §5), appended to the count of waiting items. */
+export const BATCH_RUN_RULE = 'Run the full test suite once for the batch, on a branch that holds all batch items. ' +
+    'Green: move them to done together with bulk update (update with ids). ' +
+    'Red: send the items whose paths meet the failing tests back to in-progress and keep the rest in review.';
+/** The reminder when work items wait in review together; `queue` lists all of them. */
+export function batchRunReminder(queue) {
+    const shown = queue.slice(0, BATCH_REMINDER_ID_LIMIT);
+    const more = queue.length - shown.length;
+    const ids = more > 0 ? `${shown.join(', ')}, +${more} more` : shown.join(', ');
+    return `Batch run: ${queue.length} work items wait in review (${ids}). ${BATCH_RUN_RULE}`;
+}
+/** The reminder when an epic lacks required template sections or holds only placeholders. */
+export function epicSectionsReminder(id, headings) {
+    return `${id} lacks the epic sections ${headings.join(', ')} (absent or empty). Write them through update description; Working rules is optional.`;
+}
+/** The reminder when a story written from the story template leaves required parts empty. */
+export function storySectionsReminder(id, parts) {
+    return `${id} comes from the story template and leaves ${parts.join(' and ')} empty. Write them through update description; Out of scope, Constraints and Working rules are optional.`;
+}
+/** The reminder when a title runs past a headline (STORY-504); `parts` names what to move. */
+export function titleLengthReminder(id, length, parts) {
+    const move = parts.length > 0 ? parts.join(', ') : 'the reasons, options and scope';
+    return `${id} has a ${length}-character title; a title is a headline of about 60 to 90 characters. Move ${move} into the description and shorten the title through update.`;
+}
+/** What earns a decision item (design v6.1 §1); smaller choices belong in the commit message. */
+export const DECISION_FILTER = 'An epic carries about 10 to 20 decisions: write one for a deviation, a behavior or interface choice, or a rejected alternative a later reader needs; small choices go into the commit message.';
+/** The decision count of an epic, reported when a decision is linked into it. */
+export function decisionCountReminder(epicId, count) {
+    const over = count > 20 ? ' Keep small choices in the commit message.' : '';
+    return `${epicId} now has ${count} decision${count === 1 ? '' : 's'}; target 10 to 20.${over}`;
+}
+//# sourceMappingURL=reminders.js.map

package/dist/templates/reminders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminders.js","sourceRoot":"","sources":["../../src/templates/reminders.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,aAAa;IACb,EAAE;IACF,0CAA0C;IAC1C,iDAAiD;IACjD,uCAAuC;IACvC,yDAAyD;CAC1D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAAC,EAAU;IACzC,OAAO,GAAG,EAAE,2HAA2H,iBAAiB,EAAE,CAAC;AAC7J,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GACzB,sFAAsF;IACtF,wEAAwE;IACxE,yGAAyG,CAAC;AAE5G,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,KAAwB;IACvD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/E,OAAO,cAAc,KAAK,CAAC,MAAM,+BAA+B,GAAG,MAAM,cAAc,EAAE,CAAC;AAC5F,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,oBAAoB,CAAC,EAAU,EAAE,QAA2B;IAC1E,OAAO,GAAG,EAAE,4BAA4B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,uFAAuF,CAAC;AACrJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,qBAAqB,CAAC,EAAU,EAAE,KAAwB;IACxE,OAAO,GAAG,EAAE,6CAA6C,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,0GAA0G,CAAC;AACzL,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,mBAAmB,CAAC,EAAU,EAAE,MAAc,EAAE,KAAwB;IACtF,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,gCAAgC,CAAC;IACpF,OAAO,GAAG,EAAE,UAAU,MAAM,8EAA8E,IAAI,6DAA6D,CAAC;AAC9K,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,MAAM,eAAe,GAC1B,gMAAgM,CAAC;AAEnM,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,KAAa;IACjE,MAAM,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,OAAO,GAAG,MAAM,YAAY,KAAK,YAAY,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,qBAAqB,IAAI,EAAE,CAAC;AACjG,CAAC"}

package/dist/templates/story.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Story template (STORY-487): the skeleton `add` writes for a story without description. Its
+ * sections take the epic's headings and aliases with story wording, so the compass block and the
+ * section readers parse a story exactly like an epic; a story under an epic still takes its
+ * compass from the epic.
+ */
+import { type EpicSectionSpec } from './epic.js';
+/** The placeholder that opens the story: its user story, then its observable outcome. */
+export declare const STORY_OPENING_HINT = "As a <role> I want <goal>, so that <benefit>; then the observable outcome";
+/**
+ * The footer every story template carries. Its text marks a story written from the template, so
+ * the write-time reminder names the parts still empty there and stays quiet for any other story.
+ */
+export declare const STORY_TEMPLATE_MARKER = "Tasks implement this story;";
+export declare const STORY_SECTIONS: readonly EpicSectionSpec[];
+/**
+ * The skeleton a story gets when it is added without a description. Placeholders are HTML
+ * comments, so an untouched part reads as empty.
+ */
+export declare function generateStoryTemplate(): string;
+//# sourceMappingURL=story.d.ts.map

package/dist/templates/story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../src/templates/story.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAuB,KAAK,eAAe,EAAmB,MAAM,WAAW,CAAC;AAEvF,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,8EAC8C,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AAMnE,eAAO,MAAM,cAAc,EAAE,SAAS,eAAe,EAapD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C"}

package/dist/templates/story.js

@@ -0,0 +1,36 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Story template (STORY-487): the skeleton `add` writes for a story without description. Its
+ * sections take the epic's headings and aliases with story wording, so the compass block and the
+ * section readers parse a story exactly like an epic; a story under an epic still takes its
+ * compass from the epic.
+ */
+import { epicSectionSpec } from './epic.js';
+/** The placeholder that opens the story: its user story, then its observable outcome. */
+export const STORY_OPENING_HINT = 'As a <role> I want <goal>, so that <benefit>; then the observable outcome';
+/**
+ * The footer every story template carries. Its text marks a story written from the template, so
+ * the write-time reminder names the parts still empty there and stays quiet for any other story.
+ */
+export const STORY_TEMPLATE_MARKER = 'Tasks implement this story;';
+function storySection(key, optional, hint) {
+    return { ...epicSectionSpec(key), optional, hint };
+}
+export const STORY_SECTIONS = [
+    storySection('acceptance-criteria', false, 'observable outcomes that show the story is done'),
+    storySection('out-of-scope', true, 'optional; one exclusion per line'),
+    storySection('constraints', true, 'optional; a binding rule per line, with "Check:" saying how it is verified'),
+    storySection('working-rules', true, 'optional; rules for how sessions build this story beyond the defaults'),
+];
+/**
+ * The skeleton a story gets when it is added without a description. Placeholders are HTML
+ * comments, so an untouched part reads as empty.
+ */
+export function generateStoryTemplate() {
+    const sections = STORY_SECTIONS.map((section) => `## ${section.heading}\n\n<!-- ${section.hint} -->`);
+    const footer = `<!-- ${STORY_TEMPLATE_MARKER} decisions and open points are decision and question items linked with relates-to, never sections. -->`;
+    return `${[`<!-- ${STORY_OPENING_HINT} -->`, ...sections, footer].join('\n\n')}\n`;
+}
+//# sourceMappingURL=story.js.map

package/dist/templates/story.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"story.js","sourceRoot":"","sources":["../../src/templates/story.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAA6C,eAAe,EAAE,MAAM,WAAW,CAAC;AAEvF,yFAAyF;AACzF,MAAM,CAAC,MAAM,kBAAkB,GAC7B,2EAA2E,CAAC;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,6BAA6B,CAAC;AAEnE,SAAS,YAAY,CAAC,GAAmB,EAAE,QAAiB,EAAE,IAAY;IACxE,OAAO,EAAE,GAAG,eAAe,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AACrD,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAA+B;IACxD,YAAY,CAAC,qBAAqB,EAAE,KAAK,EAAE,iDAAiD,CAAC;IAC7F,YAAY,CAAC,cAAc,EAAE,IAAI,EAAE,kCAAkC,CAAC;IACtE,YAAY,CACV,aAAa,EACb,IAAI,EACJ,4EAA4E,CAC7E;IACD,YAAY,CACV,eAAe,EACf,IAAI,EACJ,uEAAuE,CACxE;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CACjC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,OAAO,CAAC,OAAO,YAAY,OAAO,CAAC,IAAI,MAAM,CACjE,CAAC;IACF,MAAM,MAAM,GAAG,QAAQ,qBAAqB,wGAAwG,CAAC;IACrJ,OAAO,GAAG,CAAC,QAAQ,kBAAkB,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AACrF,CAAC"}

package/dist/templates/task-workflow.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TASK workflow authoring template
+ * Produces a neutral declarative skeleton that points authors to safe evidence and secret handling.
+ */
+export declare function generateTaskWorkflowTemplate(title: string): string;
+//# sourceMappingURL=task-workflow.d.ts.map

package/dist/templates/task-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-workflow.d.ts","sourceRoot":"","sources":["../../src/templates/task-workflow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA8BlE"}

package/dist/templates/task-workflow.js

@@ -0,0 +1,39 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TASK workflow authoring template
+ * Produces a neutral declarative skeleton that points authors to safe evidence and secret handling.
+ */
+export function generateTaskWorkflowTemplate(title) {
+    return `# ${title}
+
+<!-- Structured TASK workflow definition. Runtime behavior is declared here; it is not selected by tags. -->
+
+## Process Definition
+
+\`\`\`yaml
+schema_version: "1.0"
+process_type: "replace-me"
+states: {}
+initial: "replace-me"
+transitions: []
+commands: []
+human_steps: []
+inputs: []
+preconditions: []
+evidence: []
+cleanup: []
+terminal: []
+max_attempts: 1
+allow_parallel_runs: false
+\`\`\`
+
+## Operational Notes
+
+- Declare credentials as \`secret-reference\` inputs; never persist secret values.
+- Reference evidence IDs from commands, human steps, preconditions, and cleanup.
+- Keep commands and human instructions declarative; the generic runtime owns execution state.
+`;
+}
+//# sourceMappingURL=task-workflow.js.map

package/dist/templates/task-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-workflow.js","sourceRoot":"","sources":["../../src/templates/task-workflow.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,UAAU,4BAA4B,CAAC,KAAa;IACxD,OAAO,KAAK,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BlB,CAAC;AACF,CAAC"}

package/dist/templates/test-workflow.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TEST workflow authoring template.
+ */
+import type { TestProfile } from '../schemas/index.js';
+export declare function generateTestWorkflowTemplate(title: string, profile: TestProfile): string;
+//# sourceMappingURL=test-workflow.d.ts.map

package/dist/templates/test-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-workflow.d.ts","sourceRoot":"","sources":["../../src/templates/test-workflow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CA4BxF"}

package/dist/templates/test-workflow.js

@@ -0,0 +1,36 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TEST workflow authoring template.
+ */
+export function generateTestWorkflowTemplate(title, profile) {
+    return `# ${title}
+
+<!-- Structured TEST definition. Acceptance behavior is declared here; the runtime stays generic. -->
+
+## Test Definition
+
+\`\`\`yaml
+schema_version: "1.0"
+process_type: "replace-me"
+profile: "${profile}"
+derived_doc: "DOC-000"
+dependencies: []
+states: {}
+initial: "replace-me"
+transitions: []
+human_steps: []
+evidence: []
+cleanup: []
+terminal: []
+max_attempts: 1
+\`\`\`
+
+## Acceptance Notes
+
+- Declare direct \`tests\` relationships for the intended Acceptance scope.
+- Keep human instructions actionable and never persist secret values in evidence.
+`;
+}
+//# sourceMappingURL=test-workflow.js.map

package/dist/templates/test-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-workflow.js","sourceRoot":"","sources":["../../src/templates/test-workflow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,UAAU,4BAA4B,CAAC,KAAa,EAAE,OAAoB;IAC9E,OAAO,KAAK,KAAK;;;;;;;;;YASP,OAAO;;;;;;;;;;;;;;;;;CAiBlB,CAAC;AACF,CAAC"}

package/dist/types/commands.d.ts

@@ -42,6 +42,7 @@ export interface ListItemsCommandArgs {
     tags?: string[];
     archived?: boolean;
     limit?: string;
+    stale_days?: number;
 }
 export interface SearchItemsCommandArgs {
     query: string;

package/dist/types/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/types/commands.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAS1C,CAAC;AAEX;;GAEG;AAEH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AAEH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,kBAAkB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/types/commands.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAY1C,CAAC;AAEX;;GAEG;AAEH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AAEH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,kBAAkB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/types/commands.js

@@ -17,5 +17,8 @@ export const TYPE_SHORTCUTS = {
     bug: 'bug',
     spike: 'spike',
     test: 'test',
+    doc: 'doc',
+    dec: 'decision',
+    qst: 'question',
 };
 //# sourceMappingURL=commands.js.map

package/dist/types/commands.js.map

@@ -1 +1 @@
-{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/types/commands.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAA6B;IACtD,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,aAAa;IAClB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,KAAK;IACV,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACJ,CAAC"}
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/types/commands.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAA6B;IACtD,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,aAAa;IAClB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,KAAK;IACV,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,UAAU;CACP,CAAC"}

package/dist/types/docs-map.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TypeScript types for docs-map.json — the BOM manifest for
+ * Tiefenstrukturiertes Dokument (TSD) architecture.
+ *
+ * Schema decisions: SPIKE-036 ADR-S2-06 (position removed — derive at runtime),
+ * ADR-S2-07 (level removed — derive from tree depth), ADR-S2-08 (devsteps_items
+ * promoted to string[]), ADR-S2-10 (.devsteps/ placement), ADR-S2-12 (ARCH-NNN
+ * is manifest-only key, never a DevSteps ItemType),
+ * ADR-007 (JSON adjacency list — parent_id + order replace children[]).
+ */
+/**
+ * A single node in the BOM manifest adjacency list.
+ *
+ * - `id`        Stable ARCH-NNN identifier. Never registered in generateItemId().
+ * - `doc_id`    DOC-NNN item that contains this section (optional for roots that
+ *               span multiple files or future composite docs).
+ * - `parent_id` ARCH-NNN of the parent node, or null for root nodes.
+ *               Enables adjacency-list format and safe reorganisation.
+ * - `order`     Sort order within siblings (gap numbering: 10, 20, 30).
+ *               Insert a new node at 15 without renaming existing nodes.
+ * - `title`     Section heading text (mirrors H1–H4 in the TSD file).
+ * - `description` Optional human note for editorial context.
+ * - `devsteps_items` DevSteps work-item IDs traceable to this section (any type).
+ * - `tsd_heading_depth_max` Hard ceiling for heading rendering in this subtree.
+ *   Overrides the global slider if lower. Default: no override.
+ * - `default_depth` Default Depth View zoom level (1–4) shown when the user
+ *   opens this node's doc in VS Code preview. Presentation hint only.
+ */
+/**
+ * What an upsert names: the id and the parent (null for a root), and any other field to set.
+ * On an update every omitted field keeps its stored value (BUG-168).
+ */
+export type DocsMapNodeUpsert = Pick<DocsMapNode, 'id' | 'parent_id'> & Partial<Omit<DocsMapNode, 'id' | 'parent_id'>>;
+export interface DocsMapNode {
+    /** Stable BOM position code, e.g. "ARCH-001". Never a DevSteps work-item ID. */
+    id: string;
+    /** Optional DOC-NNN work-item that owns this section. */
+    doc_id?: string;
+    /** Parent node ID, or null for root-level nodes. */
+    parent_id: string | null;
+    /** Sort order within siblings. Gap numbering (10, 20, 30) is recommended. */
+    order: number;
+    /** Section heading text. */
+    title: string;
+    /** Optional human note for editorial context. */
+    description?: string;
+    /** DevSteps work-item IDs documented by or traceable to this section. */
+    devsteps_items: string[];
+    /**
+     * Maximum heading depth rendered in this subtree (1 = H1 only, 4 = H1–H4).
+     * Overrides slider ceiling when set. Absent = no override.
+     */
+    tsd_heading_depth_max?: number;
+    /**
+     * Default zoom level when the VS Code Depth View opens this doc.
+     * Presentation hint — not stored in work-item metadata.
+     */
+    default_depth?: 1 | 2 | 3 | 4;
+    /** Handbook type classification — e.g. 'arch', 'user', 'dev', 'ops'. */
+    handbook_type?: string;
+    /** Optional variant discriminator — e.g. 'enterprise', 'devsteps'. */
+    variant?: string;
+}
+/**
+ * Top-level docs-map.json document structure.
+ * The `nodes` array is a flat adjacency list of all BOM entries.
+ * Tree structure is derived via parent_id + order at runtime.
+ */
+export interface DocsMapDocument {
+    /** Schema version for future migration guards. */
+    version: string;
+    /** Flat adjacency list of all BOM nodes (not a nested tree). */
+    nodes: DocsMapNode[];
+}
+/**
+ * Flat position shadow entry written to .devsteps/index/docs-map-positions.json.
+ * Enables O(1) cross-reference queries without full JSON parse on every request.
+ */
+export interface DocsMapPositionEntry {
+    /** ARCH-NNN BOM position code. */
+    id: string;
+    /** DOC-NNN work-item that owns this section. */
+    doc_id?: string;
+    /** Parent node ID — direct copy of DocsMapNode.parent_id. */
+    parent_arch_id: string | null;
+    /** Section heading text. */
+    title: string;
+    /** DevSteps work-item IDs for this section. */
+    devsteps_items: string[];
+    /**
+     * Dot-notation structural position, e.g. "1.2.3".
+     * Derived from adjacency-list traversal — NOT stored in docs-map.json.
+     */
+    position: string;
+    /** Zero-based depth in the tree (root = 0). Derived from parent_id chain. */
+    depth: number;
+}
+/**
+ * Contents of .devsteps/index/docs-map-positions.json.
+ */
+export interface DocsMapPositionsIndex {
+    /** ISO 8601 timestamp of last write. */
+    updated: string;
+    /** Flat array of all BOM entries with derived position + depth. */
+    entries: DocsMapPositionEntry[];
+}
+//# sourceMappingURL=docs-map.d.ts.map

package/dist/types/docs-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-map.d.ts","sourceRoot":"","sources":["../../src/types/docs-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,WAAW,CAAC,GACnE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC"}

package/dist/types/docs-map.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TypeScript types for docs-map.json — the BOM manifest for
+ * Tiefenstrukturiertes Dokument (TSD) architecture.
+ *
+ * Schema decisions: SPIKE-036 ADR-S2-06 (position removed — derive at runtime),
+ * ADR-S2-07 (level removed — derive from tree depth), ADR-S2-08 (devsteps_items
+ * promoted to string[]), ADR-S2-10 (.devsteps/ placement), ADR-S2-12 (ARCH-NNN
+ * is manifest-only key, never a DevSteps ItemType),
+ * ADR-007 (JSON adjacency list — parent_id + order replace children[]).
+ */
+export {};
+//# sourceMappingURL=docs-map.js.map

package/dist/types/docs-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-map.js","sourceRoot":"","sources":["../../src/types/docs-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/types/index-refs.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-refs.types.d.ts","sourceRoot":"","sources":["../../src/types/index-refs.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IAEjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,aAAa;IAC9C,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAEhC,qEAAqE;IACrE,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IAEpC,qDAAqD;IACrD,UAAU,EAAE,GAAG,CAAC,kBAAkB,EAAE,MAAM,EAAE,CAAC,CAAC;IAE9C,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IAEb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IAEf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IAEjB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IAEnB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IAEjB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;IAC1B,2BAA2B;mBAUtB,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE7B,6BAA6B;qBAUxB,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC;IAE/B,+BAA+B;uBAM1B,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;OAKG;;IAGH;;OAEG;;;;;;CAMK,CAAC"}
+{"version":3,"file":"index-refs.types.d.ts","sourceRoot":"","sources":["../../src/types/index-refs.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IAEjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,aAAa;IAC9C,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,MAAM,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAEhC,qEAAqE;IACrE,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IAEpC,qDAAqD;IACrD,UAAU,EAAE,GAAG,CAAC,kBAAkB,EAAE,MAAM,EAAE,CAAC,CAAC;IAE9C,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IAEb,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IAEf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IAEjB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IAEnB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IAEjB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,eAAe;IAC1B,2BAA2B;aAC3B,IAAI,EAUC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE7B,6BAA6B;aAC7B,MAAM,EASD,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC;IAE/B,+BAA+B;aAC/B,QAAQ,EAKH,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;OAKG;aACH,oBAAoB;IAEpB;;OAEG;aACH,WAAW;iBACT,eAAe,EAAE,EAAE;iBACnB,iBAAiB,EAAE,EAAE;iBACrB,aAAa,EAAE,GAAG;;CAEZ,CAAC"}

package/dist/types/index-refs.types.js

@@ -31,6 +31,7 @@ export const INDEX_FILENAMES = {
         bug: 'bugs.json',
         spike: 'spikes.json',
         test: 'tests.json',
+        doc: 'docs.json',
     },
     /** Status index filenames */
     STATUS: {