@stdd/plugin 0.9.0

package/runtime/sdk/path.mjs

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertPrintableSingleLine } from "./text.mjs";
+
+const SAFE_SKILL_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+/** Validate the directory name used by agent skill adapters. */
+export function assertSkillName(name, label = "playbook name") {
+	if (typeof name !== "string" || !SAFE_SKILL_NAME.test(name)) {
+		throw new Error(
+			`${label} must be a safe lowercase skill name matching ${SAFE_SKILL_NAME}, got ${JSON.stringify(name)}`,
+		);
+	}
+	return name;
+}
+
+/**
+ * Validate a slash-normalized repository-relative path at the shared
+ * printable-text boundary before applying lexical containment rules.
+ */
+export function assertRepoRelativePath(relative, label = "path") {
+	const candidate = assertPrintableSingleLine(relative, label);
+	if (candidate.includes("\\") || path.posix.isAbsolute(candidate) || path.win32.isAbsolute(candidate)) {
+		throw new Error(`${label} must be a safe repository-relative path: ${JSON.stringify(candidate)}`);
+	}
+	const segments = candidate.split("/");
+	if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+		throw new Error(`${label} must be a safe repository-relative path: ${JSON.stringify(candidate)}`);
+	}
+	return candidate;
+}
+
+/**
+ * Resolve a validated repository-relative path below the supplied root.
+ */
+export function resolveRepoPath(root, relative, label = "path") {
+	const candidate = assertRepoRelativePath(relative, label);
+	const segments = candidate.split("/");
+	const absoluteRoot = path.resolve(root);
+	const target = path.resolve(absoluteRoot, ...segments);
+	const fromRoot = path.relative(absoluteRoot, target);
+	if (fromRoot === ".." || fromRoot.startsWith(`..${path.sep}`) || path.isAbsolute(fromRoot)) {
+		throw new Error(`${label} must be a safe repository-relative path: ${JSON.stringify(candidate)}`);
+	}
+	return target;
+}
+
+/**
+ * The write/delete variant also rejects an existing symlink anywhere below
+ * the repository root, so lexical containment cannot be redirected outside.
+ */
+export function resolveWritableRepoPath(root, relative, label = "path") {
+	const absoluteRoot = path.resolve(root);
+	const target = resolveRepoPath(absoluteRoot, relative, label);
+	let cursor = absoluteRoot;
+	for (const segment of path.relative(absoluteRoot, target).split(path.sep)) {
+		if (!segment) continue;
+		cursor = path.join(cursor, segment);
+		let observed;
+		try {
+			observed = fs.lstatSync(cursor);
+		} catch (err) {
+			if (err.code === "ENOENT") continue;
+			throw err;
+		}
+		if (observed.isSymbolicLink()) {
+			throw new Error(`${label} crosses a symlink and is unsafe to write: ${JSON.stringify(relative)}`);
+		}
+	}
+	return target;
+}

package/runtime/sdk/text.mjs

