@izkac/forgekit 0.3.12 → 0.3.14

package/vendor/templates/adr/decisions.md

@@ -1,141 +1,141 @@
-# Architecture decision records (ADRs)
-
-> How this project captures **architectural** decisions. ADRs live next to OpenSpec
-> archives. Scaffolded by Forgekit (`forge init --adr` / `forgekit install` with ADRs on).
-
-ADR directory for this project: **`{{ADR_DIR}}`** (configured in `.forge/config.json`).
-
----
-
-## 1. Why ADRs *and* OpenSpec archives?
-
-They overlap in “why we did something,” but they serve different lookups:
-
-| OpenSpec archive (verbose) | ADR (short) |
-| -------------------------- | ----------- |
-| `proposal.md`, `design.md`, `tasks.md`, specs | One file, one sharpened decision |
-| “Replay the implementation story” | “Why is X shaped this way?” |
-
----
-
-## 2. When to write an ADR
-
-| Write an ADR when the change … | Skip the ADR when … |
-| ------------------------------ | ------------------- |
-| Establishes or moves a boundary | Bug fix / copy / docs-only |
-| Chooses among real alternatives | Refactor that changes no decision |
-| Adds a constraint future code must follow | Chore rename without semantics |
-| Picks a costly-to-swap vendor or protocol | Narrow feature inside a prior ADR |
-| Codifies a convention across the repo | Noise would drown readers |
-
-If you’re listing code edits, that belongs in `design.md`—not an ADR.
-
----
-
-## 3. Format (`{{ADR_DIR}}/NNNN-short-topic.md`)
-
-```markdown
-# NNNN. <Short, decision-shaped title>
-
-- **Status**: Proposed | Accepted | Superseded by ADR-NNNN (…)
-- **Date**: YYYY-MM-DD
-- **Area**: <product or layer>
-- **Related**: openspec/changes/archive/<change>/, …
-
-## Context
-
-One paragraph: pressure or constraint forcing a decision.
-
-## Decision
-
-One imperative paragraph stating what this project commits to.
-
-## Alternatives considered
-
-- **Option A** — rejected because …
-- **Chosen** — …
-
-## Consequences
-
-### Positive
-### Negative
-### Neutral
-
-## References
-
-- Archive: openspec/changes/archive/<name>/
-```
-
-Keep ADRs terse (roughly tens to low hundreds of lines each).
-
----
-
-## 4. Numbering
-
-- Sequential `NNNN`; never recycle numbers—supersede with a **new** ADR.
-- Prefer decision-shaped filenames: `0004-outbox-only-on-critical-path.md` not `0004-add-worker.md`.
-
-All ADRs sit under **`{{ADR_DIR}}/`** even when scoped to one area—the decision
-usually crosses layers.
-
----
-
-## 5. Status index (`{{ADR_DIR}}/README.md`)
-
-Maintain the table of `#`, Title, Status, Date. Leave placeholder rows until real ADRs land.
-
----
-
-## 6. Cross-link OpenSpec ↔ ADRs
-
-ADR **References** should point at the dated archive folder.
-
-Archived `proposal.md` should gain:
-
-```markdown
-## Decision record
-
-This change is recorded as ADR-NNNN ({{ADR_DIR}}/NNNN-short-topic.md).
-```
-
-Or, for non-architectural archives, the one-line stamp:
-
-```text
-No ADR — non-architectural change
-```
-
-Capability specs may cite ADRs as normative “why.”
-
----
-
-## 7. ADRs in agent retrieval
-
-Short, focused ADRs embed well. **Do not** add `{{ADR_DIR}}/` to
-`.cursorindexignore` (or equivalent).
-
----
-
-## 7a. Hooks: archive → ADR
-
-When ADR wiring is enabled, archive hooks remind agents to run **archive-to-adr**
-after `openspec archive` or a move into `openspec/changes/archive/YYYY-MM-DD-…`.
-
-Session-start backstops list archives whose `proposal.md` lacks `ADR-[0-9]` **and**
-lacks the `No ADR — non-architectural change` stamp.
-
----
-
-## 8. Maintenance habit
-
-- On each meaningful archive: decide ADR vs stamp.
-- Periodically skim the index for stale status.
-- Supersede with new ADRs—don’t delete old ones.
-
----
-
-## 9. TL;DR
-
-- ADRs **distill** decisions; OpenSpec archives keep the **full** story.
-- Use this file + `{{ADR_DIR}}/README.md` + `{{ADR_DIR}}/NNNN-*.md`.
-- Cross-link archives and ADRs both directions.
-- After archive: run **archive-to-adr** (or stamp “No ADR”).
+# Architecture decision records (ADRs)
+
+> How this project captures **architectural** decisions. ADRs live next to OpenSpec
+> archives. Scaffolded by Forgekit (`forge init --adr` / `forgekit install` with ADRs on).
+
+ADR directory for this project: **`{{ADR_DIR}}`** (configured in `.forge/config.json`).
+
+---
+
+## 1. Why ADRs *and* OpenSpec archives?
+
+They overlap in “why we did something,” but they serve different lookups:
+
+| OpenSpec archive (verbose) | ADR (short) |
+| -------------------------- | ----------- |
+| `proposal.md`, `design.md`, `tasks.md`, specs | One file, one sharpened decision |
+| “Replay the implementation story” | “Why is X shaped this way?” |
+
+---
+
+## 2. When to write an ADR
+
+| Write an ADR when the change … | Skip the ADR when … |
+| ------------------------------ | ------------------- |
+| Establishes or moves a boundary | Bug fix / copy / docs-only |
+| Chooses among real alternatives | Refactor that changes no decision |
+| Adds a constraint future code must follow | Chore rename without semantics |
+| Picks a costly-to-swap vendor or protocol | Narrow feature inside a prior ADR |
+| Codifies a convention across the repo | Noise would drown readers |
+
+If you’re listing code edits, that belongs in `design.md`—not an ADR.
+
+---
+
+## 3. Format (`{{ADR_DIR}}/NNNN-short-topic.md`)
+
+```markdown
+# NNNN. <Short, decision-shaped title>
+
+- **Status**: Proposed | Accepted | Superseded by ADR-NNNN (…)
+- **Date**: YYYY-MM-DD
+- **Area**: <product or layer>
+- **Related**: openspec/changes/archive/<change>/, …
+
+## Context
+
+One paragraph: pressure or constraint forcing a decision.
+
+## Decision
+
+One imperative paragraph stating what this project commits to.
+
+## Alternatives considered
+
+- **Option A** — rejected because …
+- **Chosen** — …
+
+## Consequences
+
+### Positive
+### Negative
+### Neutral
+
+## References
+
+- Archive: openspec/changes/archive/<name>/
+```
+
+Keep ADRs terse (roughly tens to low hundreds of lines each).
+
+---
+
+## 4. Numbering
+
+- Sequential `NNNN`; never recycle numbers—supersede with a **new** ADR.
+- Prefer decision-shaped filenames: `0004-outbox-only-on-critical-path.md` not `0004-add-worker.md`.
+
+All ADRs sit under **`{{ADR_DIR}}/`** even when scoped to one area—the decision
+usually crosses layers.
+
+---
+
+## 5. Status index (`{{ADR_DIR}}/README.md`)
+
+Maintain the table of `#`, Title, Status, Date. Leave placeholder rows until real ADRs land.
+
+---
+
+## 6. Cross-link OpenSpec ↔ ADRs
+
+ADR **References** should point at the dated archive folder.
+
+Archived `proposal.md` should gain:
+
+```markdown
+## Decision record
+
+This change is recorded as ADR-NNNN ({{ADR_DIR}}/NNNN-short-topic.md).
+```
+
+Or, for non-architectural archives, the one-line stamp:
+
+```text
+No ADR — non-architectural change
+```
+
+Capability specs may cite ADRs as normative “why.”
+
+---
+
+## 7. ADRs in agent retrieval
+
+Short, focused ADRs embed well. **Do not** add `{{ADR_DIR}}/` to
+`.cursorindexignore` (or equivalent).
+
+---
+
+## 7a. Hooks: archive → ADR
+
+When ADR wiring is enabled, archive hooks remind agents to run **archive-to-adr**
+after `openspec archive` or a move into `openspec/changes/archive/YYYY-MM-DD-…`.
+
+Session-start backstops list archives whose `proposal.md` lacks `ADR-[0-9]` **and**
+lacks the `No ADR — non-architectural change` stamp.
+
+---
+
+## 8. Maintenance habit
+
+- On each meaningful archive: decide ADR vs stamp.
+- Periodically skim the index for stale status.
+- Supersede with new ADRs—don’t delete old ones.
+
+---
+
+## 9. TL;DR
+
+- ADRs **distill** decisions; OpenSpec archives keep the **full** story.
+- Use this file + `{{ADR_DIR}}/README.md` + `{{ADR_DIR}}/NNNN-*.md`.
+- Cross-link archives and ADRs both directions.
+- After archive: run **archive-to-adr** (or stamp “No ADR”).

