Skip to content
Back to search

adlc-team-skills

Agent skills for the Agentic SDLC: team lifecycle (team-boot, team-learn, team-init, team-repair), software factory, evals, CDR lifecycle with confidence scoring, and ADR/PDR/ChDR decision records. Works with Claude Code, Codex, OpenCode, Cursor, Copilot, and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tikalk/adlc-team-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tikalk/adlc-team-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tikalk--adlc-team-skills/badge.svg)](/listings/tikalk--adlc-team-skills)

HTML

<a href="/listings/tikalk--adlc-team-skills"><img src="/api/listings/tikalk--adlc-team-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx adlc-cli team setup tikalk/adlc-team-skills -a opencode

This installs the skills (via `npx skills add`), generates the `/name` slash commands, wires the event hooks, then runs `/team-setup` headlessly to clone, link, or scaffold your team-ai-directives repo. It writes `.adlc/init-options.json` (agent, skills source, directives path) so every later command knows where things live.

Plain `npx adlc-cli skills add tikalk/adlc-team-skills -a <agent>` installs skills + commands + events without the team configuration.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 713 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # adlc-team-skills
  2. Agent skills that give coding agents your team's context at session start,
  3. so they stop working like strangers.
  4. ## Table of contents
  5. - [How it works](#how-it-works)
  6. - [The developer journey](#the-developer-journey)
  7. - [The problems these skills solve](#the-problems-these-skills-solve)
  8. - [Install](#install)
  9. - [The software factory](#the-software-factory)
  10. - [Universal orchestration](#universal-orchestration)
  11. - [What's inside](#whats-inside)
  12. - [Philosophy](#philosophy)
  13. - [When something goes wrong](#when-something-goes-wrong)
  14. - [Security](#security)
  15. - [Contributing](#contributing)
  16. - [Reference details](#reference-details)
  17. - [Release process](#release-process)
  18. - [License](#license)
  19. ## How it works
  20. It starts the moment you open a session. `team-boot` fires via the
  21. `session_start` event hook and injects a lean index of your team's rules —
  22. roughly a hundred tokens of names and one-line descriptors. Not the rules
  23. themselves. When the active task matches a rule, the agent pulls that
  24. rule's full text on demand. A task touching SQL loads the SQL rule;
  25. nothing else does.
  26. The index lives in a git repo — your [team-ai-directives](https://github.com/tikalk/agentic-sdlc-team-ai-directives) —
  27. versioned, reviewed by PR, shared by the whole team. No more personal
  28. CLAUDE.md files that live on one machine, drift out of date, and don't
  29. transfer between teammates or tools.
  30. When you ask the agent to build something, it doesn't jump to code.
  31. `factory-mission` forces a contract first — goal, constraints, non-goals,
  32. success criteria (the mission-brief format) — then walks `specify → plan → implement ↔ converge`, with
  33. gates, a circuit breaker, resume, and an audit trail. When a session
  34. surfaces a hard-won fix, `team-levelup` extracts it as a Context
  35. Directive Record (CDR), scores it by confidence, and publishes accepted
  36. CDRs back to the team repo. Usage data and confidence scores live in
  37. the `adlc` orphan branch — the next session starts smarter and CDRs
  38. rank by real usage.
  39. Verification, history, and tech selection have loops of their own.
  40. When a rule or skill's behavior needs proof, the `evals-*` skills build
  41. executable graders — binary checks where code can verify, LLM judges only
  42. for what static checks can't — validated with holdout splits and TPR/TNR.
  43. When you touch old code and wonder why it looks like this, `change-init`
  44. mines git history for issue-linked commits and recovers the past-change
  45. rationale as ChDRs. And when a tech choice comes up, `tech-radar-boot`
  46. injects the Tikal Tech Radar's opinion — adoption ring, quadrant — before
  47. the selection is captured as an ADR.
  48. That session loop sits inside a bigger one: **the software factory**.
  49. `factory-queue` triages incoming work, `factory-mission` executes it as
  50. spec-gated missions in isolated worktrees, `factory-review` grades the
  51. resulting PRs against policy-as-code, and `factory-learn` feeds what the
  52. runs taught back into team-ai-directives — with human gates (⭐) at every
  53. decision point. One platform: intake → mission → review → learning.
  54. And because the skills trigger automatically from the index, you don't do
  55. anything special once they're installed. Your coding agent just has your
  56. team's context.
  57. ## The developer journey
  58. What it actually looks like to get from zero to a factory, in order.
  59. ### 0. Prerequisites
  60. - A coding agent (opencode, Claude Code, Cursor, Codex, Gemini CLI, …)
  61. - [`adlc-cli`](https://github.com/tikalk/adlc-cli) — `npx` works, no install needed
  62. - `jq` — required by the setup scripts (they build all JSON output with `jq -n`; missing `jq` fails loudly instead of silently resolving defaults)
  63. ### 1. Install — one command per project
  64. ```bash
  65. npx adlc-cli team setup tikalk/adlc-team-skills -a opencode
  66. ```
  67. This installs the skills (via `npx skills add`), generates the `/name` slash
  68. commands, wires the event hooks, then runs `/team-setup` headlessly to
  69. clone, link, or scaffold your team-ai-directives repo. It writes
  70. `.adlc/init-options.json` (agent, skills source, directives path) so every
  71. later command knows where things live.
  72. Plain `npx adlc-cli skills add tikalk/adlc-team-skills -a <agent>` installs
  73. skills + commands + events without the team configuration.
  74. ### 2. First session — context arrives on its own
  75. Open a session in the project. `team-boot` fires on `session_start` and
  76. injects the index (constitution titles, CDR index ranked by confidence,
  77. Class Boots catalog, skills registry, MCP servers). On an unconfigured
  78. project it points you to `/team-setup`; `/team-constitution` fills in your
  79. team's principles once. There is nothing to remember after this point —
  80. skills trigger when the task matches.
  81. ### 3. Daily work — index, class boots, decision capture
  82. - The agent checks the directives index before any task; full rule bodies
  83. load on demand.
  84. - **Class boots** fire when a decision class shows up: `architect-boot`
  85. (ADR index), `product-boot` (PDR index), `change-boot` (ChDR index),
  86. `tech-radar-boot` (radar opinion before a tech selection).
  87. - **Decision capture is suggested, never automatic**: decisions detected
  88. mid-session surface a `_Suggested capture_` line naming the class capture
  89. skill (`/architect-specify`, `/product-specify`, `/change-specify`, …);
  90. running that skill writes the lightweight draft to
  91. `.adlc/drafts/{adr,pdr,chdr,cdr,evals}/`.
  92. The `file_edited` hook notices each draft landing and nudges the matching
  93. clarify skill (`adr→/architect-clarify`, `pdr→/product-clarify`, …).
  94. - When harness compaction summarizes history away, `session_compact`
  95. re-injects the index.
  96. ### 4. Session end — learnings become records
  97. `team-levelup` fires on `session_end`: it extracts hard-won fixes as CDRs +
  98. paired eval CDRs, scores confidence, batch-reviews them, and publishes
  99. accepted CDRs as a draft PR to team-ai-directives. Drafts and usage reports
  100. live in the `adlc` orphan branch (`drafts/cdr/` + `reports/`).
  101. ### 5. Individual lifecycles — on demand
  102. Each record class has its own skill loop you invoke explicitly:
  103. ```
  104. Product: product-specify|init → product-clarify (accept + promote to memory) → product-implement → product-analyze
  105. Architecture: architect-specify|init → architect-clarify (accept + promote to memory) → architect-implement → architect-analyze
  106. Team: team-init → team-levelup (extract + review + publish) → team-repair (--update-confidence)
  107. Change: change-init → change-clarify → change-publish (change-boot injects the chdr.md index)
  108. Evals: evals-init → evals-specify → evals-clarify → evals-implement → evals-validate
  109. ```
  110. Accepted PDRs/ADRs are promoted to memory on approval — no gap between
  111. "Accepted in drafts" and "moved to memory".
  112. ### 6. The software factory — the outer loop
  113. Running intake → execution → review → learning unattended? The factory
  114. takes over from queue to PR — see [The software factory](#the-software-factory).
  115. ### Ongoing maintenance
  116. ```bash
  117. adlc-cli team update # git pull team-ai-directives + skills update + confidence update
  118. adlc-cli team repair # full repair via agent run (reindex, conflicts, freshness)
  119. adlc-cli team repair --update-confidence # deterministic confidence aggregation (no agent)
  120. ```
  121. `team-repair --build-to-delete` re-runs evals without a rule and proposes
  122. deletion when the model passes anyway; `--validate-drafts` validates draft
  123. files in `.adlc/drafts/` without modifying them.
  124. ## The problems these skills solve
  125. | # | Problem | Fixed by |
  126. |--|--|--|
  127. | 1 | The agent doesn't know how your team works | **`team-*`** — session-start index + on-demand rules |
  128. | 2 | The agent guesses instead of asking | **`factory-mission`** — spec contract before code |
  129. | 3 | The maker grades its own work | **`evals-*`** — binary graders, holdout splits, nothing auto-merges |
  130. | 4 | Session learnings evaporate | **`team-levelup`** — extract fixes as CDRs, publish to the team repo |
  131. | 5 | Product and architecture decisions are invisible | **`product-*`** / **`architect-*`** — PDR→PRD, ADR→AD traceability |
  132. | 6 | "Why was this changed?" is archaeology — rationale lives in nobody's head | **`change-*`** — ChDRs mined from git history's issue-linked commits |
  133. | 7 | The agent picks tech by vibes, not team opinion | **`tech-radar-boot`** — radar context (adoption ring, quadrant) before the ADR |
  134. | 8 | Rules pile up and rot | **`team-repair --build-to-delete`** — rules should shrink over time, not grow; mechanical rules promoted to deterministic CI checks (EVAL-010) |
  135. | 9 | Accepted decisions linger in drafts, not memory | **Clarify-side promotion** — Accepted PDRs/ADRs move to memory on approval (atomic); `sweep_duplicates` catches leftovers; analyze flags duplicates as HIGH |
  136. ## Install
  137. ```bash
  138. # One command: install skills + configure team-ai-directives (runs /team-setup interactively)
  139. npx adlc-cli team setup tikalk/adlc-team-skills -a opencode
  140. # Or just install skills (no team-setup)
  141. npx adlc-cli skills add tikalk/adlc-team-skills -a opencode
  142. # Or plain skills (no commands/events)
  143. npx skills add tikalk/adlc-team-skills -a claude -g
  144. ```
  145. Selective installs resolve closures automatically: `--skill architect-implement`
  146. also pulls its canonical home (`architect-clarify`) via `.skills-deps.json`,
  147. so shared helpers are never orphaned. Factory skills resolve the same way
  148. (`--skill factory-intent` pulls `factory-runbook`). Borrower skills fail fast with the exact
  149. recovery command if their canonical home is missing.
  150. Works with any agent supporting the [Agent Skills standard](https://agentskills.io) —
  151. Claude Code, Codex, OpenCode, Cursor, Copilot, and others.
  152. [`adlc-cli`](https://github.com/tikalk/adlc-cli) wraps `npx skills add`
  153. and additionally generates `/name` slash commands and wires the four event
  154. hooks declared in this repo's `.events.json` — `session_start` and
  155. `session_compact` (team-boot), `session_end` (team-levelup), and `file_edited`
  156. (team-boot, draft-written nudges) — for the 9 coding agents with native
  157. hook support. `team setup` also runs the `/team-setup` skill via
  158. `agent run` to clone, link, or scaffold your team-ai-directives repo.
  159. Skills repos without `.events.json` get commands only.
  160. **First run:** `team-boot` fires at session start. On an unconfigured project
  161. it points you to `/team-setup`, which clones, links, or scaffolds your
  162. team-ai-directives repo. `/team-constitution` fills in your principles.
  163. **Using `agentic-sdlc-spec-kit` alongside this repo?** See
  164. [Coexistence with Spec Kit](docs/spec-kit-integration.md) for the
  165. conflict-free install flow.
  166. ## The software factory
  167. The factory skills are the full outer loop of an agentic SDLC: they take a
  168. brownfield repo from bootstrap all the way to merged, reviewed PRs — and
  169. turn what each run learned into team memory. Every automated stage is
  170. advisory; humans hold the gates (⭐).
  171. ```
  172. brownfield repo
  173. │
  174. ▼
  175. ┌─────────────────┐ unified bootstrap: product → architect → change
  176. │ factory-init │ tracks + PDR↔ADR↔ChDR↔code coverage matrix
  177. └────────┬────────┘ (--refresh = recurring alignment sweep)
  178. │ PRD.md · AD.md · .adlc/memory/
  179. ▼
  180. ┌──────────────────────────┐ PDRs → PRD.md · ADRs → AD.md
  181. │ factory-intent │ (two scope-pinned gates)
  182. │ (product + arch lanes) │
  183. └────────┬─────────────────┘
  184. │ Mission Brief (goal + constraints + success criteria)
  185. ▼
  186. Intent Gate ⭐ (human approves the brief; AI triage scores are advisory)
  187. │
  188. ▼
  189. ┌─────────────────┐ spec-gated into the tracker (the Q, single source of truth)
  190. │ factory-queue │
  191. └────────┬────────┘
  192. │ --issue ref
  193. ▼
  194. ┌─────────────────┐ inner loop: specify → plan → implement ↔ converge
  195. │ factory-mission │ (comment bus · worktrees · TDD test/code split · circuit breaker)
  196. └────────┬────────┘
  197. │ agent-authored PR
  198. ▼
  199. ┌─────────────────┐
  200. │ factory-review │──▶ Merge Gate ⭐ (human code-owner approval)
  201. └────────┬────────┘
  202. ▼
  203. ┌─────────────────┐ CDRs/ChDRs → team-ai-directives PR
  204. │ factory-learn │ workflow memories → memory.jsonl
  205. └────────┬────────┘
  206. │
  207. └─▶ back to factory-mission (memories)
  208. + team-boot (CDR index — closes the context loop)
  209. ```
  210. What each station adds:
  211. - **`factory-setup`** — one command wires a repo to its issue tracker:
  212. provider pick (detect-from-remote, explicit, or already-configured),
  213. writes `.adlc/issues-provider.yml` (never credentials, never overwrite).
  214. - **`factory-init`** — one command onboards an existing repo onto ADLC and
  215. emits the PDR↔ADR↔ChDR↔code coverage matrix (`--refresh` for the
  216. recurring alignment sweep).
  217. - **`factory-queue`** — mission brief intake: AI-assisted advisory triage
  218. scoring, intent gate, gating label stamping, milestones/epics generation.
  219. - **`factory-mission`** — the execution engine: spec-gated inner loop
  220. (specify → plan → implement ↔ converge) with tracker-agnostic integration,
  221. an inter-agent comment bus, worktree isolation, lease-based liveness,
  222. stall detection, a dependency hard gate (Operation 12 — intake refuses
  223. while declared dependencies stay open; only closed/cancelled counts
  224. complete, dependents machine-notified on clear),
  225. stall detection, and a mandated TDD test/code split (RED gate + GREEN gate,
  226. enforced at the skill level, not just the prompt level).
  227. - **`factory-review`** — severity-ranked PR compliance against REVIEW.md
  228. policy-as-code; babysits agent PRs to merge, never auto-merges past the
  229. human gate. `--self-heal` runs a three-sub-agent converge loop
  230. (Review→Fix→Converge) with maker-checker separation and circuit breaker.
  231. - **`factory-learn`** — retrospectives into team-ai-directives:
  232. build-to-delete pruning, promote-to-check for mechanical rules.
  233. - **`factory-intent`** — merged two-lane intent orchestrator
  234. maintaining PRD.md and AD.md with clarify⭐ gates.
  235. - **`factory-orchestrator`** — front-door router: accepts work at any
  236. lifecycle stage (new request, CI failure on a delivered PR, review
  237. findings, merge notification), detects the stage from tracker/run
  238. evidence, and hands it to the owning skill, human gate, or follow-up
  239. context. Router and communicator only — never implements, reviews,
  240. or merges itself.
  241. - **`factory-tickets`** — read-only worklist across trackers, classified by
  242. next actionable move.
  243. - **`factory-clean`** — resource inventory and reclamation, approval-gated.
  244. <details>
  245. <summary><strong>Detailed wiring</strong></summary>
  246. ```mermaid
  247. flowchart LR
  248. FQ["factory-queue<br/>Ingestion & Triage"] ~~~ IG{"Intent Gate"}
  249. FI2["factory-intent<br/>Merged Two-Lane DAG"] ~~~ CG1{"product Gate"} & CG1 ~~~ CG2{"architecture Gate"}
  250. FM["factory-mission<br/>Execution Engine"] ~~~ CB{"Circuit Breaker"}
  251. FR["factory-review<br/>PR Compliance"] ~~~ MG{"Merge Gate"}
  252. FL["factory-learn<br/>Learning Loop"] ~~~ CG3{"clarify⭐ Gate"}
  253. FC["factory-clean<br/>Resource Cleanup"] ~~~ UG{"Approval Gate"}
  254. FT["factory-tickets<br/>Read-Only Worklist"]
  255. FO["factory-orchestrator<br/>Front-Door Router"]
  256. FI["factory-init<br/>Brownfield Bootstrap"]
  257. TR[("Issue Tracker<br/>GitHub / GitLab / Linear / Jira")]
  258. TD[["team-ai-directives<br/>repo"]]
  259. FQ -->|"spec-gated labels"| TR
  260. TR -->|"--issue ref"| FM
  261. FI2 -->|"PRD.md + AD.md"| FQ
  262. FM -->|"agent-authored PRs"| TR
  263. TR -->|"PR diff + checks"| FR
  264. FR -->|"twice-mistake rule"| FL
  265. FL -->|"memory.jsonl"| FM
  266. FL -->|"draft PR"| TD
  267. FC -.->|"reads state files"| FM
  268. FO -->|"new work requests"| FQ
  269. FO -.->|"CI failure / merge notification follow-ups"| FM
  270. FT -.->|"read-only"| TR
  271. FI -.->|"via intent lanes"| FI2
  272. ```
  273. </details>
  274. ## Universal orchestration
  275. `factory-mission` doesn't lock you into a proprietary ecosystem. Step prompts
  276. name skills by exact name; the dispatched subagent resolves them through its
  277. own harness Skill tool (the runtime injects the installed-skills inventory —
  278. no filesystem scan). For commands-based frameworks the model cannot see, the
  279. commands-dir fallback in `references/agent-integrations.md` covers discovery.
  280. Routing stays LLM-decided — no hard-coded phase-to-skill mapping. Works
  281. alongside:
  282. | Source | Examples |
  283. |---|---|
  284. | [mattpocock/skills](https://github.com/mattpocock/skills) | `/tdd`, `/grill-me`, `/code-review` |
  285. | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | Exit-criteria checklists |
  286. | [superpowers](https://github.com/obra/superpowers) | Workflow skills |
  287. | spec-kit / [agentic-sdlc-spec-kit](https://github.com/tikalk/agentic-sdlc-spec-kit) / OpenSpec | SDD command frameworks |
  288. | This repo | `product-specify`, `architect-specify`, `evals-validate`, `team-levelup` |
  289. | Your own | Anything following the `SKILL.md` standard |
  290. ## What's inside
  291. 48 skills across 8 categories.
  292. ### Team directives — every session, every user
  293. - **`team-boot`** — session-start bootstrap; injects the always-relevant layer (constitution titles, CDR index ranked by confidence, Class Boots catalog, skills registry) and dispatches to per-class boots on demand. Auto-triggered; re-declared for `session_compact` so the index survives harness compaction. Also fires the session-end friction trigger for CDR capture, and `file_edited` draft-written nudges suggesting the matching clarify skill.
  294. - **`team-setup`** — clone, link, or scaffold a team-ai-directives repo.
  295. - **`team-constitution`** — define or amend team principles interactively.
  296. - **`team-discover`** — manual re-scan; structured match table (`/team-discover`).
  297. - **`team-repair`** — re-index, conflict scan, freshness, `--build-to-delete`, `--validate-drafts`, deterministic-enforcement coverage check.
  298. - **`team-skills`** — browse/install team skills from the directives repo.
  299. - **`team-diagnose`** — evidence-first diagnosis when team context doesn't appear: walks the chain (init-options → jq → boot.sh → artifact sync) and routes injection-side bugs to adlc-cli.
  300. ### The software factory — the outer loop
  301. - **`factory-init`** — unified brownfield bootstrap + PDR↔ADR↔ChDR↔code coverage matrix (`--refresh`).
  302. - **`factory-queue`** — queue intake, AI advisory triage scoring, intent gate, milestone generation.
  303. - **`factory-mission`** — execution engine: tracker-agnostic, comment bus, worktree isolation, mandated TDD RED/GREEN gates (Test Agent writes failing tests first, Implement Agent writes code to pass them), circuit breaker.
  304. - **`factory-intent`** — merged intent orchestrator (product + architecture lanes, two gates).
  305. - **`factory-runbook`** — shared run mechanics, invoked by orchestrators: publish procedure (run branch → step commits → draft MR/PR with milestone/assignee ownership) plus the run contracts (executor, tracker integration, lanes, brief/provider templates) borrowed by path, never copied.
  306. - **`factory-release`** — post-merge release orchestration: exact-head gated merge → staged rollout with threshold verdicts → SemVer-tagged, noted release with monitor handoff.
  307. - **`factory-learn`** — continuous improvement loops targeting team-ai-directives: build-to-delete pruning, promote-to-check (EVAL-010) for mechanical rules.
  308. - **`factory-tickets`** — read-only personal worklist across trackers.
  309. - **`factory-clean`** — resource inventory and reclamation (approval-gated).
  310. ### Mission-driven development
  311. - **`factory-mission`** — spec-contract pipeline with converge loop, circuit breaker, resume (`factory-mission "feature"`, `--resume`).
  312. ### Learning loop (CDR lifecycle)
  313. - **`team-levelup`** — session-end CDR lifecycle: extract patterns, score confidence, batch review (A/B/C/D/P), and publish accepted CDRs as a draft PR. Auto-triggers on `session_end` event. Drafts live in the `adlc` orphan branch of team-ai-directives (`drafts/cdr/` + `reports/` for usage data).
  314. - **`team-init`** — brownfield CDR discovery from an existing codebase. Writes to the `adlc` branch; handoff to `team-levelup` for review/publish.
  315. - **`team-repair --update-confidence`** — aggregate usage data from the `adlc` branch into confidence scores, update OKF frontmatter, rebuild CDR.md with confidence column. `team-boot` ranks CDRs by confidence in the injected index.
  316. ### Evals — verification over vibes
  317. - **`evals-init`** — scaffold `evals/{system}/` with security baseline.
  318. - **`evals-specify`** — extract criteria from specs / failure traces.
  319. - **`evals-clarify`** — cluster, isolate holdout, publish goldset.
  320. - **`evals-implement`** — generate graders + unit tests.
  321. - **`evals-validate`** — run evaluation pyramid, TPR/TNR + SLA headroom.
  322. - **`evals-analyze`** — route failures to deterministic checks, context rules, or evaluator backlog.
  323. ### Product & architecture lifecycles
  324. - **`product-boot`** / **`product-init`** / **`product-specify`** — PDR index, brownfield discovery, greenfield creation.
  325. - **`product-clarify`** — refine and approve. **`product-implement`** — generate `PRD.md`.
  326. - **`product-analyze`** — PDR↔PRD consistency. **`product-roadmap`** — milestone progress across decision, execution, evidence, and gate layers.
  327. - **`architect-boot`** / **`architect-init`** / **`architect-specify`** — ADR index, reverse-engineering, creation (routes tech selection through `tech-radar-boot`).
  328. - **`architect-clarify`** — refine. **`architect-implement`** — generate `AD.md`. **`architect-analyze`** — ADR↔AD consistency.
  329. ### Change history (ChDRs)
  330. - **`change-boot`** — class boot: injects the `chdr.md` index when past-change rationale matters + ChDR mining capture.
  331. - **`change-init`** — mine git history for Change Decision Records via issue-linked commits.
  332. - **`change-clarify`** — review mined ChDRs (provenance gate on Decision claims).
  333. - **`change-publish`** — promote accepted ChDRs to `.adlc/memory/chdr/`.
  334. ### Tech selection
  335. - **`tech-radar-boot`** — class boot: injects Tikal Tech Radar context (adoption ring, quadrant, opinion) for tech selection + ADR capture pairing. Auto-triggered. The radar is read from the **adlc-radar OKF knowledge repository** (`gitlab.tikalk.dev/tikalk/engineering/agentic-sdlc/adlc-radar`, `knowledge/technologies/`) through a cached shallow clone refreshed every 3 days; when the repository is unreachable it says so and falls back to the stale clone, then to the public `https://tikalk.com/radar.json` — always announcing which source answered.
  336. ### Workspace
  337. - **`workspace`** — multi-repo workspace: `--init` creates `.adlc/` structure, discover/link/audit child repos (`--link`, `--status`, `--ignore-only`).
  338. ### Skill authoring — contributors
  339. - **`writing-skills`** — TDD-for-skills: baseline the failure without the skill (RED), write the minimal skill (GREEN), close rationalization loopholes (REFACTOR). Iron Law: no skill without a failing baseline first (EVAL-011). Includes the `SKILL.md` template and the testing methodology.
  340. ## Philosophy
  341. - **Index, not injection.** Long contexts measurably degrade LLM performance —
  342. even with perfect retrieval
  343. ([arXiv:2510.05381](https://arxiv.org/abs/2510.05381), 13.9%–85% degradation
  344. by length alone). Agents get an index by default and pull full rules only
  345. when relevant. If your instinct is "more rules in context don't work" —
  346. we agree. That's the design.
  347. - **Rules should shrink over time, not grow.** Base models improve;
  348. yesterday's scaffolding becomes today's context noise. `--build-to-delete`
  349. re-runs evals without a rule and proposes deletion when the model passes
  350. anyway. Mechanical rules that survive are flagged for promotion to
  351. deterministic checks.
  352. - **Evidence over vibes.** Anything code can check gets a binary grader —
  353. plain assertions, Tier 1. LLM judges are Tier 2, reserved for what
  354. static checks can't verify. Nothing auto-merges; pipelines end at a PR a
  355. human reviews.
  356. - **Decisions as code.** Every decision class — product (PDR), architecture
  357. (ADR), change (ChDR), context (CDR) — lives in version-controlled repos
  358. with a draft → clarify → accept → promote → publish → analyze lifecycle,
  359. and traces from record to document to code. Accepted records are promoted
  360. to memory atomically with approval — never left in drafts.
  361. ## When something goes wrong
  362. - **Team context didn't appear at session start** — check `.adlc/init-options.json`
  363. points at an existing team-ai-directives checkout; on an unconfigured
  364. project run `/team-setup`. The `session_start` hook (`.events.json` →
  365. dispatcher → `team-boot`'s `scripts/boot.sh`) needs `jq` available. Full
  366. chain contract: [docs/event-hook-contract.md](docs/event-hook-contract.md);
  367. run `scripts/acceptance-test.sh` to verify the whole loop from scratch.
  368. For evidence-first diagnosis of injection failures, run `/team-diagnose`
  369. (traces init-options → jq → boot.sh → artifact sync → injection; EVAL-013).
  370. - **Team context vanished mid-session after compaction** — re-injection
  371. after compaction is a declared contract (`session_compact` in
  372. `.events.json`); the injection side is implemented by
  373. [adlc-cli](https://github.com/tikalk/adlc-cli) — if your
  374. agent's adapter doesn't map the event yet, file it there.
  375. - **Skill descriptions or commands look stale** — the install layer is
  376. CLI-generated (`.agents/skills/`, `.opencode/commands/`, `skills-lock.json`).
  377. Regenerate: `npx adlc-cli skills add tikalk/adlc-team-skills -a <agent> -y`.
  378. `tests/unit/test_generated_artifacts_sync.py` catches drift locally.
  379. - **Index is inconsistent or rules conflict** — run `/team-repair`
  380. (re-index, conflict scan, freshness check, orphan detection).
  381. - **Something else** — [open an issue](https://github.com/tikalk/adlc-team-skills/issues).
  382. To verify a suspected skill-behavior bug yourself, follow the
  383. [manual testing protocol](CONTRIBUTING.md#manual-testing) (scratch project,
  384. real agent, report table). The repo's testing model — two directories,
  385. three tiers — is mapped in [docs/testing.md](docs/testing.md).
  386. ## Security
  387. On 2026-07-27 a supply-chain worm briefly injected a malicious payload into
  388. this repo's `.claude/` and `.vscode/` directories via a stolen maintainer
  389. token (exposure window ~11:06–18:30 UTC). The payload only executed if you
  390. cloned the repo and opened it in VS Code or started a Claude Code session
  391. inside it; the `npx skills` install path never shipped or ran those files.
  392. History was rewritten to strip the payload from all commits and tags, tokens
  393. and secrets were rotated, and branch protection now blocks the vector used.
  394. Details and remediation steps: [issue #1](https://github.com/tikalk/adlc-team-skills/issues/1).
  395. Lesson for any repo: treat `.vscode/tasks.json` and `.claude/settings.json`
  396. in a clone as executable code, and disable editor auto-run tasks.
  397. ## Contributing
  398. See [CONTRIBUTING.md](CONTRIBUTING.md). New skills must be agreed in an
  399. issue first, ship with eval coverage, and follow the `writing-skills`
  400. methodology — no skill without a failing baseline first.
  401. ## Reference details
  402. <details>
  403. <summary><strong>Repository layout</strong></summary>
  404. Skills are organized into category subdirectories under `skills/`, ordered
  405. by the pull each family has on a typical session (team first):
  406. ```
  407. skills/
  408. ├── team/ # team-* (9) + workspace + templates/ (team-helpers canonical in team-setup)
  409. ├── evals/ # evals-* (6) + evals-templates/
  410. ├── product/ # product-* (7) + product-templates/ + templates/ (pdr-lib canonical in product-clarify)
  411. ├── architect/ # architect-* (6) + templates/ (setup-architect + generators canonical in architect-clarify)
  412. ├── change/ # change-* (4) + templates/
  413. ├── tech-radar/ # tech-radar-boot (1) — OKF knowledge repo reader (cached clone + public-JSON fallback)
  414. ├── authoring/ # writing-skills (1; templates live inside the skill)
  415. └── factory/ # factory-* (10) — platform orchestration
  416. ```
  417. This places every single skill exactly 2 levels deep, fully resolving the
  418. default depth limit of the `skills` CLI and ensuring all skills install
  419. out of the box. (Enforced by `tests/unit/test_playbook_integrity.py`.)
  420. Each skill family shares a `{family}/templates/` directory instead of
  421. duplicating templates per-skill (evals and product retain their
  422. `-templates/` names for compatibility).
  423. </details>
  424. <details>
  425. <summary><strong>Output File Layout</strong></summary>
  426. All skills write to `.adlc/` (project root) and the team AI directives repo.
  427. **Team Directives** (inside the team AI directives repository):
  428. - `AGENTS.md` — agent instructions (loading order, rules, skills)
  429. - `CDR.md` — index of approved context contributions
  430. - `.skills.json` — skills manifest (schema v2.0.0)
  431. - `.mcp.json.example` — MCP servers config example
  432. - `context_modules/constitution.md` — team constitution (OKF frontmatter)
  433. - `context_modules/{rules,personas,examples}/**/*.md` — context modules
  434. - `context_modules/{type}/index.md` — progressive disclosure per concept type
  435. - `context_modules/{type}/log.md` — chronological change log per concept type
  436. - `skills/{name}/SKILL.md` + `.skills-entry.json` — published team skills
  437. - `evals/{directive-id}/goldset.md` + `goldset.json` — directive compliance goldensets
  438. **team-levelup** (inside `.adlc/` of the target project):
  439. - `adlc branch drafts/cdr/CDR-{NNN}.md` — proposed/discovered CDRs (including eval CDRs)
  440. - `adlc branch drafts/cdr/cdr.md` — auto-generated CDR index
  441. - `.adlc/init-options.json` — team AI directives path config
  442. **Product** (inside `.adlc/` and repo root):
  443. - `.adlc/drafts/pdr/PDR-{NNN}.md` — proposed/discovered PDRs
  444. - `.adlc/drafts/pdr/pdr.md` — auto-generated PDR index
  445. - `.adlc/memory/pdr/PDR-{NNN}.md` — accepted/completed PDRs
  446. - `.adlc/memory/pdr/pdr.md` — accepted PDR index
  447. - `.adlc/product/sections/{feature-area}/{section}.md` — PRD section build artifacts
  448. - `.adlc/product/state.json` — DAG execution state
  449. - `PRD.md` — Product Requirements Document (repo root)
  450. **Architecture** (inside `.adlc/` and repo root):
  451. - `.adlc/drafts/adr/ADR-{NNN}.md` — proposed/discovered ADRs
  452. - `.adlc/drafts/adr/adr.md` — auto-generated ADR index
  453. - `.adlc/memory/adr/ADR-{NNN}.md` — accepted ADRs
  454. - `.adlc/memory/adr/adr.md` — accepted ADR index
  455. - `AD.md` — Architecture Description (repo root)
  456. - `.adlc/architect/` — per-view DAG artifacts
  457. **Missions** (inside `.adlc/` of the target project):
  458. - `.adlc/workflows/runs/<run_id>/` — the durable run archive: `brief.md`
  459. (the worker brief), `mission.yml` (execution/supervision/budgets policy),
  460. `state.json` (program counter, written via the `adlc-cli workflow state`
  461. helpers), `lease.json` (strict run lease, shared run state), `scratchpads/`,
  462. `findings/`, `decisions/`, `artifacts/`, `iterations.md`
  463. - `.adlc/workflows/<run_id>/workflow.yml` — generated-by-slug workflow
  464. definition (the workflow namespace)
  465. - `.adlc/workflows/memory.jsonl` — cross-run workflow memory
  466. (workspace-global; read/write by `factory-learn` retrospectives)
  467. - `.adlc/worktrees/<run_id>/` — isolated mission worktrees
  468. - `refs/factory-runs/<run_id>` — git-refs Tier-3 transport of the run
  469. archive (git-refs run state)
  470. **Governance** (inside target project and repo root):
  471. - `.adlc/drafts/evals/EVAL-{NNN}.md` — proposed/discovered eval criteria drafts
  472. - `.adlc/drafts/evals/evals.md` — draft evals index
  473. - `.adlc/memory/evals/EVAL-{NNN}.md` — accepted/completed eval criteria
  474. - `.adlc/memory/evals/evals.md` — accepted evals index
  475. - `.adlc/memory/evals/holdout.json` — isolated/reserved holdout test dataset
  476. - `.adlc/coverage/coverage.md` — factory-init PDR↔ADR↔ChDR↔code coverage matrix
  477. - `evals/{system}/goldset.md` — published goldset (human-readable)
  478. - `evals/{system}/goldset.json` — published goldset (machine-readable)
  479. - `evals/{system}/config.yml` — evaluation framework configuration
  480. - `evals/{system}/config.{js,py}` — framework test config
  481. - `evals/{system}/graders/check_*.py` — generated binary Python graders / metrics
  482. - `evals/{system}/tests/test_check_*.py` — generated unit tests verifying grader correctness
  483. - `evals/results/validation_report.md` — statistical validation results report
  484. **Workspace** (inside parent repo root):
  485. - `.gitmodules` — Git submodule registrations for child repos (created by `--link`)
  486. - `.adlc/` — shared team context (PDRs, ADRs, CDRs); parent is the single source of truth
  487. - Child repos discovered at depth 1; each child's `.adlc/` presence is reported (informational)
  488. </details>
  489. <details>
  490. <summary><strong>OKF Compliance</strong></summary>
  491. Generated context modules include [Open Knowledge Format (OKF) v0.2](https://blog.agentics.org/open-knowledge-format/) compliant frontmatter alongside custom fields.
  492. | OKF field | Status | Source |
  493. |-----------|--------|--------|
  494. | `type` | ✅ | CDR context type (Constitution/Persona/Rule/Example/Skill) |
  495. | `title` | ✅ | CDR title |
  496. | `description` | ✅ | CDR descriptor |
  497. | `tags` | ✅ | Context type tag |
  498. | `generated` | ✅ | ISO 8601 datetime + author |
  499. | `verified` | ✅ | ISO 8601 datetime + verifier |
  500. | `status` | ✅ | stable / draft / deprecated |
  501. | `stale_after` | ✅ | e.g., `180d` — freshness window for team-repair |
  502. Custom fields co-exist with OKF frontmatter: `id`, `cdr_ref`, `created`, `modified`, `verified`, `age_days`, `evidence`.
  503. Directory structure: `context_modules/{type}/index.md` (progressive disclosure), `context_modules/{type}/log.md` (change history), cross-links between related concepts.
  504. </details>
  505. <details>
  506. <summary><strong>Workflows</strong></summary>
  507. **Team Directives setup:**
  508. ```
  509. team-setup → team-constitution → team-boot (auto at session start)
  510. ```
  511. **Product lifecycle:**
  512. ```
  513. Brownfield: product-init → product-clarify → product-implement → product-analyze
  514. Greenfield: product-specify → product-clarify → product-implement → product-analyze
  515. Roadmap: product-roadmap (anytime)
  516. ```
  517. **Architecture lifecycle:**
  518. ```
  519. Brownfield: architect-init → architect-clarify → architect-implement → architect-analyze
  520. Greenfield: architect-specify → architect-clarify → architect-implement → architect-analyze
  521. ```
  522. **CDR lifecycle:**
  523. ```
  524. Brownfield: team-init → team-levelup (extract + review + publish) → team-repair
  525. Session: team-levelup (extract + review + publish) → team-repair
  526. History: change-init → change-clarify → change-publish (change-boot injects chdr.md)
  527. Build to Delete: team-repair --build-to-delete → team-levelup (review deletion CDRs)
  528. Confidence: team-repair --update-confidence → team-boot (ranks CDRs by confidence)
  529. ```
  530. **Mission:**
  531. ```
  532. factory-mission "feature" → review brief → execute steps → converge → run archive (.adlc/workflows/runs/<run_id>/)
  533. ```
  534. **Multi-repo workspace:**
  535. ```
  536. workspace --init → create .adlc/ structure + configure .gitignore
  537. product-specify / architect-specify → create shared PDRs/ADRs in parent .adlc/
  538. workspace --link → register child repos as submodules
  539. workspace --status → audit branch, dirty, unpushed, SHA drift
  540. ```
  541. **Application Evaluation lifecycle:**
  542. ```
  543. Greenfield (Spec-Driven): evals-init → evals-specify (from spec) → evals-clarify → evals-implement → evals-validate
  544. Brownfield (Error-Driven): evals-init → evals-specify (from failures) → evals-clarify → evals-implement → evals-validate → evals-analyze
  545. ```
  546. </details>
  547. <details>
  548. <summary><strong>12-Factor Alignment</strong></summary>
  549. This repo implements the [Twelve-Factor Agentic SDLC](https://github.com/tikalk/agentic-sdlc-12-factors).
  550. | Factor | Skills | How |
  551. |--------|--------|-----|
  552. | **III — Mission Definition** | Product skills | PRD/PDR lifecycle ensures product decisions are documented, reviewed, and traceable before execution |
  553. | **IV — Structured Planning** | Architecture skills | ADRs and AD.md provide structured planning artifacts using Rozanski & Woods viewpoints |
  554. | **VII — Verification-First Evals** | team-levelup + Evals skills | team-levelup creates directive-compliance eval CDRs; evals skills build and run application-level evaluation suites (PromptFoo/DeepEval) with binary graders, holdout splits, and statistical validation |
  555. | **VIII — Ratchet Effect** | team-levelup + Evals skills | Each session extracts eval CDRs alongside directive CDRs; each goldset publication adds criteria that monotonically increase quality — `evals-clarify` publishes, `evals-validate` enforces |
  556. | **IX — Traceability** | Product + Architecture | Every decision traces from PDR → PRD → feature and from ADR → AD → code |
  557. | **X — Context Engineering** | Team Directives | `team-boot` assembles constitution, CDR index (ranked by confidence), and the Class Boots catalog into the system prompt at session start; the class boots load ADR/PDR/ChDR/CDR/radar context on demand, each paired with decision capture; `team-discover` provides manual re-scan |
  558. | **XI — Directives as Code** | Team + team-levelup + Product + Architecture | All directive lifecycles (CDR, PDR, ADR) live in version-controlled repos; CDR drafts and usage reports live in the `adlc` orphan branch of team-ai-directives (`drafts/cdr/` + `reports/`); each lifecycle has extract → review → publish → analyze stages |
  559. | **XII — Build to Delete** | team-repair + evals-analyze | `--build-to-delete` runs evals without directives via LLM calls; if model passes, proposes deletion (Harness Decay); `--update-confidence` aggregates usage data into OKF frontmatter confidence scores; `evals-analyze` routes spec failures to `team-levelup` (rules) and generalization failures to the evaluator backlog — the feedback loop that makes build-to-delete verifiable |
  560. ### Deck ↔ code glossary (the deck-code glossary)
  561. Canonical names live in code; deck terms map to them (code is ground truth, except Pair 1 where the concept itself is harness-agnostic):
  562. | Deck term | Code term | Resolution |
  563. |-----------|-----------|------------|
  564. | `plan.md` (approved before code) | `brief.md` + `workflow.yml` + step list (approved plan-of-record) | Agnostic concept — both are instances, valid for any SDD skills |
  565. | `evidence-chain.md` | Audit trail (comment bus + `runs/<id>/`) | Code wins — deck adopts "audit trail" |
  566. | Triage / Clarify Agents | `factory-queue` triage scoring + inline clarify gates | Code wins, no skill split (revisit if scoring grows independent owners/evals) |
  567. | "Lit Factory" / "Ratchet Effect" | Factory orchestrators / `team-levelup` + Twice-Mistake Threshold | Keep both — evocative deck names mapped to code refs |
  568. | `mission-brief` skill | `factory-mission` | Settled by history (renamed) |
  569. | `team-learn` | `team-levelup` | Settled by history (v0.30.0 hard rename) |
  570. </details>
  571. ## Release process
  572. See [RELEASE.md](./RELEASE.md) for the release runbook, tag naming conventions, security design, and recovery procedures.
  573. ## License
  574. MIT — see [LICENSE](./LICENSE).
skills/factory/factory-review/scripts/bash/check-verdict-head.sh · Bundled script · 462 lines · 2 findings marked
  1. #!/usr/bin/env bash
  2. # Verify that the latest factory-review verdict names the current PR head.
  3. #
  4. # CDR-022 exemption (no PowerShell twin): invoked only by CI
  5. # (.github/workflows/verdict-head.yml) on ubuntu runners, where bash is
  6. # guaranteed; a Windows twin would have no caller.
  7. #
  8. # A factory-review verdict certifies exactly ONE head SHA — the one carried in
  9. # its `head=<sha>` marker. Any push after the verdict (a fix, a rebase, a
  10. # force-push) moves the head and invalidates it, so the review must run again
  11. # on the new head before merge-readiness is claimed.
  12. #
  13. # The skill states that rule; this script makes it mechanical: it reads the
  14. # PR's comments and review bodies, finds the latest factory-review review
  15. # verdict, and compares the head it names with the head being merged.
  16. #
  17. # Usage:
  18. # check-verdict-head.sh --repo <owner/repo> --pr <number> --pr-head <sha>
  19. # check-verdict-head.sh --verdicts <file> --pr-head <sha> # offline
  20. # ... [--require-outcome]
  21. #
  22. # Exit codes (default mode — a staleness check):
  23. # 0 = no factory-review verdict, or the verdict names the current head
  24. # 1 = the verdict is stale or unbound — the review must be re-run on this head
  25. # 2 = usage or infrastructure error (bad arguments, unreadable comments)
  26. #
  27. # --require-outcome upgrades the check from "is this verdict current?" to the
  28. # merge gate "may this PR merge?". The head being current answers only the
  29. # first question: a verdict can name the current head and still be a
  30. # not-merge-ready verdict, or one reporting open Important findings. With the
  31. # flag set the gate additionally fails (exit 1) on a verdict that:
  32. # - does not exist at all (an unreviewed PR is not merge-ready)
  33. # - omits `outcome=` or `important=` from its marker (fails closed — a
  34. # marker published before this schema cannot claim merge-readiness by
  35. # silence)
  36. # - carries `outcome=not-merge-ready`
  37. # - carries `important=` greater than zero (this repository's review policy
  38. # treats an open Important finding as blocking a merge)
  39. # - carries an `outcome=` or `important=` value that is not a legal one
  40. # The head rules are unchanged: the gate is an additional question, not a
  41. # replacement, so a stale or unbound head still fails under the flag.
  42. #
  43. # EVERYTHING THAT COMES BACK FROM GITHUB IS UNTRUSTED. The repository is
  44. # public: any account can comment, and a comment body can say anything. A
  45. # body therefore never reaches the parser. jq extracts the fields the checker
  46. # needs — the timestamp, the author, the author's association with the
  47. # repository, and the head named inside the `<!-- factory-review:step=review
  48. # … -->` marker — and hands back one tab-separated record per comment or
  49. # review. A body can therefore neither create a record nor choose where that
  50. # record sits in the ordering, and no value a body carries (a timestamp, a
  51. # head, a separator line) can reach the comparison.
  52. #
  53. # The head is read from INSIDE the marker only: a `head=<sha>` that appears in
  54. # prose — outside any marker — is never read. The value must be a full
  55. # 40-character SHA.
  56. #
  57. # A verdict counts only when it comes from an account that collaborates with
  58. # the repository (owner, organization member, collaborator). When no such
  59. # account has posted a verdict, the newest verdict of any author is used
  60. # instead — the check must never turn green because it declined to read the
  61. # only verdict there is.
  62. #
  63. # The --verdicts file holds one or more records; a line of three percent
  64. # signs separates them and the LAST record is the newest. That separator is a
  65. # local fixture convention only: nothing that arrives over the network is
  66. # ever split on it.
  67. set -u
  68. export LC_ALL=C
  69. REPO=""
  70. PR=""
  71. PR_HEAD=""
  72. VERDICTS_FILE=""
  73. REQUIRE_OUTCOME=0
  74. usage_error() {
  75. echo "check-verdict-head: $*" >&2
  76. exit 2
  77. }
  78. # A flag must be followed by a value. Without this check, `shift 2` on a
  79. # trailing flag fails without shifting and the parser loops forever.
  80. require_value() {
  81. if [ "$2" = "" ]; then
  82. usage_error "$1 requires a value"
  83. fi
  84. }
  85. while [ "$#" -gt 0 ]; do
  86. case "$1" in
  87. --repo) require_value "$1" "${2:-}"; REPO="$2"; shift 2 ;;
  88. --pr) require_value "$1" "${2:-}"; PR="$2"; shift 2 ;;
  89. --pr-head) require_value "$1" "${2:-}"; PR_HEAD="$2"; shift 2 ;;
  90. --verdicts) require_value "$1" "${2:-}"; VERDICTS_FILE="$2"; shift 2 ;;
  91. --require-outcome) REQUIRE_OUTCOME=1; shift ;;
  92. --help|-h) awk 'NR>1 && /^#/ { sub(/^# ?/, ""); print; next } NR>1 { exit }' "$0"
  93. exit 0 ;;
  94. *) usage_error "unknown argument '$1'" ;;
  95. esac
  96. done
  97. if [ -z "$PR_HEAD" ]; then
  98. usage_error "--pr-head <sha> is required"
  99. fi
  100. # The jq library: the ONLY place that ever looks at a comment body.
  101. #
  102. # `verdict_record` answers one question about a body: does it carry a
  103. # factory-review verdict marker, and what does that marker declare? It
  104. # returns a state (none / unbound / malformed / ok), the head it names, and
  105. # the marker's outcome and important-count, never the body itself. Everything
  106. # it returns is validated: the timestamp must be a full ISO-8601 UTC instant,
  107. # the head must be a full 40-character SHA, the outcome must be one of the two
  108. # legal verdicts, the important-count must be a non-negative integer, and the
  109. # author and the author's association are reduced to safe alphabets. The
  110. # marker region is taken from the text between `<!--` and the marker's own
  111. # closing `-->`, so a `head=` that appears in prose — outside any marker — is
  112. # never read.
  113. #
  114. # An absent field and an illegal one are kept apart: `-` means the marker
  115. # declared nothing, `invalid` means it declared something that is not a legal
  116. # value. The merge gate treats both as failures, but for different reasons —
  117. # one is a marker published before this schema, the other is a marker that
  118. # violates it — so the script can say which.
  119. JQ_LIB=$(cat <<'JQEOF'
  120. def iso_ts: if test("^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$") then . else "-" end;
  121. def trim_ws: sub("^[[:space:]]+"; "");
  122. def marker_regions:
  123. [ . | split("<!--")[1:][]
  124. | select(contains("-->"))
  125. | (trim_ws | split("-->")[0]) as $seg
  126. | select($seg | startswith("factory-review:step=review"))
  127. | $seg ];
  128. def head_token:
  129. ( [ splits("\\s+") | select(length > 0) | select(startswith("head=")) | .[5:] ] | .[0] // "-" );
  130. def outcome_token:
  131. ( [ splits("\\s+") | select(length > 0) | select(startswith("outcome=")) | .[8:] ] | .[0] // "-" );
  132. def important_token:
  133. ( [ splits("\\s+") | select(length > 0) | select(startswith("important=")) | .[10:] ] | .[0] // "-" );
  134. def verdict_record:
  135. if (test("factory-review:step=review") | not) then {state: "none", head: "-", outcome: "-", important: "-"}
  136. else
  137. ( [ marker_regions[] | head_token ] ) as $vals
  138. | ( [ $vals[] | select(test("^[0-9a-fA-F]{40}$")) ] | .[0] // "-" ) as $good
  139. | ( [ marker_regions[] | outcome_token ] | map(select(. != "-")) | .[0] // "-" ) as $oc
  140. | ( [ marker_regions[] | important_token ] | map(select(. != "-")) | .[0] // "-" ) as $im
  141. | ( if $oc == "-" then "-"
  142. elif ($oc == "merge-ready" or $oc == "not-merge-ready") then $oc
  143. else "invalid" end ) as $outcome
  144. | ( if $im == "-" then "-"
  145. elif ($im | test("^[0-9]+$")) then $im
  146. else "invalid" end ) as $important
  147. | if $good != "-" then {state: "ok", head: $good, outcome: $outcome, important: $important}
  148. elif ([ $vals[] | select(. != "-") ] | length) > 0 then {state: "malformed", head: "-", outcome: $outcome, important: $important}
  149. else {state: "unbound", head: "-", outcome: $outcome, important: $important}
  150. end
  151. end;
  152. JQEOF
  153. )
  154. # The live filter: one record per comment or per review. A record carries
  155. #
  156. # <timestamp>\t<author>\t<association>\t<state>\t<head>\t<outcome>\t<important>
    • Note: Usual in code (tag names in paths and patterns): Contains a <important> block, a common wrapper for instructions hidden in a tool description
    • Line 164 on GitHub
  157. #
  158. # and never any part of a comment body. The outcome and the important-count
  159. # ride along so the merge gate can read what the verdict concluded; in the
  160. # default (head-only) mode they are simply unused.
  161. JQ_FILTER_JSON=$(cat <<'JQEOF'
  162. .[] | ((.submitted_at // .created_at // "") | iso_ts) as $ts
  163. | ((.user.login // "") | gsub("[^A-Za-z0-9._-]"; "")) as $who
  164. | ((.author_association // "NONE") | gsub("[^A-Za-z]"; "")) as $assoc
  165. | ((.body // "") | verdict_record) as $rec
  166. | "\($ts)\t\($who)\t\($assoc)\t\($rec.state)\t\($rec.head)\t\($rec.outcome)\t\($rec.important)"
  167. JQEOF
  168. )
  169. # The offline filter: the file's records are separated by a line of three
  170. # percent signs; the last record is the newest, so the records carry no
  171. # timestamp and no author.
  172. JQ_FILTER_RAW=$(cat <<'JQEOF'
  173. def split_records:
  174. reduce (split("\n")[]) as $line (
  175. {records: [[]]};
  176. if ($line | test("^[[:space:]]*%%%[[:space:]]*$")) then .records += [[]]
  177. else .records[-1] += [$line]
  178. end
  179. )
  180. | .records
  181. | map(join("\n"));
  182. split_records | .[] | (verdict_record) as $rec | "-\t-\t-\t\($rec.state)\t\($rec.head)\t\($rec.outcome)\t\($rec.important)"
  183. JQEOF
  184. )
  185. require_jq() {
  186. if ! command -v jq >/dev/null 2>&1; then
  187. echo "check-verdict-head: jq is required to read the verdicts" >&2
  188. exit 2
  189. fi
  190. }
  191. # Run jq over a filter, failing closed when jq cannot parse the input.
  192. # Reads stdin. $1 is the input mode ("raw" for raw text, "json" for JSON).
  193. run_jq() {
  194. _mode="$1"
  195. _filter="$2"
  196. _jqerr=$(mktemp) || {
  197. echo "check-verdict-head: could not create a temporary file for the parser error" >&2
  198. exit 2
  199. }
  200. trap '[ -n "${_jqerr:-}" ] && rm -f "$_jqerr"' EXIT HUP INT TERM
  201. if [ "$_mode" = "raw" ]; then
  202. # --slurp: the whole file is ONE input, not one input per line.
  203. jq --raw-input --slurp -r "$_filter" 2>"$_jqerr"
  204. else
  205. jq -r "$_filter" 2>"$_jqerr"
  206. fi
  207. _rc=$?
  208. if [ "$_rc" -ne 0 ]; then
  209. echo "check-verdict-head: could not parse the verdicts (jq exited $_rc):" >&2
  210. if [ -f "$_jqerr" ]; then sed 's/^/ /' "$_jqerr" >&2; fi
  211. rm -f "$_jqerr"
  212. trap - EXIT HUP INT TERM
  213. exit 2
  214. fi
  215. rm -f "$_jqerr"
  216. trap - EXIT HUP INT TERM
  217. }
  218. # Run one `gh api` call and print its raw payload. Fails closed: a failed
  219. # call is an infrastructure error, never "there is no verdict".
  220. gh_records() {
  221. _endpoint="$1"
  222. _label="$2"
  223. _err=$(mktemp) || {
  224. echo "check-verdict-head: could not create a temporary file for the gh error" >&2
  225. exit 2
  226. }
  227. trap '[ -n "${_err:-}" ] && rm -f "$_err"' EXIT HUP INT TERM
  228. _out=$(gh api "$_endpoint" --paginate 2>"$_err")
  229. _rc=$?
  230. if [ "$_rc" -ne 0 ]; then
  231. echo "check-verdict-head: could not read $_label (gh api exited $_rc):" >&2
  232. if [ -f "$_err" ]; then sed 's/^/ /' "$_err" >&2; fi
  233. rm -f "$_err"
  234. trap - EXIT HUP INT TERM
  235. exit 2
  236. fi
  237. rm -f "$_err"
  238. trap - EXIT HUP INT TERM
  239. printf '%s\n' "$_out"
  240. }
  241. # The records the checker parses. Every line is
  242. # <timestamp>\t<author>\t<association>\t<state>\t<head>
  243. # and no line carries any part of a comment body.
  244. fetch_records() {
  245. if [ -n "$VERDICTS_FILE" ]; then
  246. if [ ! -f "$VERDICTS_FILE" ]; then
  247. echo "check-verdict-head: could not read the verdicts file '$VERDICTS_FILE'" >&2
  248. exit 2
  249. fi
  250. require_jq
  251. run_jq "raw" "${JQ_LIB}${JQ_FILTER_RAW}" < "$VERDICTS_FILE"
  252. return 0
  253. fi
  254. if ! command -v gh >/dev/null 2>&1; then
  255. echo "check-verdict-head: gh is not available and --verdicts was not given" >&2
  256. exit 2
  257. fi
  258. if [ -z "$REPO" ] || [ -z "$PR" ]; then
  259. missing=""
  260. [ -z "$REPO" ] && missing="--repo"
  261. [ -z "$PR" ] && missing="${missing:+$missing }--pr"
  262. echo "check-verdict-head: $missing required without --verdicts" >&2
  263. exit 2
  264. fi
  265. require_jq
  266. # Issue comments and review bodies both carry the marker; inline review
  267. # comments have no body, so the review body is what matters. Each call is
  268. # checked on its own: a failure on either is an infrastructure error.
  269. _comments=$(gh_records "repos/$REPO/issues/$PR/comments" "the PR's issue comments") || exit 2
  270. _reviews=$(gh_records "repos/$REPO/pulls/$PR/reviews" "the PR's review bodies") || exit 2
  271. printf '%s\n%s\n' "$_comments" "$_reviews" | run_jq "json" "${JQ_LIB}${JQ_FILTER_JSON}"
  272. }
  273. # The newest verdict among the records.
  274. #
  275. # Prints "<state>\t<head>\t<author>\t<association>\t<outcome>\t<important>",
    • Note: Usual in code (tag names in paths and patterns): Contains a <important> block, a common wrapper for instructions hidden in a tool description
    • Line 289 on GitHub
  276. # where the state is one of
  277. # none — no record carries a verdict marker at all
  278. # unbound — a verdict exists but its marker names no head
  279. # malformed — a verdict names something that is not a full 40-character SHA
  280. # ok — the verdict names <head>
  281. # The newest record wins: the newest timestamp, and among equal timestamps
  282. # the later record. A record without a timestamp never beats a timestamped
  283. # one. A verdict only counts when it comes from an account that collaborates
  284. # with the repository; when no such account has posted one, the newest
  285. # verdict of any author is used, so that the check never goes green merely
  286. # because it declined to read the only verdict there is.
  287. select_verdict() {
  288. awk -F'\t' '
  289. function trusted(a) {
  290. return (a == "OWNER" || a == "MEMBER" || a == "COLLABORATOR")
  291. }
  292. BEGIN { FS = "\t"; n = 0 }
  293. NF == 0 { next }
  294. $4 == "none" { next }
  295. {
  296. n++
  297. ts[n] = $1; who[n] = $2; assoc[n] = $3; st[n] = $4; hd[n] = $5
  298. oc[n] = $6; im[n] = $7
  299. }
  300. END {
  301. has_trusted = 0
  302. for (i = 1; i <= n; i++) if (trusted(assoc[i])) has_trusted = 1
  303. best = 0
  304. for (i = 1; i <= n; i++) {
  305. if (has_trusted && !trusted(assoc[i])) continue
  306. if (best == 0) { best = i; continue }
  307. if (ts[i] != ts[best]) {
  308. if (ts[i] == "-") continue
  309. if (ts[best] != "-" && ts[i] < ts[best]) continue
  310. }
  311. best = i
  312. }
  313. if (best == 0) { print "none\t-\t-\t-\t-\t-"; exit 0 }
  314. print st[best] "\t" hd[best] "\t" who[best] "\t" assoc[best] "\t" oc[best] "\t" im[best]
  315. }
  316. '
  317. }
  318. RECORDS=$(fetch_records) || exit 2
  319. # printf '%s' (not '%s\n'): with zero comments and zero reviews RECORDS is
  320. # empty, and a trailing newline would hand the selector one blank record —
  321. # a phantom verdict with empty fields that failed every fresh PR.
  322. if ! SELECTED=$(printf '%s' "$RECORDS" | select_verdict); then
  323. echo "check-verdict-head: could not parse the PR's comments (the parser failed)" >&2
  324. exit 2
  325. fi
  326. STATE=$(printf '%s\n' "$SELECTED" | cut -f1)
  327. VERDICT_HEAD=$(printf '%s\n' "$SELECTED" | cut -f2)
  328. VERDICT_AUTHOR=$(printf '%s\n' "$SELECTED" | cut -f3)
  329. VERDICT_ASSOC=$(printf '%s\n' "$SELECTED" | cut -f4)
  330. VERDICT_OUTCOME=$(printf '%s\n' "$SELECTED" | cut -f5)
  331. VERDICT_IMPORTANT=$(printf '%s\n' "$SELECTED" | cut -f6)
  332. if [ "$VERDICT_AUTHOR" = "-" ]; then
  333. AUTHOR_NOTE="(author unknown)"
  334. elif [ "$VERDICT_ASSOC" = "OWNER" ] || [ "$VERDICT_ASSOC" = "MEMBER" ] || [ "$VERDICT_ASSOC" = "COLLABORATOR" ]; then
  335. AUTHOR_NOTE="(posted by $VERDICT_AUTHOR — $VERDICT_ASSOC)"
  336. else
  337. AUTHOR_NOTE="(posted by $VERDICT_AUTHOR — not a collaborator with the repository)"
  338. fi
  339. if [ "$STATE" = "none" ]; then
  340. if [ "$REQUIRE_OUTCOME" = "1" ]; then
  341. echo "check-verdict-head: FAIL — no factory-review verdict on this PR."
  342. echo " The merge gate asks whether this PR may merge. A PR with no verdict"
  343. echo " has not been certified merge-ready, so the gate cannot pass it:"
  344. echo " passing on silence would turn the check green for exactly the PRs"
  345. echo " nobody reviewed. Run the review on this head."
  346. exit 1
  347. fi
  348. echo "check-verdict-head: OK — no factory-review verdict on this PR; nothing to verify."
  349. exit 0
  350. fi
  351. if [ "$STATE" = "unbound" ]; then
  352. echo "check-verdict-head: FAIL — a factory-review verdict exists but names no head."
  353. echo " $AUTHOR_NOTE"
  354. echo " A verdict that names no head certifies nothing: it cannot be checked"
  355. echo " against a head, so it cannot support a merge-ready claim."
  356. echo " Re-run the review on the current head so the marker names it."
  357. exit 1
  358. fi
  359. if [ "$STATE" = "malformed" ]; then
  360. echo "check-verdict-head: FAIL — the verdict's head= value is not a full 40-character SHA."
  361. echo " $AUTHOR_NOTE"
  362. echo " A verdict that names no usable head certifies nothing: it cannot be checked"
  363. echo " against a head, so it cannot support a merge-ready claim."
  364. echo " Re-run the review on the current head so the marker names it."
  365. exit 1
  366. fi
  367. verdict_head=$(printf '%s' "$VERDICT_HEAD" | tr '[:upper:]' '[:lower:]')
  368. pr_head=$(printf '%s' "$PR_HEAD" | tr '[:upper:]' '[:lower:]')
  369. if [ "$verdict_head" != "$pr_head" ]; then
  370. echo "check-verdict-head: FAIL — the verdict names $VERDICT_HEAD but the head is $PR_HEAD."
  371. echo " $AUTHOR_NOTE"
  372. echo " A fix push invalidates the verdict: re-run the review passes on the current"
  373. echo " head and post the updated verdict naming $PR_HEAD before claiming merge-readiness."
  374. exit 1
  375. fi
  376. # The verdict is current. In the default mode that answers the whole question
  377. # and the check passes; the question asked there is staleness. The merge gate
  378. # asks one more: does this verdict say the PR may merge? A current verdict can
  379. # still be a not-merge-ready one, or one carrying open Important findings, and
  380. # neither may be shown as a green merge gate. Every field the gate reads is
  381. # checked fail-closed: a verdict that declares nothing cannot certify anything.
  382. if [ "$REQUIRE_OUTCOME" = "1" ]; then
  383. if [ -z "$VERDICT_OUTCOME" ] || [ "$VERDICT_OUTCOME" = "-" ]; then
  384. echo "check-verdict-head: FAIL — the verdict declares no outcome."
  385. echo " $AUTHOR_NOTE"
  386. echo " The marker names the head but omits outcome=, so it says nothing about"
  387. echo " merge-readiness. The gate fails closed: a verdict that declares nothing"
  388. echo " cannot certify that the PR may merge. Re-run the review so the marker"
  389. echo " carries outcome=merge-ready or outcome=not-merge-ready."
  390. exit 1
  391. fi
  392. if [ "$VERDICT_OUTCOME" = "invalid" ]; then
  393. echo "check-verdict-head: FAIL — the verdict's outcome= is not a legal value."
  394. echo " $AUTHOR_NOTE"
  395. echo " outcome= must be merge-ready or not-merge-ready; a value the gate does"
  396. echo " not recognise cannot be trusted to mean either. Re-run the review so the"
  397. echo " marker carries a legal outcome."
  398. exit 1
  399. fi
  400. if [ -z "$VERDICT_IMPORTANT" ] || [ "$VERDICT_IMPORTANT" = "-" ] || [ "$VERDICT_IMPORTANT" = "invalid" ]; then
  401. echo "check-verdict-head: FAIL — the verdict's important= is missing or not a count."
  402. echo " $AUTHOR_NOTE"
  403. echo " The gate reads important= to learn whether Important findings are open."
  404. echo " A marker that omits it, or makes it unreadable, cannot prove that none"
  405. echo " are, so the gate fails closed. Re-run the review so the marker carries"
  406. echo " important=<count>."
  407. exit 1
  408. fi
  409. if [ "$VERDICT_OUTCOME" = "not-merge-ready" ]; then
  410. echo "check-verdict-head: FAIL — the verdict says outcome=not-merge-ready."
  411. echo " $AUTHOR_NOTE"
  412. echo " The verdict is current, so it is not stale; it concludes the PR may not"
  413. echo " merge. The gate reports that conclusion instead. Address the blocking"
  414. echo " findings and re-run the review to clear it."
  415. exit 1
  416. fi
  417. if [ "$VERDICT_IMPORTANT" -gt 0 ] 2>/dev/null; then
  418. echo "check-verdict-head: FAIL — the verdict reports $VERDICT_IMPORTANT open Important finding(s)."
  419. echo " $AUTHOR_NOTE"
  420. echo " An Important finding blocks a merge, so a verdict counting one cannot"
  421. echo " certify merge-readiness even when its outcome= says merge-ready: the"
  422. echo " count is the fact, the outcome string only summarises it. Resolve the"
  423. echo " findings and re-run the review."
  424. exit 1
  425. fi
  426. echo "check-verdict-head: OK — the verdict names the current head and declares merge-ready."
  427. echo " $AUTHOR_NOTE"
  428. exit 0
  429. fi
  430. echo "check-verdict-head: OK — the verdict names the current head ($PR_HEAD)."
  431. echo " $AUTHOR_NOTE"
  432. exit 0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.