@@ -0,0 +1,42 @@
+/** Shared boundary for identifiers and inline text that may reach logs or generated files. */
+const CONTROL_OR_SEPARATOR = /[\p{Cc}\p{Cs}\p{Zl}\p{Zp}\p{Bidi_Control}]/u;
+
+// Fixed instead of `\p{Cf}`: join controls, variation selectors, emoji tags,
+// and visible script formatting remain valid ordinary Unicode.
+const INVISIBLE_FORMAT_CONTROL =
+	/(?:\u00ad|\u034f|\u180e|\u200b|[\u2060-\u206f]|\ufeff|[\ufff9-\ufffb]|[\u{1bca0}-\u{1bcaf}]|[\u{1d173}-\u{1d17a}]|\u{e0001})/u;
+
+function isNonPrintableSingleLineScalar(value) {
+	return CONTROL_OR_SEPARATOR.test(value) || INVISIBLE_FORMAT_CONTROL.test(value);
+}
+
+/** Escape only scalars that could split, repaint, hide, or reorder one displayed line. */
+export function escapeNonPrintableSingleLine(value) {
+	if (typeof value !== "string") {
+		throw new TypeError("value must be a string");
+	}
+	let escaped = "";
+	for (const scalar of value) {
+		if (!isNonPrintableSingleLineScalar(scalar)) {
+			escaped += scalar;
+			continue;
+		}
+		const codePoint = scalar.codePointAt(0);
+		escaped +=
+			codePoint <= 0xffff
+				? `\\u${codePoint.toString(16).padStart(4, "0")}`
+				: `\\u{${codePoint.toString(16)}}`;
+	}
+	return escaped;
+}
+
+export function isPrintableSingleLine(value) {
+	return typeof value === "string" && value.trim() !== "" && !isNonPrintableSingleLineScalar(value);
+}
+
+export function assertPrintableSingleLine(value, label = "value") {
+	if (!isPrintableSingleLine(value)) {
+		throw new TypeError(`${label} must be a non-empty single printable line`);
+	}
+	return value;
+}

package/runtime/sdk/workflow.mjs

