drt-method 1.0.0

package/src/drt-skills/3-solutioning/drt-architecture/assets/spine-template.md

@@ -0,0 +1,79 @@
+---
+name: '{name}'
+type: architecture-spine
+purpose: build-substrate    # build-substrate (default) · discussion · report · deck
+altitude: feature           # initiative (keeps features) · feature (keeps epics) · epic (keeps stories)
+paradigm: '{named design pattern, e.g. hexagonal, layered, pipes-and-filters, actor}'
+scope: '{what this spine governs}'
+status: draft               # draft · final
+created: '{date}'
+updated: '{date}'
+binds: []                   # capability / unit IDs governed (from the driving spec; at epic altitude, also the inherited parent AD ids)
+sources: []
+companions: []
+---
+
+# Architecture Spine — {name}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them; never emit a comment in the finished spine. This is a shape, not a script: keep only the sections this spine needs and cut the rest (no empty headers). A small intent may be just paradigm + a few ADs + conventions; a platform earns more. An inherited epic spine is usually mostly Inherited Invariants + a thin Deferred. Decisions, not rationale (rationale lives in the memlog). Carry shape in diagrams; prose only where it must. -->
+
+## Design Paradigm
+
+<!-- Name the pattern (a known one loads a whole model for free) and map its layers to namespaces/directories. The smallest, most durable thing here. -->
+
+## Inherited Invariants
+
+<!-- Only when this spine inherits a higher-altitude parent. The parent's ADs/conventions/paradigm that bind here, by their ORIGINAL ids — read-only, never renumbered, not re-derived. A local decision that contradicts one is a conflict to surface, not an override. Cut this section otherwise. -->
+
+| Inherited | From parent | Binds here |
+| --- | --- | --- |
+| {AD-id / convention} | {parent spine} | {what it constrains in this scope} |
+
+## Invariants & Rules
+
+<!-- The durable heart: calls a future builder can't read off compliant code. One block per decision: stable ascending id (never reused/renumbered), Binds, Prevents (the divergence), Rule (enforceable). Tag [ADOPTED] when the user or existing reality settled it. Include a dependency-direction diagram (who may depend on whom) — it IS a rule; author it as valid mermaid, never an empty graph. -->
+
+### AD-1 — {decision}
+
+- **Binds:** {capability / unit ids / fr/nfr's, areas, or `all`}
+- **Prevents:** {the divergence this stops}
+- **Rule:** {the constraint downstream must follow}
+
+## Consistency Conventions
+
+<!-- Defaults that bind where independent builders would drift. Cut rows that don't apply; add rows the project needs. -->
+
+| Concern | Convention |
+| --- | --- |
+| Naming (entities, files, interfaces, events) | |
+| Data & formats (ids, dates, error shapes, envelopes) | |
+| State & cross-cutting (mutation, errors, logging, config, auth) | |
+
+## Stack
+
+<!-- SEED — verified current at authoring; the code owns this once it exists. Name + version only; the why lives in the memlog. One row per language, framework, key dependency, platform, or chain that's pinned. -->
+
+| Name | Version |
+| --- | --- |
+| {language / framework / key dep / platform / chain} | {pinned version} |
+
+## Structural Seed
+
+<!-- The shapes worth fixing at cold-start — not a fixed list. Include only what's non-obvious at this altitude, and use as many diagrams as convey it, each as VALID mermaid (never a placeholder or empty graph). Candidates: system/container/context view; DEPLOYMENT & ENVIRONMENTS and external provider/infra topology (cover the operational envelope here when this altitude owns it — don't let it fall through); core-entity ERD (names + relationships only; an attribute that's itself an invariant is an AD, not a diagram); a minimal source tree. The code owns the detail — this is scaffold, not a mirror to maintain. -->
+
+```text
+{root}/
+  {dir}/   # {what lives here}
+```
+
+## Capability → Architecture Map
+
+<!-- Present when a spec drove this run. Bridges the spec's capabilities to where they live + what governs them; the consistency auditor's checklist. Cut otherwise. -->
+
+| Capability / Area | Lives in | Governed by |
+| --- | --- | --- |
+| {CAP-id / area} | {component / module} | {AD-id, convention, paradigm} |
+
+## Deferred
+
+<!-- Decisions intentionally pushed down, each with the reason it can wait — including whole dimensions this altitude doesn't own yet. The half of the contract that keeps the spine lean. -->

package/src/drt-skills/3-solutioning/drt-architecture/customize.toml

@@ -0,0 +1,100 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for drt-architecture.
+#
+# Override files (not edited here):
+#   {project-root}/_drt/custom/drt-architecture.toml         (team)
+#   {project-root}/_drt/custom/drt-architecture.user.toml    (personal)
+
+[workflow]
+
+# --- Configurable below. Overrides merge per DRT structural rules: ---
+#   scalars: override wins • arrays: append
+
+# Steps to run before the standard activation (config load, greet).
+# Use for pre-flight loads, approved-stack policy checks, etc.
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Use for context-heavy setup that should happen once the user has been acknowledged.
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (approved stacks, banned dependencies, platform constraints, compliance guardrails).
+# Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed
+# path/glob whose contents are loaded as facts.
+#
+# Default loads project-context.md if drt-generate-project-context produced one — giving the
+# architect persistent awareness of the project's tech, domain, and conventions (load-bearing
+# for brownfield). Common opt-ins (set in team/user override TOML):
+#   "Our org is AWS-only -- do not propose GCP or Azure."
+#   "file:{project-root}/docs/engineering-standards.md"
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Executed when the workflow completes (after the spine is final and the user has been told).
+# String scalar (single instruction) or array of instructions executed in order. Empty for none.
+on_complete = ""
+
+# The architecture spine template. Treated as expert prior knowledge, not a checklist — the LLM
+# adapts it to the project, altitude, and domain, and drops sections a project genuinely doesn't
+# need. Override the path in team/user TOML to enforce a different spine shape.
+spine_template = "assets/spine-template.md"
+
+# Run folder location. ARCHITECTURE-SPINE.md, its .memlog.md, and any fuller rendering the run
+# produces all land inside `{spine_output_path}/{run_folder_pattern}/`. Resume-check scans
+# `{spine_output_path}` for prior unfinished runs.
+#
+# The default pattern fits the common case (one spine per project, at the altitude above epics).
+# At EPIC altitude, override run_folder_pattern to carry the epic identity so per-epic runs don't
+# collide on the same day — e.g. set it (team/user TOML) to "architecture-epic-{epic_id}", binding
+# {epic_id} from the driving spec / the activating payload. Headless callers may instead pass an
+# explicit doc_workspace and bypass the pattern entirely.
+spine_output_path = "{planning_artifacts}/architecture"
+run_folder_pattern = "architecture-{project_name}-{date}"
+
+# Prose-editorial standards applied at finalize ONLY to a fuller prose document the run produces
+# (a discussion report, full architecture doc, or design addendum) — never to the spine or other
+# short, structured outputs, which are terse and carry decisions in AD-n blocks and diagrams by
+# design. Each entry is a `skill:`, `file:`, or plain-text directive applied before the user sees
+# the polished draft. Suggested order: structural passes first, prose mechanics last. Append-only.
+doc_standards = [
+  "skill:drt-editorial-review-structure",
+  "skill:drt-editorial-review-prose",
+]
+
+# External-source registry. Natural-language directives describing knowledge bases, MCP tools, or
+# internal systems the LLM may consult ON DEMAND during the run (not preemptively) — approved-stack
+# catalogs, internal platform docs, version registries. Each entry names the tool, the trigger
+# condition, and any fields it needs. If a named tool is unavailable at runtime, the LLM falls back
+# to standard behavior (e.g. web research) and notes the gap. Empty by default.
+#
+# Examples (set in team/user override TOML):
+#   "When choosing a datastore, consult corp:platform_catalog before recommending one."
+#   "For current library versions, query corp:artifact_registry before web search."
+external_sources = []
+
+# External-handoff routing applied at Finalize to push outputs beyond local files (Confluence,
+# Notion, ticket systems). Each entry names the MCP tool, the destination, and required fields.
+# Runs after polish; returned URLs/IDs are surfaced. Unavailable tools are skipped and flagged;
+# local files always exist. Empty by default.
+external_handoffs = []
+
+# --- Finalize reviewers ---
+# Extra review lenses spawned as parallel subagents at the validation gate (Finalize and the
+# Validate intent), on top of the skill's built-in good-spine checklist and the lint_spine.py
+# mechanical floor. The GATE is stakes-gated — a throwaway spine may run it quietly or skip it —
+# but whenever the gate runs, every entry here runs with it (the configured floor, never cherry-
+# picked); only ad-hoc lenses are optional, and headless never skips the gate.
+#
+# Entries follow the standard prefix convention:
+#   "skill:NAME"   invoke the named review skill as a subagent against ARCHITECTURE-SPINE.md
+#   "file:PATH"    load the file as a review prompt; spawn an adversarial subagent applying it
+#   plain text     use the text directly as the subagent's review prompt
+#
+# Resolved on-demand (not at activation). Override TOML may append.
+finalize_reviewers = [
+  "Verify every committed decision was web-researched or reality-checked rather than asserted from training data: current library/framework versions, that each named technology still exists and fits, and — greenfield — the live defaults of any starter it leans on. Flag anything that could be out of date and wasn't confirmed against the web, the existing project, or the current starter.",
+  "Attack the spine as an adversary: construct two units one level down that each obey every AD to the letter yet still build incompatibly — clashing shared-data shapes, two owners of one entity, conflicting state-mutation paths. Every pair you find is a hole to close with a new or tightened AD.",
+]

package/src/drt-skills/3-solutioning/drt-architecture/references/headless.md

@@ -0,0 +1,26 @@
+# Headless
+
+No interactive user: infer everything, ask nothing, but never invent — record inferences as `assumptions[]` and gaps that need a human as `open_questions[]`. Detect headless from a `headless: true` flag, a non-interactive / no-TTY invocation, an activation hook that declares it, or a first message that pre-supplies all inputs and asks for an artifact path back; when ambiguous, default to interactive.
+
+Drive the run from the payload in the first message — `intent`, `altitude`, `purpose`, the driving input (spec package / PRD / raw intent / brownfield path), a parent spine path at lower altitude, and `doc_workspace` if a specific folder is required. Infer anything absent from the inputs or workspace; don't invent stack, constraints, or scope to fill a gap. You still verify named tech on the web (you can't ask, but you can check) and still drive every write through the shared `{project-root}/_drt/scripts/memlog.js`. Run the full Reviewer Gate (`references/reviewer-gate.md`) non-interactively: `scripts/lint_spine.py` plus **every `{workflow.finalize_reviewers}` lens as a parallel subagent** (and any ad-hoc lens the spine's criticality warrants). Headless skips only the human picking from the menu — never the reviewers themselves; apply the clear fixes and record anything unresolved in `open_questions[]`. For a true authority collision, list it in `conflicts_with_prior_decisions[]`. For the Validate intent, always write the report to `{doc_workspace}` and add `"offer_to_update": true`. If intent stays ambiguous after inference, halt blocked.
+
+End with JSON only, omitting keys for artifacts not produced — the shape below is the fully-produced (`complete`) case; a `blocked` run produces no spine, so it omits `spine`, `memlog`, and `companions` entirely (see the note under the block):
+
+```json
+{
+  "status": "complete | partial | blocked",
+  "intent": "create | update | validate",
+  "altitude": "initiative | feature | epic",
+  "purpose": "build-substrate | discussion",
+  "doc_workspace": "<resolved run folder>",
+  "spine": "{doc_workspace}/ARCHITECTURE-SPINE.md",
+  "memlog": "{doc_workspace}/.memlog.md",
+  "companions": [],
+  "assumptions": [],
+  "open_questions": [],
+  "conflicts_with_prior_decisions": [],
+  "reason": "<one line, only when blocked>"
+}
+```
+
+`complete` stands alone · `partial` (spine produced, but `open_questions[]` non-empty or critical inputs inferred) means review before downstream use · `blocked` means no spine produced — return only `status`, `intent`, `reason`, and `doc_workspace` (if bound), omitting `spine`, `memlog`, `companions`, and the artifact arrays that don't exist.

package/src/drt-skills/3-solutioning/drt-architecture/references/reviewer-gate.md

@@ -0,0 +1,13 @@
+# Reviewer Gate
+
+The spine's pre-handoff review. Runs at Finalize (after distill + reconcile) and *is* the Validate intent. The difference is the ending: at Finalize you apply the clear fixes yourself; under Validate you report and don't change the spine.
+
+Cheap deterministic pass first: `uv run {skill-root}/scripts/lint_spine.py --workspace {doc_workspace}` settles the mechanical misses (placeholders, duplicate `AD` IDs, missing Binds/Prevents/Rule, unpinned Stack versions), so reviewers spend judgment on the semantic half.
+
+Assemble the menu: a **rubric walker** that judges the spine against the good-spine checklist below, **+ every entry in `{workflow.finalize_reviewers}`**, + ad-hoc lenses you invent or offer as the spine's rigor, altitude, and criticality warrant — a security/compliance lens for regulated stakes, a seam reviewer cross-team, a data-integrity lens for a heavy data model. Scale *whether and how heavily the gate runs* to the stakes: a throwaway prototype may run it quietly or skip the gate entirely; a high-criticality or platform-altitude spine earns more lenses and the explicit all / subset / skip menu. But once the gate runs, the `{workflow.finalize_reviewers}` always run — they are the configured floor, never cherry-picked out; only the ad-hoc lenses are optional. (Headless never skips the gate.)
+
+Dispatch every entry as a **parallel subagent against `ARCHITECTURE-SPINE.md`** (prefix convention: `skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/reviews/review-{slug}.md` — a subfolder, so the gate's scratch stays out of the deliverable folder — and returns ONLY a compact summary (verdict, top 2–5 findings, file path) — the parent never holds full review text. An inline self-check does not count: the independent context is the point, because a fresh reviewer finds the divergences the author talks past. If subagents are unavailable, run sequentially — write the file first, then flush it from context.
+
+**Good-spine checklist** (what the rubric walker judges): it fixes the real divergence points for the level below and misses none; every `AD`'s Rule is enforceable and actually prevents its stated divergence; nothing under Deferred could let two units diverge; named tech is verified-current; it ratifies rather than contradicts a brownfield codebase; if a spec drove it, it covers that spec's capabilities; if a parent spine is inherited, no new `AD` weakens or contradicts an inherited one; and every dimension the altitude owns is decided, deferred, or an open question — a whole dimension left silent is a finding, especially the operational/environmental envelope (deployment & environments, infra/provider strategy, operations) a domain-focused draft skips.
+
+Surface findings tiered, never dumped: a one-sentence gate verdict, then critical + high; medium/low roll into a tail ("plus N more in {file}"). Per finding: autofix, discuss, defer to Deferred / open items, or ignore. **At Finalize this is your own gate — apply the clear fixes rather than handing over a list; surface only what genuinely needs the user.** Under the **Validate intent**, fold every reviewer's output into one bespoke HTML + markdown report and open the HTML.

package/src/drt-skills/3-solutioning/drt-architecture/scripts/lint_spine.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""lint-spine — the mechanical half of spine decision-integrity, done deterministically.
+
+LLMs miscount IDs and miss literal placeholders; a grep does not. This linter owns the
+checks a script does better than a prompt, and leaves the semantic half (is each Rule
+actually enforceable? does the boundary make sense?) to the rubric walker.
+
+It reads ARCHITECTURE-SPINE.md from a workspace and reports, as compact JSON on stdout:
+
+  - placeholder    literal TBD / TODO / "similar to AD-n" / unfilled {template-token}
+  - ad_id          duplicate or non-monotonic AD-n identifiers
+  - ad_fields      an AD-n block missing Binds / Prevents / Rule
+  - version_pin    a ## Stack table row with no version
+
+Fenced code blocks are blanked (replaced with equal-count blank lines) before scanning, so
+mermaid and source trees don't trip false positives AND reported line numbers still line up
+with the real file. Reported lines are absolute file lines (frontmatter offset added). Exit
+code is always 0 — findings travel in the JSON; the caller (Reviewer Gate / rubric walker)
+decides what to do with them.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+SPINE = "ARCHITECTURE-SPINE.md"
+
+AD_HEADING = re.compile(r"^#{2,4}\s*AD-(\d+)\b(.*)$", re.MULTILINE)
+HEADING = re.compile(r"^#{1,6}\s", re.MULTILINE)
+FENCE = re.compile(r"```.*?```", re.DOTALL)
+PLACEHOLDER_WORD = re.compile(r"\b(TBD|TODO|FIXME|XXX)\b")
+SIMILAR_TO = re.compile(r"similar to AD-\d+", re.IGNORECASE)
+TEMPLATE_TOKEN = re.compile(r"\{[a-z_][a-z0-9_ /.-]*\}")
+
+
+def split_frontmatter(text: str) -> tuple[str, str, int]:
+    """Return (frontmatter, body, body_line_offset).
+
+    Frontmatter is the content between the first two lines that are *exactly* `---`
+    (line-exact, like memlog.split — a `---` inside a value or a body thematic break never
+    truncates it). body_line_offset is the number of file lines before the body begins, so a
+    body-relative line number plus the offset gives the absolute file line. Absent frontmatter
+    → ('', text, 0)."""
+    lines = text.split("\n")
+    if lines and lines[0] == "---":
+        for i in range(1, len(lines)):
+            if lines[i] == "---":
+                fm = "\n".join(lines[1:i])
+                body = "\n".join(lines[i + 1:])
+                return fm, body, i + 1
+    return "", text, 0
+
+
+def blank_fences(text: str) -> str:
+    """Replace each fenced block with the same number of newlines, so scanning skips fenced
+    content while every line number outside the fence stays put."""
+    return FENCE.sub(lambda m: "\n" * m.group(0).count("\n"), text)
+
+
+def line_of(text: str, idx: int) -> int:
+    return text.count("\n", 0, idx) + 1
+
+
+def find_placeholders(body: str, offset: int) -> list[dict]:
+    findings: list[dict] = []
+    scan = blank_fences(body)
+    # (regex, label, severity) — TBD/TODO and dangling cross-refs are unambiguous; a bare
+    # {template-token} can be legitimate brace prose, so it is flagged low ("possible") to keep
+    # the mechanical pass near-zero false-positive rather than train reviewers to ignore it.
+    for rx, label, severity in (
+        (PLACEHOLDER_WORD, "placeholder marker", "high"),
+        (SIMILAR_TO, "unresolved cross-reference", "high"),
+        (TEMPLATE_TOKEN, "possible unfilled template token (verify)", "low"),
+    ):
+        for m in rx.finditer(scan):
+            findings.append({
+                "category": "placeholder",
+                "severity": severity,
+                "detail": f"{label}: {m.group(0)!r}",
+                "location": f"{SPINE} (line {offset + line_of(scan, m.start())})",
+            })
+    return findings
+
+
+def find_frontmatter_placeholders(frontmatter: str) -> list[dict]:
+    """Catch unfilled tokens left in frontmatter (e.g. paradigm/scope/date) — part of the
+    spine contract, but outside the body that find_placeholders scans."""
+    findings: list[dict] = []
+    for rx, label, severity in (
+        (PLACEHOLDER_WORD, "placeholder marker", "high"),
+        (TEMPLATE_TOKEN, "possible unfilled template token (verify)", "low"),
+    ):
+        for m in rx.finditer(frontmatter):
+            findings.append({
+                "category": "placeholder",
+                "severity": severity,
+                "detail": f"frontmatter {label}: {m.group(0)!r}",
+                "location": f"{SPINE} frontmatter (line {1 + line_of(frontmatter, m.start())})",
+            })
+    return findings
+
+
+def find_ad_issues(body: str, offset: int) -> list[dict]:
+    findings: list[dict] = []
+    scan = blank_fences(body)  # AD headings shown inside a code fence are not live ADs
+    matches = list(AD_HEADING.finditer(scan))
+    seen: dict[int, int] = {}
+    prev: int | None = None
+    for m in matches:
+        num = int(m.group(1))
+        file_line = offset + line_of(scan, m.start())
+        loc = f"{SPINE} AD-{num} (line {file_line})"
+        if num in seen:
+            findings.append({
+                "category": "ad_id",
+                "severity": "high",
+                "detail": f"AD-{num} id reused (also at line {seen[num]})",
+                "location": loc,
+            })
+        else:
+            seen[num] = file_line
+        if prev is not None and num <= prev:
+            findings.append({
+                "category": "ad_id",
+                "severity": "high",
+                "detail": f"AD-{num} is non-monotonic (follows AD-{prev}); ids must ascend and never renumber",
+                "location": loc,
+            })
+        prev = num if prev is None else max(prev, num)
+
+        # block text = from this heading to the next heading of any level
+        start = m.end()
+        nxt = HEADING.search(scan, start)
+        block = scan[start:nxt.start()] if nxt else scan[start:]
+        low = block.lower()
+        missing = [f for f in ("binds", "prevents", "rule") if f not in low]
+        if missing:
+            findings.append({
+                "category": "ad_fields",
+                "severity": "high",
+                "detail": f"AD-{num} missing required field(s): {', '.join(missing)}",
+                "location": loc,
+            })
+    return findings
+
+
+def find_unpinned_stack(body: str, offset: int) -> list[dict]:
+    """Flag a `## Stack` table row that names something but leaves its version blank or a
+    placeholder. Pinning lives in the body table now, not frontmatter. A row whose name is
+    still a `{token}` skeleton is left to the placeholder pass, not double-reported here.
+
+    Fences are blanked first (like find_placeholders / find_ad_issues), so a pipe-row or
+    heading inside a code block is never read as live Stack content. The heading match is
+    `## Stack` with a word boundary, so a renamed heading (`## Stack & Versions`) still
+    counts. Name and Version columns are located from the header row, so a reordered table
+    pairs name to version correctly; both default to the canonical positions (0, 1)."""
+    findings: list[dict] = []
+    in_stack = False
+    header_seen = False
+    name_idx, ver_idx = 0, 1
+    scan = blank_fences(body)
+    for i, raw in enumerate(scan.splitlines()):
+        if HEADING.match(raw):
+            in_stack = re.match(r"^##\s+Stack\b", raw) is not None
+            header_seen = False
+            name_idx, ver_idx = 0, 1
+            continue
+        if not in_stack or not raw.lstrip().startswith("|"):
+            continue
+        if set(raw.strip()) <= set("|-: "):
+            continue  # separator row
+        cells = _table_cells(raw)
+        if not header_seen:
+            header_seen = True
+            for j, c in enumerate(cells):
+                if c.lower() == "name":
+                    name_idx = j
+                elif c.lower() == "version":
+                    ver_idx = j
+            continue
+        name = cells[name_idx] if len(cells) > name_idx else ""
+        version = cells[ver_idx] if len(cells) > ver_idx else ""
+        if not name or TEMPLATE_TOKEN.search(name):
+            continue
+        if not version or TEMPLATE_TOKEN.search(version):
+            findings.append({
+                "category": "version_pin",
+                "severity": "medium",
+                "detail": f"Stack entry {name!r} has no version",
+                "location": f"{SPINE} (line {offset + i + 1})",
+            })
+    return findings
+
+
+def _table_cells(row: str) -> list[str]:
+    """Split a markdown table row into trimmed cells, dropping the leading/trailing pipe."""
+    s = row.strip()
+    if s.startswith("|"):
+        s = s[1:]
+    if s.endswith("|"):
+        s = s[:-1]
+    return [c.strip() for c in s.split("|")]
+
+
+def lint(text: str) -> dict:
+    frontmatter, body, offset = split_frontmatter(text)
+    findings: list[dict] = []
+    findings += find_frontmatter_placeholders(frontmatter)
+    findings += find_placeholders(body, offset)
+    findings += find_ad_issues(body, offset)
+    findings += find_unpinned_stack(body, offset)
+    counts: dict[str, int] = {}
+    for f in findings:
+        counts[f["severity"]] = counts.get(f["severity"], 0) + 1
+    return {
+        "ok": len(findings) == 0,
+        "spine": SPINE,
+        "total_findings": len(findings),
+        "by_severity": counts,
+        "findings": findings,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Lint an architecture spine for mechanical integrity.")
+    ap.add_argument("--workspace", required=True, help="run folder containing ARCHITECTURE-SPINE.md")
+    ap.add_argument("-o", "--output", help="write JSON here instead of stdout")
+    args = ap.parse_args(argv)
+
+    spine_path = Path(args.workspace) / SPINE
+    if not spine_path.exists():
+        result = {"ok": False, "error": f"{spine_path} not found", "findings": [], "total_findings": 0}
+    else:
+        try:
+            text = spine_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as e:
+            # honor the "exit code is always 0" contract: a read/decode failure travels in JSON
+            result = {"ok": False, "error": f"could not read {spine_path}: {e}", "findings": [], "total_findings": 0}
+        else:
+            result = lint(text)
+
+    out = json.dumps(result, indent=2)
+    if args.output:
+        Path(args.output).write_text(out + "\n", encoding="utf-8")
+    else:
+        print(out)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/drt-skills/3-solutioning/drt-check-implementation-readiness/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: drt-check-implementation-readiness
+description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness".'
+---
+
+# Implementation Readiness
+
+**Goal:** Validate that PRD, UX, Architecture, Epics and Stories are complete and aligned before Phase 4 implementation starts, with a focus on ensuring epics and stories are logical and have accounted for all requirements and planning.
+
+**Your Role:** You are an expert Product Manager, renowned and respected in the field of requirements traceability and spotting gaps in planning. Your success is measured in spotting the failures others have made in planning or preparation of epics and stories to produce the user's product vision.
+
+## Conventions
+
+- Bare paths (e.g. `steps/step-01-document-discovery.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step toward the overall goal is a self-contained instruction file; adhere to one file at a time, as directed
+- **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `node {project-root}/_drt/scripts/resolve-customization.js --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_drt/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_drt/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_drt/drt/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Execution
+
+Read fully and follow: `./steps/step-01-document-discovery.md` to begin the workflow.

package/src/drt-skills/3-solutioning/drt-check-implementation-readiness/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for drt-check-implementation-readiness. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per DRT structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All artifacts must follow org naming conventions."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches Step 6 (Final Assessment),
+# after the readiness report has been saved and presented. Override wins.
+# Leave empty for no custom post-completion behavior.
+
+on_complete = ""