package/vendor/templates/adr/hooks/check-pending-adrs.mjs

@@ -1,74 +1,74 @@
-#!/usr/bin/env node
-/**
- * Pending-ADR backstop: list archived proposals missing ADR link and No-ADR stamp.
- * Honors .forge/config.json adr.enabled === false.
- *
- * Usage: node check-pending-adrs.mjs [repoRoot]
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-
-function gitRoot() {
-  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], {
-    encoding: 'utf8',
-    shell: process.platform === 'win32',
-  });
-  if (r.status !== 0) return null;
-  return String(r.stdout || '').trim() || null;
-}
-
-function loadConfig(cwd) {
-  const p = path.join(cwd, '.forge', 'config.json');
-  if (!fs.existsSync(p)) return {};
-  try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-function listProposals(cwd, archiveRoot) {
-  const dir = path.join(cwd, ...archiveRoot.split('/'));
-  if (!fs.existsSync(dir)) return [];
-  /** @type {string[]} */
-  const out = [];
-  for (const name of fs.readdirSync(dir)) {
-    const proposal = path.join(dir, name, 'proposal.md');
-    if (fs.existsSync(proposal)) out.push(proposal);
-  }
-  return out;
-}
-
-const cwd = process.argv[2] || gitRoot();
-if (!cwd) process.exit(0);
-
-const cfg = loadConfig(cwd);
-if (cfg.adr && cfg.adr.enabled === false) process.exit(0);
-
-const archives = [
-  'openspec/changes/archive',
-  `${(cfg.plan && typeof cfg.plan === 'object' && cfg.plan.dir) || 'specs'}/changes/archive`,
-];
-/** @type {string[]} */
-const pending = [];
-for (const root of archives) {
-  for (const proposal of listProposals(cwd, root)) {
-    const body = fs.readFileSync(proposal, 'utf8');
-    if (/ADR-[0-9]/.test(body)) continue;
-    if (body.includes('No ADR — non-architectural change')) continue;
-    pending.push(path.relative(cwd, proposal).replace(/\\/g, '/'));
-  }
-}
-
-if (pending.length === 0) process.exit(0);
-
-const shown = pending.slice(0, 10).join('\n');
-process.stdout.write(
-  `Archived changes whose proposal.md does not reference an ADR yet:\n\n${shown}\n\n` +
-    `If any had architectural impact, run the archive-to-adr skill.\n` +
-    `Otherwise add a one-line stamp to each proposal.md:\n` +
-    `  'No ADR — non-architectural change'\n`,
-);
-process.exit(0);
+#!/usr/bin/env node
+/**
+ * Pending-ADR backstop: list archived proposals missing ADR link and No-ADR stamp.
+ * Honors .forge/config.json adr.enabled === false.
+ *
+ * Usage: node check-pending-adrs.mjs [repoRoot]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+function gitRoot() {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  if (r.status !== 0) return null;
+  return String(r.stdout || '').trim() || null;
+}
+
+function loadConfig(cwd) {
+  const p = path.join(cwd, '.forge', 'config.json');
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function listProposals(cwd, archiveRoot) {
+  const dir = path.join(cwd, ...archiveRoot.split('/'));
+  if (!fs.existsSync(dir)) return [];
+  /** @type {string[]} */
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const proposal = path.join(dir, name, 'proposal.md');
+    if (fs.existsSync(proposal)) out.push(proposal);
+  }
+  return out;
+}
+
+const cwd = process.argv[2] || gitRoot();
+if (!cwd) process.exit(0);
+
+const cfg = loadConfig(cwd);
+if (cfg.adr && cfg.adr.enabled === false) process.exit(0);
+
+const archives = [
+  'openspec/changes/archive',
+  `${(cfg.plan && typeof cfg.plan === 'object' && cfg.plan.dir) || 'specs'}/changes/archive`,
+];
+/** @type {string[]} */
+const pending = [];
+for (const root of archives) {
+  for (const proposal of listProposals(cwd, root)) {
+    const body = fs.readFileSync(proposal, 'utf8');
+    if (/ADR-[0-9]/.test(body)) continue;
+    if (body.includes('No ADR — non-architectural change')) continue;
+    pending.push(path.relative(cwd, proposal).replace(/\\/g, '/'));
+  }
+}
+
+if (pending.length === 0) process.exit(0);
+
+const shown = pending.slice(0, 10).join('\n');
+process.stdout.write(
+  `Archived changes whose proposal.md does not reference an ADR yet:\n\n${shown}\n\n` +
+    `If any had architectural impact, run the archive-to-adr skill.\n` +
+    `Otherwise add a one-line stamp to each proposal.md:\n` +
+    `  'No ADR — non-architectural change'\n`,
+);
+process.exit(0);