@@ -0,0 +1,294 @@
+import { isPrintableSingleLine } from "./text.mjs";
+
+function isCanonicalIsoTimestamp(value) {
+	if (!isPrintableSingleLine(value)) return false;
+	try {
+		return new Date(value).toISOString() === value;
+	} catch {
+		return false;
+	}
+}
+
+function isPlainRecord(value) {
+	if (typeof value !== "object" || value === null) return false;
+	try {
+		const prototype = Object.getPrototypeOf(value);
+		return prototype === Object.prototype || prototype === null;
+	} catch {
+		return false;
+	}
+}
+
+function invalidTaskState(reason, boundary = null) {
+	return { state: "invalid", task: null, boundary, reason };
+}
+
+function snapshotEventRecord(event, index) {
+	if (!isPlainRecord(event)) {
+		return {
+			invalid: invalidTaskState(`task event at index ${index} must be a plain record object`, event),
+		};
+	}
+	let descriptors;
+	try {
+		descriptors = Object.getOwnPropertyDescriptors(event);
+	} catch {
+		return {
+			invalid: invalidTaskState(
+				`task event at index ${index} could not be safely inspected as a plain record object`,
+				event,
+			),
+		};
+	}
+	const data = Object.create(null);
+	for (const key of Reflect.ownKeys(descriptors)) {
+		const descriptor = descriptors[key];
+		if (!Object.hasOwn(descriptor, "value")) {
+			return {
+				invalid: invalidTaskState(
+					`task event at index ${index} property ${String(key)} is an accessor; accessors are not allowed`,
+					event,
+				),
+			};
+		}
+		if (typeof key === "string" && descriptor.enumerable) data[key] = descriptor.value;
+	}
+	return { record: { original: event, data } };
+}
+
+function snapshotTaskEvents(events) {
+	let array;
+	try {
+		array = Array.isArray(events);
+	} catch {
+		return { invalid: invalidTaskState("task events could not be safely inspected as an array") };
+	}
+	if (!array) return { invalid: invalidTaskState("task events must be an array") };
+	let descriptors;
+	try {
+		descriptors = Object.getOwnPropertyDescriptors(events);
+	} catch {
+		return { invalid: invalidTaskState("task events could not be safely inspected as an array") };
+	}
+	const lengthDescriptor = descriptors.length;
+	if (
+		!lengthDescriptor ||
+		!Object.hasOwn(lengthDescriptor, "value") ||
+		!Number.isSafeInteger(lengthDescriptor.value) ||
+		lengthDescriptor.value < 0
+	) {
+		return { invalid: invalidTaskState("task events must expose a safe data length") };
+	}
+	const records = [];
+	for (let index = 0; index < lengthDescriptor.value; index++) {
+		const descriptor = descriptors[String(index)];
+		if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value")) {
+			return {
+				invalid: invalidTaskState(
+					`task event at index ${index} must be an own enumerable data property`,
+				),
+			};
+		}
+		const snapshot = snapshotEventRecord(descriptor.value, index);
+		if (snapshot.invalid) return snapshot;
+		records.push(snapshot.record);
+	}
+	return { records };
+}
+
+/**
+ * Pure loop derivation shared by the CLI and integrations. Snapshots are
+ * opaque equality tokens; callers decide how a checkout is fingerprinted.
+ */
+export function deriveLoopState(events, currentSnapshot, nonDocChanged = false) {
+	const lastRedIdx = events.findLastIndex(
+		(event) => event.event === "red" && event.exit !== 0 && event.genuine !== "no",
+	);
+	const redEvent = lastRedIdx === -1 ? null : events[lastRedIdx];
+	const recordedVerify =
+		events
+			.slice(lastRedIdx + 1)
+			.filter((event) => event.event === "verify" && event.exit === 0)
+			.at(-1) ?? null;
+	const redImported = Boolean(redEvent?.workerId);
+	const redLegacy = Boolean(redEvent && !redEvent.snapshot && !redImported);
+	const implementationObserved = redEvent
+		? redImported || redLegacy
+			? nonDocChanged
+			: redEvent.snapshot !== currentSnapshot
+		: false;
+	const verifyStale = Boolean(
+		recordedVerify?.workerId ||
+			(recordedVerify?.snapshot && recordedVerify.snapshot !== currentSnapshot),
+	);
+	const verifyEvent = verifyStale ? null : recordedVerify;
+	return {
+		lastRedIdx,
+		redEvent,
+		redLegacy,
+		recordedVerify,
+		verifyEvent,
+		verifyStale,
+		implementationObserved,
+		loop: {
+			red: redEvent
+				? {
+						done: true,
+						genuine: redEvent.genuine,
+						cmd: redEvent.cmd,
+						exit: redEvent.exit,
+						legacy: redLegacy,
+						...(redImported ? { imported: true } : {}),
+					}
+				: { done: false },
+			impl: { done: implementationObserved },
+			verify: verifyEvent
+				? {
+						done: true,
+						cmd: verifyEvent.cmd,
+						exit: verifyEvent.exit,
+						legacy: !verifyEvent.snapshot,
+						stale: false,
+					}
+				: { done: false, stale: verifyStale },
+		},
+	};
+}
+
+function deriveTaskStateFromRecords(records) {
+	const boundaries = records.filter(
+		({ data }) =>
+			data.event === "task-start" || data.event === "task-finish" || data.event === "task-reset",
+	);
+	if (boundaries.length === 0) return { state: "legacy", task: null };
+	let state = { state: "idle", task: null, boundary: null };
+	const seenTaskIds = new Set();
+	for (const { original, data: boundary } of boundaries) {
+		const boundaryId = boundary.event === "task-start" ? boundary.id : boundary.taskId;
+		if (!isPrintableSingleLine(boundaryId)) {
+			return {
+				state: "invalid",
+				task: null,
+				boundary: original,
+				reason: `${boundary.event} needs a non-empty ${
+					boundary.event === "task-start" ? "id" : "taskId"
+				} that is a single printable line`,
+			};
+		}
+		if (boundary.branch !== undefined && !isPrintableSingleLine(boundary.branch)) {
+			return {
+				state: "invalid",
+				task: null,
+				boundary: original,
+				reason: `${boundary.event} branch must be a non-empty single printable line when present`,
+			};
+		}
+		if (boundary.ts !== undefined && !isCanonicalIsoTimestamp(boundary.ts)) {
+			return {
+				state: "invalid",
+				task: null,
+				boundary: original,
+				reason: `${boundary.event} timestamp must be a canonical ISO timestamp when present`,
+			};
+		}
+		if (boundary.event === "task-start") {
+			if (seenTaskIds.has(boundaryId)) {
+				return {
+					state: "invalid",
+					task: null,
+					boundary: original,
+					reason: `task-start reuses task ID ${boundaryId}`,
+				};
+			}
+			if (state.state === "active") {
+				return {
+					state: "invalid",
+					task: null,
+					boundary: original,
+					reason: `task-start ${boundaryId} cannot replace active task ${state.task.id}`,
+				};
+			}
+			if (!isPrintableSingleLine(boundary.name)) {
+				return {
+					state: "invalid",
+					task: null,
+					boundary: original,
+					reason: "task-start name is required and must be a non-empty single printable line",
+				};
+			}
+			if (
+				!Object.hasOwn(boundary, "planBaseline") ||
+				(boundary.planBaseline !== null &&
+					(typeof boundary.planBaseline !== "string" ||
+						!/^sha256:[0-9a-f]{64}$/u.test(boundary.planBaseline)))
+			) {
+				return {
+					state: "invalid",
+					task: null,
+					boundary: original,
+					reason: "task-start planBaseline is required and must be a sha256 snapshot or null",
+				};
+			}
+			state = {
+				state: "active",
+				task: {
+					id: boundaryId,
+					name: boundary.name,
+					branch: boundary.branch,
+					startedAt: boundary.ts,
+					planBaseline: boundary.planBaseline ?? null,
+				},
+				boundary: original,
+			};
+			seenTaskIds.add(boundaryId);
+			continue;
+		}
+		if (state.state !== "active") {
+			return {
+				state: "invalid",
+				task: null,
+				boundary: original,
+				reason: `${boundary.event} ${boundaryId} has no active task to close`,
+			};
+		}
+		if (boundaryId !== state.task.id) {
+			return {
+				state: "invalid",
+				task: null,
+				boundary: original,
+				reason: `${boundary.event} names ${boundaryId}, but ${state.task.id} is active`,
+			};
+		}
+		state = { state: "idle", task: null, boundary: original };
+	}
+	return state;
+}
+
+/** Derive the active task boundary without reading files or git state. */
+export function deriveTaskState(events) {
+	const snapshot = snapshotTaskEvents(events);
+	if (snapshot.invalid) return snapshot.invalid;
+	return deriveTaskStateFromRecords(snapshot.records);
+}
+
+/** Keep only the active task's events; legacy branch-only ledgers pass through. */
+export function scopeTaskEvents(events) {
+	const snapshot = snapshotTaskEvents(events);
+	if (snapshot.invalid) return { state: snapshot.invalid, events: [] };
+	const state = deriveTaskStateFromRecords(snapshot.records);
+	if (state.state === "legacy") {
+		return { state, events: snapshot.records.map(({ original }) => original) };
+	}
+	if (state.state === "idle" || state.state === "invalid") return { state, events: [] };
+	const boundaryIndex = snapshot.records.findLastIndex(({ original }) => original === state.boundary);
+	return {
+		state,
+		events: snapshot.records
+			.slice(boundaryIndex)
+			.filter(
+				({ data: event }) =>
+					(event.event === "task-start" && event.id === state.task.id) || event.taskId === state.task.id,
+			)
+			.map(({ original }) => original),
+	};
+}

