Template Drift

/template-drift — Template Drift Detector

You are checking whether the project's local copies of every vendored sync surface still match the canonical versions in the adlc-toolkit. These surfaces are copied per-repo (not symlinked like skills/agents), so they drift over time. Some drift is intentional (project-specific customization); some is accidental (toolkit updated and the project never pulled the change). This skill surfaces both and helps you decide what to reconcile.

Vendored sync surfaces

<!-- sync-surfaces: template-drift -->

/template-drift checks drift on all five of these surfaces. The first four are physically copied into the project by /init (see init/SKILL.md's matching <!-- sync-surfaces: init --> list); the fifth is a /template-drift-only check for a drift symptom /init deliberately does NOT copy.

• templates — .adlc/templates/*.md vs ~/.claude/skills/templates/*.md (Step 2, template-posture)
• partials — .adlc/partials/*.sh vs ~/.claude/skills/partials/*.sh (Step 3, partials-posture)
• ethos — .adlc/ETHOS.md vs ~/.claude/skills/ETHOS.md (Step 3c, template-posture + missing-principle)
• workflow-runtime — .adlc/workflows/adlc-sprint.workflow.js + README.md vs ~/.claude/skills/workflows/ (Step 3d, partials-posture)
• workflow-test-landmine — stale *.test.js/*.spec.js under .adlc/ from an older /init (Step 3b, always stale; template-drift-only)

<!-- /sync-surfaces -->

Cross-reference invariant (BR-4): every surface /init copies MUST have a matching check here. Adding a new vendored surface to /init without adding a check here is a silent gap — the toolkit's tools/lint-skills sync-surface-parity check fails the build when the two lists disagree.

Ethos

!test -s .adlc/ETHOS.md && cat .adlc/ETHOS.md || echo No ethos found — run /init to vendor .adlc/ETHOS.md

Context

This skill checks five vendored sync surfaces (see "Vendored sync surfaces" below): templates, partials, ethos, workflow-runtime, and the workflow-test landmine.

• Project templates dir: !ls .adlc/templates/ || echo No .adlc/templates/ directory — run /init first
• Toolkit templates dir: !ls ~/.claude/skills/templates/ || echo Toolkit templates not found at ~/.claude/skills/templates/
• Project ETHOS: !test -f .adlc/ETHOS.md && echo present || echo absent — run /init
• Project workflow runtime: !ls .adlc/workflows/ || echo no .adlc/workflows/ runtime — run /init
• Current directory: !pwd

Input

Scope: $ARGUMENTS (optional — single template name to check; otherwise all templates)

Prerequisites

1. .adlc/templates/ must exist in the current project. If it does not, stop and tell the user: "This project has no local templates — it uses toolkit templates directly. No drift to check." (New projects per the /init Step 6 policy don't copy templates locally.)
2. ~/.claude/skills/templates/ must resolve through the symlink. If it does not, stop and tell the user: "The adlc-toolkit symlink is broken. Verify readlink ~/.claude/skills points to the toolkit repo."

Instructions

Step 0a: Verify the Canonical Baseline (do this first — everything is measured against it)

~/.claude/skills is not a release artifact. It is a symlink to a working checkout of the toolkit repo, and that checkout can be on a feature branch, mid-rebase, or dirty. Whatever it currently contains is what every comparison below calls "canonical". If the baseline is wrong, every verdict is wrong — and it fails in the worst direction: a consumer that is correctly in sync gets reported stale, and the proposed remedy is to copy the older file over it. The skill would then be driving a regression with full confidence.

Establish the baseline before measuring anything against it:

TOOLKIT=$(readlink ~/.claude/skills)
git -C "$TOOLKIT" fetch --prune origin
TK_BRANCH=$(git -C "$TOOLKIT" branch --show-current)
TK_DEFAULT=$(git -C "$TOOLKIT" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
TK_DEFAULT=${TK_DEFAULT:-main}
TK_DIRTY=$(git -C "$TOOLKIT" status --porcelain | wc -l | tr -d ' ')
TK_BEHIND=$(git -C "$TOOLKIT" rev-list --count "HEAD..origin/$TK_DEFAULT" 2>/dev/null)

Report the baseline in the header always, and warn loudly when any of these hold:

• TK_BRANCH != TK_DEFAULT — the baseline is a feature branch, not canonical
• TK_BEHIND > 0 — the checkout is behind the toolkit's default branch
• TK_DIRTY > 0 — uncommitted local edits are being treated as canonical

When any warning fires, say so before the tables and state the consequence plainly: "Baseline is <branch>, N commits behind origin/<default> — surfaces reported stale may in fact be ahead of this baseline, and copying from it would regress them." Prefer comparing against git -C "$TOOLKIT" show "origin/$TK_DEFAULT:<path>" rather than the working tree when the checkout is not clean-and-current; if you cannot, downgrade every stale verdict to unverified-baseline rather than asserting drift you cannot stand behind.

This is not hypothetical. It produced a false stale for infrastructure's forge.sh on 2026-08-28: the toolkit checkout sat on a feature branch cut before BUG-201 merged, so the consumer — which correctly carried the newer fix — was reported as the stale one.

Step 0: Resolve the Pipeline Branch Set

Every comparison in Steps 1–3d runs once per pipeline branch, not once per checkout.

In a repo with a promotion pipeline (dev → staging → main), a vendored file is not one thing — it is one thing per branch, and they routinely disagree. A sync PR lands on the integration branch and reaches main only at the next promotion; a change promoted to main reaches dev only at the next reverse-sync. Comparing whichever branch happens to be checked out therefore answers a question nobody asked, and answers it confidently: it reports drift on repos that are merely awaiting promotion, and reports clean on repos whose other branches are stale. Under-reporting is the exact failure this skill exists to prevent (BR-4), so a single-branch check is not a smaller version of the job — it is a wrong answer wearing the costume of a complete one.

Resolve the branch set once, here, and reuse it for every surface:

1. Fetch, then read refs — never trust a stale local ref (LESSON-036).

   git fetch --prune origin

2. Determine the integration branch using the same signals as /proceed step 4 — do not invent a second detection rule. Any one signal is sufficient:

   • .adlc/config.yml declares gcp.staging_project (or otherwise indicates a staging-first deploy), OR
   • a .github/workflows/* enforces a verify-head-ref / branch-protection head-ref check, OR
   • CLAUDE.md describes a "two-branch" / "staging-first" / "staging → main promotion" pipeline.

   If any signal is present the integration branch is staging (unless the project names another); otherwise it is the default branch.

3. Enumerate the long-lived branches that actually exist on the remote. Do not assume the full triad — teton-code has only main, admin-api has staging + main, atelier-fashion has all three:

   DEFAULT_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
   DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
   # Dedupe in-shell (DEFAULT_BRANCH may itself be dev/staging). Deliberately no
   # awk: its whole-line field reference is a bare positional, which Skill
   # argument templating clobbers inside a fence (lint rule `arg-templating`).
   SEEN=""
   for b in dev staging "$DEFAULT_BRANCH"; do
     case " $SEEN " in *" $b "*) continue ;; esac
     SEEN="$SEEN $b"
     git show-ref --verify --quiet "refs/remotes/origin/$b" && echo "$b"
   done

   An explicit pipeline.branches: [dev, staging, main] in .adlc/config.yml overrides this detection when present — projects with non-standard names say so rather than being guessed at.

4. Read file content per branch with git show, never from the working tree:

   git show "origin/$BRANCH:.adlc/partials/forge.sh"

   A path absent on that branch is missing for that branch, not for the repo.

5. Also check the working tree, as its own scope, and report it alongside the branches. Uncommitted local edits to a vendored file are themselves drift, and are invisible to any git show.

Degrade, never guess. If the directory is not a git repo, has no origin, or the fetch fails (offline, auth), fall back to working-tree-only — the pre-existing behavior — and say so explicitly in the report header: branch scope: working tree only (<reason>). A degraded run must still produce its report; it must never silently present a one-branch result as full coverage.

Single-branch repos are unchanged. When the enumeration yields one branch, the output is materially what it was before, minus the false confidence.

Step 1: Enumerate Templates to Compare

1. If the user passed a scope argument (e.g. requirement-template), only check .adlc/templates/<scope>.md vs ~/.claude/skills/templates/<scope>.md.
2. Otherwise list every *.md file in .adlc/templates/ AND every *.md file in ~/.claude/skills/templates/. Compare the union of both sets — this catches templates that exist in the toolkit but not in the project (new templates added upstream) and templates in the project but not in the toolkit (legacy or custom-to-project files).

Step 2: Detect Template Drift

For each template in the comparison set, run diff -u ~/.claude/skills/templates/<name>.md .adlc/templates/<name>.md. Capture:

• Missing upstream: template exists locally but not in toolkit (legacy or custom)
• Missing locally (a.k.a. missing): template exists in toolkit but not in project (upstream added, not yet copied)
• Identical (a.k.a. synced): no diff (drift = 0)
• Drifted (a.k.a. stale): diff output — count added/removed lines

Also compute a rough drift size: total lines added + total lines removed (excluding context lines). This gives a "how much has changed" number for the summary table.

Step 3: Detect Partial Drift

Partials (*.sh files) are a second sync surface alongside templates. Unlike templates, partials are copied per-repo for portability but are not intended for project-specific customization — they are shared executable code (e.g., ethos-include.sh injects the toolkit's ETHOS preamble into every skill). The classification vocabulary matches Step 2 (synced, stale, missing) so the final report can use one unified summary line.

Rationale — why no "intentional customization" classification for partials:

Partials are shared executable code, not customizable content; intentional consumer-side modification of a partial would shadow the toolkit's gate logic and is the threat model /template-drift is meant to detect. Therefore any drift in partials is reported as stale with no customization classification. This is a security posture: a consumer with a modified ethos-include.sh could silently strip the ETHOS preamble from every skill invocation, and a consumer with a modified gate partial could bypass ADLC phase gates. Treating every partial diff as stale (and surfacing it loudly) is the correct default.

For each *.sh file in ~/.claude/skills/partials/ (use a POSIX-safe glob — guard with [ -e "$f" ] so that an empty toolkit partials directory does not iterate the literal pattern), compare against .adlc/partials/<basename>:

• Run diff -q .adlc/partials/<basename> ~/.claude/skills/partials/<basename>.
• Exit 0 → synced (both exist, identical)
• Exit 1 → stale (both exist, content differs)
• Consumer file absent (.adlc/partials/<basename> does not exist) → missing (toolkit has it, consumer doesn't — consumer needs to re-run /init to copy it down)

Also check the reverse direction: any *.sh in .adlc/partials/ that does NOT exist in ~/.claude/skills/partials/ should be reported as missing upstream (legacy or rogue partial — flag it; do not auto-delete).

If .adlc/partials/ does not exist at all in the consumer project, report every toolkit partial as missing and recommend running /init.

Step 3b: Detect Stale Workflow Test Files (Jest landmine)

A third sync surface is .adlc/workflows/. The current /init policy vendors only the runtime files (adlc-sprint.workflow.js + README.md) and deliberately does not copy the toolkit's workflows/tests/ directory. Those are node:test unit tests (CommonJS require('node:test')) for the inlined pure helpers — toolkit-internal, with no purpose in a consumer repo.

An older /init did cp -R of the whole workflows/ tree and left .adlc/workflows/tests/helpers.test.js behind. In any "type":"module" repo running Jest, Jest's default testMatch (**/?(*.)+(spec|test).[jt]s?(x)) discovers that *.test.js, runs it as ESM, and fails it with ReferenceError: require is not defined — reddening npm test and any CI gate. This is pure accidental staleness (never an intentional customization), so /template-drift flags it loudly.

