workflow-toolkit 1.0.1

package/.agents/skills/wtk-knowledge-check/scripts/check.ts

@@ -0,0 +1,502 @@
+import { execFileSync } from "node:child_process";
+import type { Dirent } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { readFrontmatter } from "./frontmatter.js";
+
+/**
+ * What a finding is about.
+ *
+ * - `conformance`: the bundle breaks one of the three OKF v0.2 conformance rules.
+ * - `drift`: a concept declares a repository source that changed after the concept recorded it.
+ * - `gap`: durable knowledge accumulated in `.specs/` without a concept harvesting it.
+ * - `naming`: a raw source that breaks the `YYYY-MM-DD-<slug>` convention.
+ */
+export type KnowledgeFindingKind = "conformance" | "drift" | "gap" | "naming";
+
+export type KnowledgeFinding = {
+  kind: KnowledgeFindingKind;
+  /** `error` fails the check; `warning` is reported and tolerated. */
+  severity: "error" | "warning";
+  /** Offending file, relative to the scanned root, with forward slashes. */
+  file: string;
+  message: string;
+};
+
+export type CheckKnowledgeOptions = {
+  /** Bundle directory, relative to the root. Defaults to `knowledge/wiki`. */
+  bundle?: string;
+  /** Raw source directory, relative to the root. Defaults to `knowledge/raw`. */
+  raw?: string;
+  /**
+   * Resolves the last change date (`YYYY-MM-DD`) of a repository file, or null when unknown.
+   * Defaults to the author date of the file's last git commit, which a rebase preserves.
+   */
+  sourceLastChanged?: (absolutePath: string) => string | null;
+};
+
+type GitChange = {
+  commit: string;
+  date: string;
+};
+
+/**
+ * The bundle is `knowledge/wiki`, not `knowledge`. Everything inside it must conform, so the
+ * untouched originals in `knowledge/raw` deliberately sit outside it (§11.1 admits no exception
+ * for a markdown file without frontmatter).
+ */
+const DEFAULT_BUNDLE = join("knowledge", "wiki");
+const DEFAULT_RAW = join("knowledge", "raw");
+/** Everything in `raw/` sorts chronologically, so the ISO date leads the name. */
+const RAW_ISO_PREFIX = /^\d{4}-\d{2}-\d{2}-\S/;
+/** The `DD-MM-YYYY` form neither matches the rest of the bundle nor sorts correctly. */
+const RAW_REVERSED_PREFIX = /^\d{2}-\d{2}-\d{4}-/;
+/** Explains the directory itself rather than being a source. */
+const RAW_EXEMPT = new Set(["README.md"]);
+const SKIPPED_DIRECTORIES = new Set(["node_modules", ".git"]);
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const URI_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+const STATE_PATH = join(".specs", "STATE.md");
+const FEATURES_PATH = join(".specs", "features");
+const SPINE_PATH = join("docs", "architecture", "ARCHITECTURE-SPINE.md");
+
+type SourceEntry = {
+  id: string | null;
+  resource: string | null;
+  lastModified: string | null;
+};
+
+function toPosix(path: string): string {
+  return path.split(sep).join("/");
+}
+
+function readSources(data: Record<string, unknown>): SourceEntry[] {
+  const raw = data.sources;
+  if (!Array.isArray(raw)) return [];
+  const entries: SourceEntry[] = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) continue;
+    const entry = item as Record<string, unknown>;
+    entries.push({
+      id: typeof entry.id === "string" ? entry.id : null,
+      resource: typeof entry.resource === "string" ? entry.resource : null,
+      lastModified: typeof entry.last_modified === "string" ? entry.last_modified : null,
+    });
+  }
+  return entries;
+}
+
+function listMarkdownFiles(directory: string): string[] {
+  const files: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+  for (const entry of entries) {
+    if (SKIPPED_DIRECTORIES.has(entry.name)) continue;
+    const full = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...listMarkdownFiles(full));
+    else if (entry.name.endsWith(".md")) files.push(full);
+  }
+  return files;
+}
+
+function listFiles(directory: string): string[] {
+  const files: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+  for (const entry of entries) {
+    if (SKIPPED_DIRECTORIES.has(entry.name)) continue;
+    const full = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...listFiles(full));
+    else files.push(full);
+  }
+  return files;
+}
+
+/**
+ * Raw sources are named `YYYY-MM-DD-<slug>` so a flat directory sorts chronologically. They sit
+ * outside the bundle and so have no OKF conformance to break — this is a house convention, and it
+ * only warns.
+ */
+function checkRawNaming(rootDirectory: string, rawDirectory: string): KnowledgeFinding[] {
+  const findings: KnowledgeFinding[] = [];
+  for (const absoluteFile of listFiles(rawDirectory)) {
+    const name = absoluteFile.slice(absoluteFile.lastIndexOf(sep) + 1);
+    if (RAW_EXEMPT.has(name) || name.startsWith(".")) continue;
+    if (RAW_ISO_PREFIX.test(name)) continue;
+
+    const file = toPosix(relative(rootDirectory, absoluteFile));
+    findings.push({
+      kind: "naming",
+      severity: "warning",
+      file,
+      message: RAW_REVERSED_PREFIX.test(name)
+        ? "dated DD-MM-YYYY; the bundle dates everything ISO 8601, and DD-MM-YYYY does not sort"
+        : "is not prefixed with its ISO date, expected YYYY-MM-DD-<slug>",
+    });
+  }
+  return findings;
+}
+
+function gitLastChange(absolutePath: string): GitChange | null {
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: dirname(absolutePath),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const prefix = execFileSync("git", ["rev-parse", "--show-prefix"], {
+      cwd: dirname(absolutePath),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const path = toPosix(join(prefix, basename(absolutePath)));
+
+    const blobAt = (revision: string): string | null => {
+      try {
+        return execFileSync("git", ["rev-parse", `${revision}:${path}`], {
+          cwd: root,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+      } catch {
+        return null;
+      }
+    };
+
+    const lastChangeAt = (revision: string): GitChange | null => {
+      const stdout = execFileSync(
+        "git",
+        ["log", "-1", "--format=%H%x00%as%x00%P", revision, "--", path],
+        {
+          cwd: root,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+        },
+      );
+      const [commit, date, parentList = ""] = stdout.trim().split("\0");
+      if (commit === undefined || date === undefined || !ISO_DATE.test(date)) return null;
+
+      const parents = parentList.split(" ").filter(Boolean);
+      if (parents.length > 1) {
+        const blob = blobAt(commit);
+        const inherited = parents
+          .filter((parent) => blob !== null && blobAt(parent) === blob)
+          .map(lastChangeAt)
+          .filter((change): change is GitChange => change !== null)
+          .sort((left, right) => right.date.localeCompare(left.date));
+        if (inherited[0] !== undefined) return inherited[0];
+      }
+
+      return { commit, date };
+    };
+
+    return lastChangeAt("HEAD");
+  } catch {
+    return null;
+  }
+}
+
+/** §11.2 — every concept carries a non-empty `type`. */
+function checkConcept(file: string, source: string): KnowledgeFinding[] {
+  const { present, data, error } = readFrontmatter(source);
+  const base = { kind: "conformance", severity: "error", file } as const;
+
+  if (!present) return [{ ...base, message: "concept has no YAML frontmatter block" }];
+  if (data === null) return [{ ...base, message: error ?? "unparseable frontmatter" }];
+
+  const type = data.type;
+  if (typeof type !== "string" || type.trim() === "") {
+    return [{ ...base, message: "frontmatter has no non-empty `type`" }];
+  }
+  return [];
+}
+
+/** §8 — index files carry no frontmatter, except `okf_version` at the bundle root. */
+function checkIndex(file: string, source: string, isBundleRoot: boolean): KnowledgeFinding[] {
+  const { present, data, error } = readFrontmatter(source);
+  if (!present) return [];
+
+  const base = { kind: "conformance", severity: "error", file } as const;
+  if (!isBundleRoot) {
+    return [{ ...base, message: "only the bundle-root index.md may carry frontmatter" }];
+  }
+  if (data === null) return [{ ...base, message: error ?? "unparseable frontmatter" }];
+
+  const extra = Object.keys(data).filter((key) => key !== "okf_version");
+  if (extra.length > 0) {
+    return [
+      {
+        ...base,
+        message: `bundle-root index.md may only declare okf_version, found ${extra.join(", ")}`,
+      },
+    ];
+  }
+  return [];
+}
+
+/** §9 — date-grouped entries under ISO `## YYYY-MM-DD` headings, newest first. */
+function checkLog(file: string, source: string): KnowledgeFinding[] {
+  const findings: KnowledgeFinding[] = [];
+  const base = { kind: "conformance", severity: "error", file } as const;
+
+  if (readFrontmatter(source).present) {
+    findings.push({ ...base, message: "log.md must not carry frontmatter" });
+  }
+
+  const dates: string[] = [];
+  for (const line of source.replace(/\r\n/g, "\n").split("\n")) {
+    if (!line.startsWith("## ")) continue;
+    const heading = line.slice(3).trim();
+    if (!ISO_DATE.test(heading)) {
+      findings.push({ ...base, message: `date heading "${heading}" is not ISO 8601 YYYY-MM-DD` });
+      continue;
+    }
+    dates.push(heading);
+  }
+
+  for (let index = 1; index < dates.length; index += 1) {
+    const previous = dates[index - 1];
+    const current = dates[index];
+    if (previous !== undefined && current !== undefined && current > previous) {
+      findings.push({
+        ...base,
+        message: `${current} appears after ${previous}; entries run newest first`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * A concept's recorded `last_modified` against what the repository says. `sources[].last_modified`
+ * is a recency signal for the *source*, distinct from `generated.at`, which records when the
+ * concept itself was written — so comparing the two detects a source that moved on without the
+ * concept following it.
+ */
+function checkDrift(
+  file: string,
+  absoluteFile: string,
+  rootDirectory: string,
+  bundleDirectory: string,
+  data: Record<string, unknown>,
+  sourceLastChanged: (absolutePath: string, conceptPath: string) => string | null,
+): KnowledgeFinding[] {
+  const findings: KnowledgeFinding[] = [];
+
+  for (const entry of readSources(data)) {
+    const { resource, lastModified } = entry;
+    // A scope descriptor or an external URL is not a path we can stat (§5.1, §6.2).
+    if (resource === null || URI_SCHEME.test(resource)) continue;
+
+    const absoluteSource = resource.startsWith("/")
+      ? join(bundleDirectory, resource.slice(1))
+      : resolve(dirname(absoluteFile), resource);
+
+    // Only repository files are checkable; anything above the root is out of scope.
+    const inside = relative(rootDirectory, absoluteSource);
+    if (inside.startsWith("..") || inside === "") continue;
+
+    if (!existsSync(absoluteSource)) {
+      findings.push({
+        kind: "drift",
+        severity: "warning",
+        file,
+        message: `source "${resource}" does not exist`,
+      });
+      continue;
+    }
+
+    if (lastModified === null) continue;
+    if (!ISO_DATE.test(lastModified)) {
+      findings.push({
+        kind: "conformance",
+        severity: "error",
+        file,
+        message: `source "${resource}" has last_modified "${lastModified}", not YYYY-MM-DD`,
+      });
+      continue;
+    }
+
+    const changed = sourceLastChanged(absoluteSource, absoluteFile);
+    if (changed !== null && changed > lastModified) {
+      findings.push({
+        kind: "drift",
+        severity: "error",
+        file,
+        message: `source "${resource}" changed on ${changed}, concept records ${lastModified}`,
+      });
+    }
+  }
+  return findings;
+}
+
+/** Decisions and verified features that accumulated in `.specs/` without a concept harvesting them. */
+function checkGaps(
+  rootDirectory: string,
+  harvestedIds: Set<string>,
+  harvestedPaths: Set<string>,
+): KnowledgeFinding[] {
+  const findings: KnowledgeFinding[] = [];
+
+  const statePath = join(rootDirectory, STATE_PATH);
+  if (existsSync(statePath)) {
+    const state = readFileSync(statePath, "utf8");
+    const seenStateLabels = new Set<string>();
+    for (const match of state.matchAll(/^### (AD-\d+)\s*$/gm)) {
+      const label = match[1];
+      if (label === undefined) continue;
+      if (seenStateLabels.has(label)) {
+        findings.push({
+          kind: "conformance",
+          severity: "error",
+          file: toPosix(STATE_PATH),
+          message: `${label} appears more than once`,
+        });
+        continue;
+      }
+      seenStateLabels.add(label);
+      if (harvestedIds.has(`state-${label.toLowerCase()}`)) continue;
+      findings.push({
+        kind: "gap",
+        severity: "warning",
+        file: toPosix(STATE_PATH),
+        message: `${label} has no concept; expected a source entry with id "state-${label.toLowerCase()}"`,
+      });
+    }
+  }
+
+  const spinePath = join(rootDirectory, SPINE_PATH);
+  if (existsSync(spinePath)) {
+    const seenSpineLabels = new Set<string>();
+    for (const match of readFileSync(spinePath, "utf8").matchAll(/^### (AD-\d+)\b/gm)) {
+      const label = match[1];
+      if (label === undefined) continue;
+      if (seenSpineLabels.has(label)) {
+        findings.push({
+          kind: "conformance",
+          severity: "error",
+          file: toPosix(SPINE_PATH),
+          message: `${label} appears more than once`,
+        });
+        continue;
+      }
+      seenSpineLabels.add(label);
+    }
+  }
+
+  const featuresPath = join(rootDirectory, FEATURES_PATH);
+  let features: Dirent[];
+  try {
+    features = readdirSync(featuresPath, { withFileTypes: true });
+  } catch {
+    return findings;
+  }
+  for (const feature of features) {
+    if (!feature.isDirectory()) continue;
+    const validation = join(FEATURES_PATH, feature.name, "validation.md");
+    if (!existsSync(join(rootDirectory, validation))) continue;
+    if (harvestedPaths.has(toPosix(validation))) continue;
+    findings.push({
+      kind: "gap",
+      severity: "warning",
+      file: toPosix(validation),
+      message: `feature "${feature.name}" is verified but no concept cites its validation`,
+    });
+  }
+  return findings;
+}
+
+/**
+ * Checks the knowledge bundle for OKF v0.2 conformance, for concepts that drifted from the
+ * repository sources they derive from, and for durable knowledge in `.specs/` that no concept has
+ * harvested yet.
+ */
+export function checkKnowledge(
+  rootDirectory: string,
+  options: CheckKnowledgeOptions = {},
+): KnowledgeFinding[] {
+  const bundleDirectory = join(rootDirectory, options.bundle ?? DEFAULT_BUNDLE);
+  const rawDirectory = join(rootDirectory, options.raw ?? DEFAULT_RAW);
+
+  // Concepts cite the same handful of files over and over, and the default resolver spawns a git
+  // process per call. Memoising keeps a bundle of any size at one lookup per distinct path.
+  const cache = new Map<string, string | null>();
+  const gitCache = new Map<string, GitChange | null>();
+  const sourceLastChanged = (absolutePath: string, conceptPath: string): string | null => {
+    if (options.sourceLastChanged !== undefined) {
+      if (cache.has(absolutePath)) return cache.get(absolutePath) ?? null;
+      const resolved = options.sourceLastChanged(absolutePath);
+      cache.set(absolutePath, resolved);
+      return resolved;
+    }
+
+    const lastChange = (path: string): GitChange | null => {
+      if (gitCache.has(path)) return gitCache.get(path) ?? null;
+      const resolved = gitLastChange(path);
+      gitCache.set(path, resolved);
+      return resolved;
+    };
+    const sourceChange = lastChange(absolutePath);
+    const conceptChange = lastChange(conceptPath);
+    if (sourceChange?.commit === conceptChange?.commit) return null;
+    return sourceChange?.date ?? null;
+  };
+
+  const findings: KnowledgeFinding[] = [];
+  const harvestedIds = new Set<string>();
+  const harvestedPaths = new Set<string>();
+
+  for (const absoluteFile of listMarkdownFiles(bundleDirectory)) {
+    const file = toPosix(relative(rootDirectory, absoluteFile));
+    const name = absoluteFile.slice(absoluteFile.lastIndexOf(sep) + 1);
+    const source = readFileSync(absoluteFile, "utf8");
+
+    if (name === "index.md") {
+      const isBundleRoot = dirname(absoluteFile) === bundleDirectory;
+      findings.push(...checkIndex(file, source, isBundleRoot));
+      continue;
+    }
+    if (name === "log.md") {
+      findings.push(...checkLog(file, source));
+      continue;
+    }
+
+    const conformance = checkConcept(file, source);
+    findings.push(...conformance);
+    if (conformance.length > 0) continue;
+
+    const data = readFrontmatter(source).data;
+    if (data === null) continue;
+
+    for (const entry of readSources(data)) {
+      if (entry.resource === null || URI_SCHEME.test(entry.resource)) continue;
+      const absoluteSource = entry.resource.startsWith("/")
+        ? join(bundleDirectory, entry.resource.slice(1))
+        : resolve(dirname(absoluteFile), entry.resource);
+      const source = toPosix(relative(rootDirectory, absoluteSource));
+      harvestedPaths.add(source);
+      // An id only marks a decision harvested when it labels the ledger the decision lives in.
+      // Without that pairing, any concept citing an unrelated source as "state-ad-001" would
+      // silently close the gap for a decision nobody read.
+      if (entry.id !== null && source === toPosix(STATE_PATH)) {
+        harvestedIds.add(entry.id.toLowerCase());
+      }
+    }
+
+    findings.push(
+      ...checkDrift(file, absoluteFile, rootDirectory, bundleDirectory, data, sourceLastChanged),
+    );
+  }
+
+  findings.push(...checkRawNaming(rootDirectory, rawDirectory));
+  findings.push(...checkGaps(rootDirectory, harvestedIds, harvestedPaths));
+  return findings;
+}

package/.agents/skills/wtk-knowledge-check/scripts/cli.ts

@@ -0,0 +1,32 @@
+import { checkKnowledge, type KnowledgeFinding } from "./check.js";
+
+const HEADINGS: Record<KnowledgeFinding["kind"], string> = {
+  conformance: "conformance — OKF v0.2 requires a parseable frontmatter with a non-empty `type`",
+  drift:
+    "drift — the source moved on after the concept recorded it; re-read it and bump last_modified.\n  This compares committer dates, which a rebase moves, so an uncommitted edit does not show here\n  and a green run is not final. A source and the concept citing it are exempt while their last\n  change is the same commit; set last_modified to the day you commit rather than leaning on that.",
+  naming: "naming — raw sources are named YYYY-MM-DD-<slug> so the directory sorts chronologically",
+  gap: "gap — durable knowledge in .specs/ that no concept has harvested yet",
+};
+
+const rootDirectory = process.argv[2] ?? process.cwd();
+const findings = checkKnowledge(rootDirectory);
+
+if (findings.length === 0) {
+  console.log(`knowledge: bundle is conformant, in sync and fully harvested in ${rootDirectory}`);
+} else {
+  for (const kind of ["conformance", "drift", "naming", "gap"] as const) {
+    const group = findings.filter((finding) => finding.kind === kind);
+    if (group.length === 0) continue;
+
+    const write = group.some((finding) => finding.severity === "error")
+      ? console.error
+      : console.warn;
+    write(`\nknowledge: ${HEADINGS[kind]}`);
+    for (const finding of group) write(`  ${finding.file}: ${finding.message}`);
+  }
+
+  const errors = findings.filter((finding) => finding.severity === "error").length;
+  const warnings = findings.length - errors;
+  console.error(`\nknowledge: ${errors} error(s), ${warnings} warning(s)`);
+  if (errors > 0) process.exitCode = 1;
+}

package/.agents/skills/wtk-knowledge-check/scripts/frontmatter.ts

@@ -0,0 +1,44 @@
+/**
+ * The result of reading a document's leading `---` delimited YAML block.
+ *
+ * Absence and malformation are different answers on purpose: a caller may tolerate a file
+ * with no block at all while still refusing one whose block cannot be read.
+ */
+export type Frontmatter = {
+  /** Whether the file opens with a `---` delimited block at all. */
+  present: boolean;
+  data: Record<string, unknown> | null;
+  /** Why the block could not be turned into a mapping, when it could not. */
+  error: string | null;
+};
+
+/**
+ * Reads the frontmatter of a Markdown document.
+ *
+ * Three shapes fail, each with its own message: a block that is never closed, a block whose
+ * YAML does not parse, and a block that parses to something other than a mapping. An empty
+ * block is not a failure — it yields an empty mapping.
+ */
+export function readFrontmatter(source: string): Frontmatter {
+  const lines = source.replace(/\r\n/g, "\n").split("\n");
+  if (lines[0] !== "---") return { present: false, data: null, error: null };
+
+  const closing = lines.indexOf("---", 1);
+  if (closing === -1) {
+    return { present: true, data: null, error: "the frontmatter block is never closed" };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = Bun.YAML.parse(lines.slice(1, closing).join("\n"));
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message.split("\n")[0] : String(cause);
+    return { present: true, data: null, error: `unparseable YAML: ${detail}` };
+  }
+
+  if (parsed === null || parsed === undefined) return { present: true, data: {}, error: null };
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { present: true, data: null, error: "the frontmatter is not a YAML mapping" };
+  }
+  return { present: true, data: parsed as Record<string, unknown>, error: null };
+}

package/.agents/skills/wtk-lean/.skill-meta.json

@@ -0,0 +1,6 @@
+{
+  "source": "https://github.com/tech-leads-club/agent-skills/tree/main/skills/tlc-spec-lean",
+  "sourceCommit": "0ab82f644cd9caf94c65347a50ad934800b0cbc4",
+  "contentHash": "56db00c3b8c5e76c41f05aeddf1ba1c21be420f4afee48a5695c693a7391a50f",
+  "license": "CC-BY-4.0"
+}

package/.agents/skills/wtk-lean/NOTICE.md

@@ -0,0 +1,18 @@
+## Attribution
+
+This skill is an adapted version of Tech Lead's Club's `tlc-spec-lean` skill,
+created by Felipe Rodrigues and published at:
+
+https://github.com/tech-leads-club/agent-skills/tree/main/skills/tlc-spec-lean
+
+The original work is licensed under CC BY 4.0. This workflow-owned adaptation
+retains the original planning and validation foundations and materially changes
+execution to use whole observable slices, one sequential builder, one fresh verifier
+over the complete feature, and transient feature-artifact cleanup.
+
+## License
+
+Creative Commons Attribution 4.0 International (CC BY 4.0).
+
+Attribution is required. This notice identifies the original author, source,
+license, and material modifications.