package/runtime/templates/deferred-design.md

@@ -0,0 +1,47 @@
+# Deferred Design Template
+
+A design for work that is agreed but not yet scheduled. Use this template only
+when `.stdd/config.json` keeps `projectLog.enabled` set to `true`. It lives as
+a **dated entry** in the project log (e.g. `docs/project/`), never as a spec
+file next to canonical docs. When the policy is disabled, keep the design
+outside the tracked tree instead. Delete the entry when the work ships or is
+abandoned.
+
+The frontmatter is mandatory: it is the machine-readable marker that keeps
+agent retrieval authority-aware — canonical docs never carry
+`authority: non-canonical`, project-log entries always do.
+
+```markdown
+---
+authority: non-canonical
+status: deferred
+---
+
+# <Title>
+
+Last updated: <YYYY-MM-DD>
+
+- Status: Deferred | Decision needed | Ready | Blocked
+- Priority: High | Medium | Low
+
+## Problem
+
+<What hurts and who it hurts. Impact if never done.>
+
+## Agreed direction
+
+<The design, as rules precise enough to implement from. Note explicitly that
+this describes FUTURE behavior — canonical docs still describe the present.>
+
+## Why deferred
+
+<The reason it is not being done now.>
+
+## Resume condition
+
+<The concrete trigger that should restart this work.>
+
+## Acceptance criteria
+
+<How we will know it is done.>
+```