Scan .adlc/ for any test file that Jest would collect:

# Any *.test.js / *.spec.js anywhere under .adlc/ is the landmine. The known
# offender is the workflows/tests/ tree from an older `cp -R` /init.
find .adlc -type f \( -name '*.test.js' -o -name '*.spec.js' \) 2>/dev/null
# Also surface a lingering tests/ dir (may also hold _load-pure.js, a .md, etc.):
[ -d .adlc/workflows/tests ] && echo ".adlc/workflows/tests/ present (stale — remove)"

Classification is always stale — there is no "intentional customization" path here (same posture as partials in Step 3: this is toolkit-internal code a consumer should never carry). Each hit is reported in Step 5 and offered for removal in Step 6. If there are no hits, report .adlc/ workflow test files as clean (one line) and move on.

Step 3c: Detect ETHOS Drift (the injected constitution)

A fourth sync surface is .adlc/ETHOS.md — the principles /init copies from ~/.claude/skills/ETHOS.md and that every skill injects at invocation time via ethos-include.sh. This surface is the most consequential to keep in sync: ethos-include.sh resolves the project copy first, so a stale .adlc/ETHOS.md silently runs an outdated constitution in every skill invocation — and the toolkit has shipped new principles more than once (principle #6 "If It's Broken, Fix It" and #7 "Skeptical by Default" were added after the original five). Drift here is therefore reported prominently, near the top of the report.

Classification follows the template posture (intentional customization vs accidental staleness): a project may legitimately tailor its constitution (e.g. add a project-specific principle), so a diff is not automatically stale. Read both full versions and judge per the Step 4 signals, treating an added project-specific principle as intentional and a structurally-older copy as accidental.

Mandatory missing-principle sub-check (the dangerous case, reported loudly regardless of classification): enumerate the canonical principle headings present upstream and flag any that are absent from the project copy. Principle headings are the ## <n>. <title> lines:

# Canonical principles present upstream:
grep -E '^## [0-9]+\. ' ~/.claude/skills/ETHOS.md
# Project's principles:
grep -E '^## [0-9]+\. ' .adlc/ETHOS.md
# A canonical heading absent from the project copy is a MISSING PRINCIPLE —
# the consumer is silently running an outdated constitution. Report it loudly,
# naming each missing principle by its heading text, even if the file is
# otherwise classified "intentional".

Heading-level comparison (not line-level body text) keeps this robust to legitimate body rewording while still catching a wholesale-missing principle. If .adlc/ETHOS.md is absent entirely, report ethos as missing and recommend /init. If identical, report ethos as clean (one line).