package/vendor/templates/adr/hooks/check-pending-adrs.sh

@@ -1,3 +1,3 @@
-#!/usr/bin/env bash
-# Thin wrapper around the Node implementation.
-exec node "$(dirname "$0")/check-pending-adrs.mjs" "$@"
+#!/usr/bin/env bash
+# Thin wrapper around the Node implementation.
+exec node "$(dirname "$0")/check-pending-adrs.mjs" "$@"

package/vendor/templates/adr/hooks/openspec-archive-agent-message.mjs

@@ -1,52 +1,52 @@
-#!/usr/bin/env node
-/**
- * Agent reminder after a successful change archive (stdout only).
- * Usage: node openspec-archive-agent-message.mjs <change-slug>
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-
-const changeName = process.argv[2];
-if (!changeName) {
-  process.stderr.write('Usage: openspec-archive-agent-message.mjs <change-slug>\n');
-  process.exit(1);
-}
-
-let adrDir = 'docs/adr';
-let decisionsDoc = 'docs/decisions.md';
-let archiveRoot = 'openspec/changes/archive';
-let adrEnabled = true;
-
-const cfgPath = path.join(process.cwd(), '.forge', 'config.json');
-if (fs.existsSync(cfgPath)) {
-  try {
-    const c = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-    if (c.plan?.engine === 'specs') {
-      archiveRoot = `${c.plan.dir || 'specs'}/changes/archive`;
-    }
-    if (c.adr?.enabled === false) adrEnabled = false;
-    if (c.adr?.dir) adrDir = c.adr.dir;
-    if (c.adr?.decisionsDoc) decisionsDoc = c.adr.decisionsDoc;
-  } catch {
-    // keep defaults
-  }
-}
-
-if (!adrEnabled) {
-  process.stdout.write(
-    `Change '${changeName}' was archived. ADRs are disabled for this project\n` +
-      `(\`.forge/config.json\` → adr.enabled: false). No archive-to-adr follow-up.\n\n` +
-      `Suggested commit (display only — do NOT commit unless the user asks):\n\n` +
-      `openspec: archive ${changeName}\n`,
-  );
-  process.exit(0);
-}
-
-process.stdout.write(
-  `Change '${changeName}' was just archived.\n\n` +
-    `1. archive-to-adr: locate ${archiveRoot}/YYYY-MM-DD-${changeName}/, open proposal.md, and evaluate an ADR (${decisionsDoc}). If yes: ${adrDir}/NNNN-<topic>.md, update ${adrDir}/README.md, add a ## Decision record to proposal.md. If no: add one line to proposal.md: No ADR — non-architectural change.\n\n` +
-    `2. Suggested commit (display only — do NOT run git commit / push / gh pr create unless the user explicitly asks):\n\n` +
-    `openspec: archive ${changeName}\n`,
-);
-process.exit(0);
+#!/usr/bin/env node
+/**
+ * Agent reminder after a successful change archive (stdout only).
+ * Usage: node openspec-archive-agent-message.mjs <change-slug>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const changeName = process.argv[2];
+if (!changeName) {
+  process.stderr.write('Usage: openspec-archive-agent-message.mjs <change-slug>\n');
+  process.exit(1);
+}
+
+let adrDir = 'docs/adr';
+let decisionsDoc = 'docs/decisions.md';
+let archiveRoot = 'openspec/changes/archive';
+let adrEnabled = true;
+
+const cfgPath = path.join(process.cwd(), '.forge', 'config.json');
+if (fs.existsSync(cfgPath)) {
+  try {
+    const c = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    if (c.plan?.engine === 'specs') {
+      archiveRoot = `${c.plan.dir || 'specs'}/changes/archive`;
+    }
+    if (c.adr?.enabled === false) adrEnabled = false;
+    if (c.adr?.dir) adrDir = c.adr.dir;
+    if (c.adr?.decisionsDoc) decisionsDoc = c.adr.decisionsDoc;
+  } catch {
+    // keep defaults
+  }
+}
+
+if (!adrEnabled) {
+  process.stdout.write(
+    `Change '${changeName}' was archived. ADRs are disabled for this project\n` +
+      `(\`.forge/config.json\` → adr.enabled: false). No archive-to-adr follow-up.\n\n` +
+      `Suggested commit (display only — do NOT commit unless the user asks):\n\n` +
+      `openspec: archive ${changeName}\n`,
+  );
+  process.exit(0);
+}
+
+process.stdout.write(
+  `Change '${changeName}' was just archived.\n\n` +
+    `1. archive-to-adr: locate ${archiveRoot}/YYYY-MM-DD-${changeName}/, open proposal.md, and evaluate an ADR (${decisionsDoc}). If yes: ${adrDir}/NNNN-<topic>.md, update ${adrDir}/README.md, add a ## Decision record to proposal.md. If no: add one line to proposal.md: No ADR — non-architectural change.\n\n` +
+    `2. Suggested commit (display only — do NOT run git commit / push / gh pr create unless the user explicitly asks):\n\n` +
+    `openspec: archive ${changeName}\n`,
+);
+process.exit(0);

package/vendor/templates/adr/hooks/openspec-archive-agent-message.sh

@@ -1,3 +1,3 @@
-#!/usr/bin/env bash
-# Thin wrapper around the Node implementation.
-exec node "$(dirname "$0")/openspec-archive-agent-message.mjs" "$@"
+#!/usr/bin/env bash
+# Thin wrapper around the Node implementation.
+exec node "$(dirname "$0")/openspec-archive-agent-message.mjs" "$@"