package/runtime/templates/github-stdd.yml

@@ -0,0 +1,42 @@
+# __STAMP__
+#
+# Validates the PR body fetched LIVE from the API, not the event payload —
+# the payload is frozen at trigger time, so a body-only edit would never be
+# re-checked. The `edited` trigger re-runs this workflow on body changes.
+name: STDD
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  stdd:
+    name: STDD Contract
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # check-pr --base diffs against the base ref
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: stdd check
+        run: npx --yes @stdd/cli@__VERSION__ check .
+      - name: PR docs evidence (live body)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        # node, not gh: node is already required for stdd, while self-hosted
+        # runners often lack the gh CLI. pipefail: a failed fetch must fail
+        # the gate as a fetch error, not feed check-pr an empty body.
+        run: |
+          set -o pipefail
+          node --input-type=module -e '
+            const url = "https://api.github.com/repos/" + process.env.GITHUB_REPOSITORY + "/pulls/" + process.env.PR_NUMBER;
+            const res = await fetch(url, { headers: { authorization: "Bearer " + process.env.GH_TOKEN, accept: "application/vnd.github+json" } });
+            if (!res.ok) { console.error("GitHub API " + res.status + " for " + url); process.exit(1); }
+            process.stdout.write((await res.json()).body ?? "");
+          ' | npx --yes @stdd/cli@__VERSION__ check-pr - --base "origin/$GITHUB_BASE_REF"

package/runtime/templates/gitlab-stdd.yml

@@ -0,0 +1,72 @@
+# __STAMP__
+#
+# Include this file from the repository's root .gitlab-ci.yml:
+#   include:
+#     - local: .gitlab/stdd.gitlab-ci.yml
+#
+# The job defaults to GitLab's reserved .pre stage, so this include stays valid
+# when a consumer defines custom stages without "test". To run STDD in an
+# existing consumer stage, override the included job in the root .gitlab-ci.yml.
+# The override must name a stage declared by that pipeline:
+#
+# stdd:
+#   stage: verify
+#
+# Same-project merge requests use CI_JOB_TOKEN. A fork pipeline runs in its
+# source project, so the target must allowlist that project under CI/CD job
+# token permissions. Only for a controlled, trusted source project, an
+# optional masked and hidden STDD_GITLAB_READ_API_TOKEN may carry a
+# target-project access token with read_api. Never expose a target token to
+# untrusted fork code.
+stdd:
+  stage: .pre
+  image: node:22
+  variables:
+    GIT_DEPTH: "0"
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  script:
+    - npx --yes @stdd/cli@__VERSION__ check .
+    - |
+      set -o pipefail
+      node --input-type=module -e '
+        const targetProjectId = process.env.CI_MERGE_REQUEST_PROJECT_ID;
+        const pipelineProjectId = process.env.CI_PROJECT_ID;
+        const crossProject = Boolean(
+          pipelineProjectId && targetProjectId && pipelineProjectId !== targetProjectId
+        );
+        const readApiToken = crossProject
+          ? process.env.STDD_GITLAB_READ_API_TOKEN
+          : "";
+        const headers = readApiToken
+          ? { "PRIVATE-TOKEN": readApiToken, accept: "application/json" }
+          : { "JOB-TOKEN": process.env.CI_JOB_TOKEN, accept: "application/json" };
+        const url = process.env.CI_API_V4_URL + "/projects/" +
+          encodeURIComponent(targetProjectId) + "/merge_requests/" +
+          process.env.CI_MERGE_REQUEST_IID;
+        const res = await fetch(url, { headers });
+        if (!res.ok) {
+          console.error("GitLab API " + res.status + " for " + url);
+          if (crossProject && !readApiToken) {
+            console.error(
+              "Fork or cross-project MR pipeline project " + pipelineProjectId +
+              " cannot read target project " + targetProjectId +
+              ". Add pipeline project " + pipelineProjectId +
+              " to the target CI/CD job token allowlist, or only for a trusted source project " +
+              "define masked and hidden STDD_GITLAB_READ_API_TOKEN with target-project read_api."
+            );
+          } else if (crossProject) {
+            console.error(
+              "STDD_GITLAB_READ_API_TOKEN cannot read target project " + targetProjectId +
+              "; verify that it is a target-project token with read_api."
+            );
+          } else {
+            console.error(
+              "The same-project CI_JOB_TOKEN cannot read this merge request; " +
+              "verify the triggering user and job-token permissions."
+            );
+          }
+          process.exit(1);
+        }
+        process.stdout.write((await res.json()).description ?? "");
+      ' | npx --yes @stdd/cli@__VERSION__ check-pr - --base "$CI_MERGE_REQUEST_DIFF_BASE_SHA"

package/runtime/templates/pr-description.md

@@ -0,0 +1,35 @@
+# PR Description Template
+
+The PR description is the durable home for everything that is not a rule:
+rationale, scope decisions, rejected alternatives. Copy, fill, delete unused
+sections.
+
+```markdown
+## Why
+
+<The problem, one paragraph. Link the discussion if there was one.>
+
+## What changed
+
+<Behavior first, implementation second. Bullets.>
+
+## Decisions and alternatives
+
+<Choices made and what was rejected, with the reason. This is the section
+future readers will thank you for — it never goes in the docs tree.>
+
+## Out of scope
+
+<What this PR deliberately does not do.>
+
+## Docs evidence
+
+<Exactly one of:>
+Docs updated first: <list of changed docs>
+Docs checked, no change needed: <docs + reason>
+Docs not applicable: <why implementation-only>
+
+## Verification
+
+<Commands run and their results. Screenshots for visual work.>
+```

package/scripts/adopting-root.mjs

@@ -0,0 +1,42 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+function enclosingGitMarkerRoot(start) {
+	let candidate = path.resolve(start);
+	while (true) {
+		try {
+			fs.lstatSync(path.join(candidate, ".git"));
+			return candidate;
+		} catch (error) {
+			if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") return candidate;
+		}
+		const parent = path.dirname(candidate);
+		if (parent === candidate) return null;
+		candidate = parent;
+	}
+}
+
+export function resolveAdoptingRoot(cwd) {
+	const start = path.resolve(cwd);
+	const gitMarkerRoot = enclosingGitMarkerRoot(start);
+	const top = spawnSync("git", ["-C", start, "rev-parse", "--show-toplevel"], {
+		encoding: "utf8",
+	});
+	const gitRootResolved = !top.error && top.status === 0;
+	if (gitRootResolved) {
+		const candidate = top.stdout.trim();
+		const markerMatches =
+			!gitMarkerRoot || path.resolve(gitMarkerRoot) === path.resolve(candidate || ".");
+		return candidate && markerMatches && fs.existsSync(path.join(candidate, ".stdd")) ? candidate : null;
+	}
+	if (gitMarkerRoot) return null;
+
+	let candidate = start;
+	while (true) {
+		if (fs.existsSync(path.join(candidate, ".stdd"))) return candidate;
+		const parent = path.dirname(candidate);
+		if (parent === candidate) return null;
+		candidate = parent;
+	}
+}