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.
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
Markdown
[](/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
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.
- # adlc-team-skills
- Agent skills that give coding agents your team's context at session start,
- so they stop working like strangers.
- ## Table of contents
- - [How it works](#how-it-works)
- - [The developer journey](#the-developer-journey)
- - [The problems these skills solve](#the-problems-these-skills-solve)
- - [Install](#install)
- - [The software factory](#the-software-factory)
- - [Universal orchestration](#universal-orchestration)
- - [What's inside](#whats-inside)
- - [Philosophy](#philosophy)
- - [When something goes wrong](#when-something-goes-wrong)
- - [Security](#security)
- - [Contributing](#contributing)
- - [Reference details](#reference-details)
- - [Release process](#release-process)
- - [License](#license)
- ## How it works
- It starts the moment you open a session. `team-boot` fires via the
- `session_start` event hook and injects a lean index of your team's rules —
- roughly a hundred tokens of names and one-line descriptors. Not the rules
- themselves. When the active task matches a rule, the agent pulls that
- rule's full text on demand. A task touching SQL loads the SQL rule;
- nothing else does.
- The index lives in a git repo — your [team-ai-directives](https://github.com/tikalk/agentic-sdlc-team-ai-directives) —
- versioned, reviewed by PR, shared by the whole team. No more personal
- CLAUDE.md files that live on one machine, drift out of date, and don't
- transfer between teammates or tools.
- When you ask the agent to build something, it doesn't jump to code.
- `factory-mission` forces a contract first — goal, constraints, non-goals,
- success criteria (the mission-brief format) — then walks `specify → plan → implement ↔ converge`, with
- gates, a circuit breaker, resume, and an audit trail. When a session
- surfaces a hard-won fix, `team-levelup` extracts it as a Context
- Directive Record (CDR), scores it by confidence, and publishes accepted
- CDRs back to the team repo. Usage data and confidence scores live in
- the `adlc` orphan branch — the next session starts smarter and CDRs
- rank by real usage.
- Verification, history, and tech selection have loops of their own.
- When a rule or skill's behavior needs proof, the `evals-*` skills build
- executable graders — binary checks where code can verify, LLM judges only
- for what static checks can't — validated with holdout splits and TPR/TNR.
- When you touch old code and wonder why it looks like this, `change-init`
- mines git history for issue-linked commits and recovers the past-change
- rationale as ChDRs. And when a tech choice comes up, `tech-radar-boot`
- injects the Tikal Tech Radar's opinion — adoption ring, quadrant — before
- the selection is captured as an ADR.
- That session loop sits inside a bigger one: **the software factory**.
- `factory-queue` triages incoming work, `factory-mission` executes it as
- spec-gated missions in isolated worktrees, `factory-review` grades the
- resulting PRs against policy-as-code, and `factory-learn` feeds what the
- runs taught back into team-ai-directives — with human gates (⭐) at every
- decision point. One platform: intake → mission → review → learning.
- And because the skills trigger automatically from the index, you don't do
- anything special once they're installed. Your coding agent just has your
- team's context.
- ## The developer journey
- What it actually looks like to get from zero to a factory, in order.
- ### 0. Prerequisites
- - A coding agent (opencode, Claude Code, Cursor, Codex, Gemini CLI, …)
- - [`adlc-cli`](https://github.com/tikalk/adlc-cli) — `npx` works, no install needed
- - `jq` — required by the setup scripts (they build all JSON output with `jq -n`; missing `jq` fails loudly instead of silently resolving defaults)
- ### 1. Install — one command per project
- ```bash
- 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.
- ### 2. First session — context arrives on its own
- Open a session in the project. `team-boot` fires on `session_start` and
- injects the index (constitution titles, CDR index ranked by confidence,
- Class Boots catalog, skills registry, MCP servers). On an unconfigured
- project it points you to `/team-setup`; `/team-constitution` fills in your
- team's principles once. There is nothing to remember after this point —
- skills trigger when the task matches.
- ### 3. Daily work — index, class boots, decision capture
- - The agent checks the directives index before any task; full rule bodies
- load on demand.
- - **Class boots** fire when a decision class shows up: `architect-boot`
- (ADR index), `product-boot` (PDR index), `change-boot` (ChDR index),
- `tech-radar-boot` (radar opinion before a tech selection).
- - **Decision capture is suggested, never automatic**: decisions detected
- mid-session surface a `_Suggested capture_` line naming the class capture
- skill (`/architect-specify`, `/product-specify`, `/change-specify`, …);
- running that skill writes the lightweight draft to
- `.adlc/drafts/{adr,pdr,chdr,cdr,evals}/`.
- The `file_edited` hook notices each draft landing and nudges the matching
- clarify skill (`adr→/architect-clarify`, `pdr→/product-clarify`, …).
- - When harness compaction summarizes history away, `session_compact`
- re-injects the index.
- ### 4. Session end — learnings become records
- `team-levelup` fires on `session_end`: it extracts hard-won fixes as CDRs +
- paired eval CDRs, scores confidence, batch-reviews them, and publishes
- accepted CDRs as a draft PR to team-ai-directives. Drafts and usage reports
- live in the `adlc` orphan branch (`drafts/cdr/` + `reports/`).
- ### 5. Individual lifecycles — on demand
- Each record class has its own skill loop you invoke explicitly:
- ```
- Product: product-specify|init → product-clarify (accept + promote to memory) → product-implement → product-analyze
- Architecture: architect-specify|init → architect-clarify (accept + promote to memory) → architect-implement → architect-analyze
- Team: team-init → team-levelup (extract + review + publish) → team-repair (--update-confidence)
- Change: change-init → change-clarify → change-publish (change-boot injects the chdr.md index)
- Evals: evals-init → evals-specify → evals-clarify → evals-implement → evals-validate
- ```
- Accepted PDRs/ADRs are promoted to memory on approval — no gap between
- "Accepted in drafts" and "moved to memory".
- ### 6. The software factory — the outer loop
- Running intake → execution → review → learning unattended? The factory
- takes over from queue to PR — see [The software factory](#the-software-factory).
- ### Ongoing maintenance
- ```bash
- adlc-cli team update # git pull team-ai-directives + skills update + confidence update
- adlc-cli team repair # full repair via agent run (reindex, conflicts, freshness)
- adlc-cli team repair --update-confidence # deterministic confidence aggregation (no agent)
- ```
- `team-repair --build-to-delete` re-runs evals without a rule and proposes
- deletion when the model passes anyway; `--validate-drafts` validates draft
- files in `.adlc/drafts/` without modifying them.
- ## The problems these skills solve
- | # | Problem | Fixed by |
- |--|--|--|
- | 1 | The agent doesn't know how your team works | **`team-*`** — session-start index + on-demand rules |
- | 2 | The agent guesses instead of asking | **`factory-mission`** — spec contract before code |
- | 3 | The maker grades its own work | **`evals-*`** — binary graders, holdout splits, nothing auto-merges |
- | 4 | Session learnings evaporate | **`team-levelup`** — extract fixes as CDRs, publish to the team repo |
- | 5 | Product and architecture decisions are invisible | **`product-*`** / **`architect-*`** — PDR→PRD, ADR→AD traceability |
- | 6 | "Why was this changed?" is archaeology — rationale lives in nobody's head | **`change-*`** — ChDRs mined from git history's issue-linked commits |
- | 7 | The agent picks tech by vibes, not team opinion | **`tech-radar-boot`** — radar context (adoption ring, quadrant) before the ADR |
- | 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) |
- | 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 |
- ## Install
- ```bash
- # One command: install skills + configure team-ai-directives (runs /team-setup interactively)
- npx adlc-cli team setup tikalk/adlc-team-skills -a opencode
- # Or just install skills (no team-setup)
- npx adlc-cli skills add tikalk/adlc-team-skills -a opencode
- # Or plain skills (no commands/events)
- npx skills add tikalk/adlc-team-skills -a claude -g
- ```
- Selective installs resolve closures automatically: `--skill architect-implement`
- also pulls its canonical home (`architect-clarify`) via `.skills-deps.json`,
- so shared helpers are never orphaned. Factory skills resolve the same way
- (`--skill factory-intent` pulls `factory-runbook`). Borrower skills fail fast with the exact
- recovery command if their canonical home is missing.
- Works with any agent supporting the [Agent Skills standard](https://agentskills.io) —
- Claude Code, Codex, OpenCode, Cursor, Copilot, and others.
- [`adlc-cli`](https://github.com/tikalk/adlc-cli) wraps `npx skills add`
- and additionally generates `/name` slash commands and wires the four event
- hooks declared in this repo's `.events.json` — `session_start` and
- `session_compact` (team-boot), `session_end` (team-levelup), and `file_edited`
- (team-boot, draft-written nudges) — for the 9 coding agents with native
- hook support. `team setup` also runs the `/team-setup` skill via
- `agent run` to clone, link, or scaffold your team-ai-directives repo.
- Skills repos without `.events.json` get commands only.
- **First run:** `team-boot` fires at session start. On an unconfigured project
- it points you to `/team-setup`, which clones, links, or scaffolds your
- team-ai-directives repo. `/team-constitution` fills in your principles.
- **Using `agentic-sdlc-spec-kit` alongside this repo?** See
- [Coexistence with Spec Kit](docs/spec-kit-integration.md) for the
- conflict-free install flow.
- ## The software factory
- The factory skills are the full outer loop of an agentic SDLC: they take a
- brownfield repo from bootstrap all the way to merged, reviewed PRs — and
- turn what each run learned into team memory. Every automated stage is
- advisory; humans hold the gates (⭐).
- ```
- brownfield repo
- │
- ▼
- ┌─────────────────┐ unified bootstrap: product → architect → change
- │ factory-init │ tracks + PDR↔ADR↔ChDR↔code coverage matrix
- └────────┬────────┘ (--refresh = recurring alignment sweep)
- │ PRD.md · AD.md · .adlc/memory/
- ▼
- ┌──────────────────────────┐ PDRs → PRD.md · ADRs → AD.md
- │ factory-intent │ (two scope-pinned gates)
- │ (product + arch lanes) │
- └────────┬─────────────────┘
- │ Mission Brief (goal + constraints + success criteria)
- ▼
- Intent Gate ⭐ (human approves the brief; AI triage scores are advisory)
- │
- ▼
- ┌─────────────────┐ spec-gated into the tracker (the Q, single source of truth)
- │ factory-queue │
- └────────┬────────┘
- │ --issue ref
- ▼
- ┌─────────────────┐ inner loop: specify → plan → implement ↔ converge
- │ factory-mission │ (comment bus · worktrees · TDD test/code split · circuit breaker)
- └────────┬────────┘
- │ agent-authored PR
- ▼
- ┌─────────────────┐
- │ factory-review │──▶ Merge Gate ⭐ (human code-owner approval)
- └────────┬────────┘
- ▼
- ┌─────────────────┐ CDRs/ChDRs → team-ai-directives PR
- │ factory-learn │ workflow memories → memory.jsonl
- └────────┬────────┘
- │
- └─▶ back to factory-mission (memories)
- + team-boot (CDR index — closes the context loop)
- ```
- What each station adds:
- - **`factory-setup`** — one command wires a repo to its issue tracker:
- provider pick (detect-from-remote, explicit, or already-configured),
- writes `.adlc/issues-provider.yml` (never credentials, never overwrite).
- - **`factory-init`** — one command onboards an existing repo onto ADLC and
- emits the PDR↔ADR↔ChDR↔code coverage matrix (`--refresh` for the
- recurring alignment sweep).
- - **`factory-queue`** — mission brief intake: AI-assisted advisory triage
- scoring, intent gate, gating label stamping, milestones/epics generation.
- - **`factory-mission`** — the execution engine: spec-gated inner loop
- (specify → plan → implement ↔ converge) with tracker-agnostic integration,
- an inter-agent comment bus, worktree isolation, lease-based liveness,
- stall detection, a dependency hard gate (Operation 12 — intake refuses
- while declared dependencies stay open; only closed/cancelled counts
- complete, dependents machine-notified on clear),
- stall detection, and a mandated TDD test/code split (RED gate + GREEN gate,
- enforced at the skill level, not just the prompt level).
- - **`factory-review`** — severity-ranked PR compliance against REVIEW.md
- policy-as-code; babysits agent PRs to merge, never auto-merges past the
- human gate. `--self-heal` runs a three-sub-agent converge loop
- (Review→Fix→Converge) with maker-checker separation and circuit breaker.
- - **`factory-learn`** — retrospectives into team-ai-directives:
- build-to-delete pruning, promote-to-check for mechanical rules.
- - **`factory-intent`** — merged two-lane intent orchestrator
- maintaining PRD.md and AD.md with clarify⭐ gates.
- - **`factory-orchestrator`** — front-door router: accepts work at any
- lifecycle stage (new request, CI failure on a delivered PR, review
- findings, merge notification), detects the stage from tracker/run
- evidence, and hands it to the owning skill, human gate, or follow-up
- context. Router and communicator only — never implements, reviews,
- or merges itself.
- - **`factory-tickets`** — read-only worklist across trackers, classified by
- next actionable move.
- - **`factory-clean`** — resource inventory and reclamation, approval-gated.
- <details>
- <summary><strong>Detailed wiring</strong></summary>
- ```mermaid
- flowchart LR
- FQ["factory-queue<br/>Ingestion & Triage"] ~~~ IG{"Intent Gate"}
- FI2["factory-intent<br/>Merged Two-Lane DAG"] ~~~ CG1{"product Gate"} & CG1 ~~~ CG2{"architecture Gate"}
- FM["factory-mission<br/>Execution Engine"] ~~~ CB{"Circuit Breaker"}
- FR["factory-review<br/>PR Compliance"] ~~~ MG{"Merge Gate"}
- FL["factory-learn<br/>Learning Loop"] ~~~ CG3{"clarify⭐ Gate"}
- FC["factory-clean<br/>Resource Cleanup"] ~~~ UG{"Approval Gate"}
- FT["factory-tickets<br/>Read-Only Worklist"]
- FO["factory-orchestrator<br/>Front-Door Router"]
- FI["factory-init<br/>Brownfield Bootstrap"]
- TR[("Issue Tracker<br/>GitHub / GitLab / Linear / Jira")]
- TD[["team-ai-directives<br/>repo"]]
- FQ -->|"spec-gated labels"| TR
- TR -->|"--issue ref"| FM
- FI2 -->|"PRD.md + AD.md"| FQ
- FM -->|"agent-authored PRs"| TR
- TR -->|"PR diff + checks"| FR
- FR -->|"twice-mistake rule"| FL
- FL -->|"memory.jsonl"| FM
- FL -->|"draft PR"| TD
- FC -.->|"reads state files"| FM
- FO -->|"new work requests"| FQ
- FO -.->|"CI failure / merge notification follow-ups"| FM
- FT -.->|"read-only"| TR
- FI -.->|"via intent lanes"| FI2
- ```
- </details>
- ## Universal orchestration
- `factory-mission` doesn't lock you into a proprietary ecosystem. Step prompts
- name skills by exact name; the dispatched subagent resolves them through its
- own harness Skill tool (the runtime injects the installed-skills inventory —
- no filesystem scan). For commands-based frameworks the model cannot see, the
- commands-dir fallback in `references/agent-integrations.md` covers discovery.
- Routing stays LLM-decided — no hard-coded phase-to-skill mapping. Works
- alongside:
- | Source | Examples |
- |---|---|
- | [mattpocock/skills](https://github.com/mattpocock/skills) | `/tdd`, `/grill-me`, `/code-review` |
- | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | Exit-criteria checklists |
- | [superpowers](https://github.com/obra/superpowers) | Workflow skills |
- | spec-kit / [agentic-sdlc-spec-kit](https://github.com/tikalk/agentic-sdlc-spec-kit) / OpenSpec | SDD command frameworks |
- | This repo | `product-specify`, `architect-specify`, `evals-validate`, `team-levelup` |
- | Your own | Anything following the `SKILL.md` standard |
- ## What's inside
- 48 skills across 8 categories.
- ### Team directives — every session, every user
- - **`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.
- - **`team-setup`** — clone, link, or scaffold a team-ai-directives repo.
- - **`team-constitution`** — define or amend team principles interactively.
- - **`team-discover`** — manual re-scan; structured match table (`/team-discover`).
- - **`team-repair`** — re-index, conflict scan, freshness, `--build-to-delete`, `--validate-drafts`, deterministic-enforcement coverage check.
- - **`team-skills`** — browse/install team skills from the directives repo.
- - **`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.
- ### The software factory — the outer loop
- - **`factory-init`** — unified brownfield bootstrap + PDR↔ADR↔ChDR↔code coverage matrix (`--refresh`).
- - **`factory-queue`** — queue intake, AI advisory triage scoring, intent gate, milestone generation.
- - **`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.
- - **`factory-intent`** — merged intent orchestrator (product + architecture lanes, two gates).
- - **`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.
- - **`factory-release`** — post-merge release orchestration: exact-head gated merge → staged rollout with threshold verdicts → SemVer-tagged, noted release with monitor handoff.
- - **`factory-learn`** — continuous improvement loops targeting team-ai-directives: build-to-delete pruning, promote-to-check (EVAL-010) for mechanical rules.
- - **`factory-tickets`** — read-only personal worklist across trackers.
- - **`factory-clean`** — resource inventory and reclamation (approval-gated).
- ### Mission-driven development
- - **`factory-mission`** — spec-contract pipeline with converge loop, circuit breaker, resume (`factory-mission "feature"`, `--resume`).
- ### Learning loop (CDR lifecycle)
- - **`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).
- - **`team-init`** — brownfield CDR discovery from an existing codebase. Writes to the `adlc` branch; handoff to `team-levelup` for review/publish.
- - **`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.
- ### Evals — verification over vibes
- - **`evals-init`** — scaffold `evals/{system}/` with security baseline.
- - **`evals-specify`** — extract criteria from specs / failure traces.
- - **`evals-clarify`** — cluster, isolate holdout, publish goldset.
- - **`evals-implement`** — generate graders + unit tests.
- - **`evals-validate`** — run evaluation pyramid, TPR/TNR + SLA headroom.
- - **`evals-analyze`** — route failures to deterministic checks, context rules, or evaluator backlog.
- ### Product & architecture lifecycles
- - **`product-boot`** / **`product-init`** / **`product-specify`** — PDR index, brownfield discovery, greenfield creation.
- - **`product-clarify`** — refine and approve. **`product-implement`** — generate `PRD.md`.
- - **`product-analyze`** — PDR↔PRD consistency. **`product-roadmap`** — milestone progress across decision, execution, evidence, and gate layers.
- - **`architect-boot`** / **`architect-init`** / **`architect-specify`** — ADR index, reverse-engineering, creation (routes tech selection through `tech-radar-boot`).
- - **`architect-clarify`** — refine. **`architect-implement`** — generate `AD.md`. **`architect-analyze`** — ADR↔AD consistency.
- ### Change history (ChDRs)
- - **`change-boot`** — class boot: injects the `chdr.md` index when past-change rationale matters + ChDR mining capture.
- - **`change-init`** — mine git history for Change Decision Records via issue-linked commits.
- - **`change-clarify`** — review mined ChDRs (provenance gate on Decision claims).
- - **`change-publish`** — promote accepted ChDRs to `.adlc/memory/chdr/`.
- ### Tech selection
- - **`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.
- ### Workspace
- - **`workspace`** — multi-repo workspace: `--init` creates `.adlc/` structure, discover/link/audit child repos (`--link`, `--status`, `--ignore-only`).
- ### Skill authoring — contributors
- - **`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.
- ## Philosophy
- - **Index, not injection.** Long contexts measurably degrade LLM performance —
- even with perfect retrieval
- ([arXiv:2510.05381](https://arxiv.org/abs/2510.05381), 13.9%–85% degradation
- by length alone). Agents get an index by default and pull full rules only
- when relevant. If your instinct is "more rules in context don't work" —
- we agree. That's the design.
- - **Rules should shrink over time, not grow.** Base models improve;
- yesterday's scaffolding becomes today's context noise. `--build-to-delete`
- re-runs evals without a rule and proposes deletion when the model passes
- anyway. Mechanical rules that survive are flagged for promotion to
- deterministic checks.
- - **Evidence over vibes.** Anything code can check gets a binary grader —
- plain assertions, Tier 1. LLM judges are Tier 2, reserved for what
- static checks can't verify. Nothing auto-merges; pipelines end at a PR a
- human reviews.
- - **Decisions as code.** Every decision class — product (PDR), architecture
- (ADR), change (ChDR), context (CDR) — lives in version-controlled repos
- with a draft → clarify → accept → promote → publish → analyze lifecycle,
- and traces from record to document to code. Accepted records are promoted
- to memory atomically with approval — never left in drafts.
- ## When something goes wrong
- - **Team context didn't appear at session start** — check `.adlc/init-options.json`
- points at an existing team-ai-directives checkout; on an unconfigured
- project run `/team-setup`. The `session_start` hook (`.events.json` →
- dispatcher → `team-boot`'s `scripts/boot.sh`) needs `jq` available. Full
- chain contract: [docs/event-hook-contract.md](docs/event-hook-contract.md);
- run `scripts/acceptance-test.sh` to verify the whole loop from scratch.
- For evidence-first diagnosis of injection failures, run `/team-diagnose`
- (traces init-options → jq → boot.sh → artifact sync → injection; EVAL-013).
- - **Team context vanished mid-session after compaction** — re-injection
- after compaction is a declared contract (`session_compact` in
- `.events.json`); the injection side is implemented by
- [adlc-cli](https://github.com/tikalk/adlc-cli) — if your
- agent's adapter doesn't map the event yet, file it there.
- - **Skill descriptions or commands look stale** — the install layer is
- CLI-generated (`.agents/skills/`, `.opencode/commands/`, `skills-lock.json`).
- Regenerate: `npx adlc-cli skills add tikalk/adlc-team-skills -a <agent> -y`.
- `tests/unit/test_generated_artifacts_sync.py` catches drift locally.
- - **Index is inconsistent or rules conflict** — run `/team-repair`
- (re-index, conflict scan, freshness check, orphan detection).
- - **Something else** — [open an issue](https://github.com/tikalk/adlc-team-skills/issues).
- To verify a suspected skill-behavior bug yourself, follow the
- [manual testing protocol](CONTRIBUTING.md#manual-testing) (scratch project,
- real agent, report table). The repo's testing model — two directories,
- three tiers — is mapped in [docs/testing.md](docs/testing.md).
- ## Security
- On 2026-07-27 a supply-chain worm briefly injected a malicious payload into
- this repo's `.claude/` and `.vscode/` directories via a stolen maintainer
- token (exposure window ~11:06–18:30 UTC). The payload only executed if you
- cloned the repo and opened it in VS Code or started a Claude Code session
- inside it; the `npx skills` install path never shipped or ran those files.
- History was rewritten to strip the payload from all commits and tags, tokens
- and secrets were rotated, and branch protection now blocks the vector used.
- Details and remediation steps: [issue #1](https://github.com/tikalk/adlc-team-skills/issues/1).
- Lesson for any repo: treat `.vscode/tasks.json` and `.claude/settings.json`
- in a clone as executable code, and disable editor auto-run tasks.
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md). New skills must be agreed in an
- issue first, ship with eval coverage, and follow the `writing-skills`
- methodology — no skill without a failing baseline first.
- ## Reference details
- <details>
- <summary><strong>Repository layout</strong></summary>
- Skills are organized into category subdirectories under `skills/`, ordered
- by the pull each family has on a typical session (team first):
- ```
- skills/
- ├── team/ # team-* (9) + workspace + templates/ (team-helpers canonical in team-setup)
- ├── evals/ # evals-* (6) + evals-templates/
- ├── product/ # product-* (7) + product-templates/ + templates/ (pdr-lib canonical in product-clarify)
- ├── architect/ # architect-* (6) + templates/ (setup-architect + generators canonical in architect-clarify)
- ├── change/ # change-* (4) + templates/
- ├── tech-radar/ # tech-radar-boot (1) — OKF knowledge repo reader (cached clone + public-JSON fallback)
- ├── authoring/ # writing-skills (1; templates live inside the skill)
- └── factory/ # factory-* (10) — platform orchestration
- ```
- This places every single skill exactly 2 levels deep, fully resolving the
- default depth limit of the `skills` CLI and ensuring all skills install
- out of the box. (Enforced by `tests/unit/test_playbook_integrity.py`.)
- Each skill family shares a `{family}/templates/` directory instead of
- duplicating templates per-skill (evals and product retain their
- `-templates/` names for compatibility).
- </details>
- <details>
- <summary><strong>Output File Layout</strong></summary>
- All skills write to `.adlc/` (project root) and the team AI directives repo.
- **Team Directives** (inside the team AI directives repository):
- - `AGENTS.md` — agent instructions (loading order, rules, skills)
- - `CDR.md` — index of approved context contributions
- - `.skills.json` — skills manifest (schema v2.0.0)
- - `.mcp.json.example` — MCP servers config example
- - `context_modules/constitution.md` — team constitution (OKF frontmatter)
- - `context_modules/{rules,personas,examples}/**/*.md` — context modules
- - `context_modules/{type}/index.md` — progressive disclosure per concept type
- - `context_modules/{type}/log.md` — chronological change log per concept type
- - `skills/{name}/SKILL.md` + `.skills-entry.json` — published team skills
- - `evals/{directive-id}/goldset.md` + `goldset.json` — directive compliance goldensets
- **team-levelup** (inside `.adlc/` of the target project):
- - `adlc branch drafts/cdr/CDR-{NNN}.md` — proposed/discovered CDRs (including eval CDRs)
- - `adlc branch drafts/cdr/cdr.md` — auto-generated CDR index
- - `.adlc/init-options.json` — team AI directives path config
- **Product** (inside `.adlc/` and repo root):
- - `.adlc/drafts/pdr/PDR-{NNN}.md` — proposed/discovered PDRs
- - `.adlc/drafts/pdr/pdr.md` — auto-generated PDR index
- - `.adlc/memory/pdr/PDR-{NNN}.md` — accepted/completed PDRs
- - `.adlc/memory/pdr/pdr.md` — accepted PDR index
- - `.adlc/product/sections/{feature-area}/{section}.md` — PRD section build artifacts
- - `.adlc/product/state.json` — DAG execution state
- - `PRD.md` — Product Requirements Document (repo root)
- **Architecture** (inside `.adlc/` and repo root):
- - `.adlc/drafts/adr/ADR-{NNN}.md` — proposed/discovered ADRs
- - `.adlc/drafts/adr/adr.md` — auto-generated ADR index
- - `.adlc/memory/adr/ADR-{NNN}.md` — accepted ADRs
- - `.adlc/memory/adr/adr.md` — accepted ADR index
- - `AD.md` — Architecture Description (repo root)
- - `.adlc/architect/` — per-view DAG artifacts
- **Missions** (inside `.adlc/` of the target project):
- - `.adlc/workflows/runs/<run_id>/` — the durable run archive: `brief.md`
- (the worker brief), `mission.yml` (execution/supervision/budgets policy),
- `state.json` (program counter, written via the `adlc-cli workflow state`
- helpers), `lease.json` (strict run lease, shared run state), `scratchpads/`,
- `findings/`, `decisions/`, `artifacts/`, `iterations.md`
- - `.adlc/workflows/<run_id>/workflow.yml` — generated-by-slug workflow
- definition (the workflow namespace)
- - `.adlc/workflows/memory.jsonl` — cross-run workflow memory
- (workspace-global; read/write by `factory-learn` retrospectives)
- - `.adlc/worktrees/<run_id>/` — isolated mission worktrees
- - `refs/factory-runs/<run_id>` — git-refs Tier-3 transport of the run
- archive (git-refs run state)
- **Governance** (inside target project and repo root):
- - `.adlc/drafts/evals/EVAL-{NNN}.md` — proposed/discovered eval criteria drafts
- - `.adlc/drafts/evals/evals.md` — draft evals index
- - `.adlc/memory/evals/EVAL-{NNN}.md` — accepted/completed eval criteria
- - `.adlc/memory/evals/evals.md` — accepted evals index
- - `.adlc/memory/evals/holdout.json` — isolated/reserved holdout test dataset
- - `.adlc/coverage/coverage.md` — factory-init PDR↔ADR↔ChDR↔code coverage matrix
- - `evals/{system}/goldset.md` — published goldset (human-readable)
- - `evals/{system}/goldset.json` — published goldset (machine-readable)
- - `evals/{system}/config.yml` — evaluation framework configuration
- - `evals/{system}/config.{js,py}` — framework test config
- - `evals/{system}/graders/check_*.py` — generated binary Python graders / metrics
- - `evals/{system}/tests/test_check_*.py` — generated unit tests verifying grader correctness
- - `evals/results/validation_report.md` — statistical validation results report
- **Workspace** (inside parent repo root):
- - `.gitmodules` — Git submodule registrations for child repos (created by `--link`)
- - `.adlc/` — shared team context (PDRs, ADRs, CDRs); parent is the single source of truth
- - Child repos discovered at depth 1; each child's `.adlc/` presence is reported (informational)
- </details>
- <details>
- <summary><strong>OKF Compliance</strong></summary>
- Generated context modules include [Open Knowledge Format (OKF) v0.2](https://blog.agentics.org/open-knowledge-format/) compliant frontmatter alongside custom fields.
- | OKF field | Status | Source |
- |-----------|--------|--------|
- | `type` | ✅ | CDR context type (Constitution/Persona/Rule/Example/Skill) |
- | `title` | ✅ | CDR title |
- | `description` | ✅ | CDR descriptor |
- | `tags` | ✅ | Context type tag |
- | `generated` | ✅ | ISO 8601 datetime + author |
- | `verified` | ✅ | ISO 8601 datetime + verifier |
- | `status` | ✅ | stable / draft / deprecated |
- | `stale_after` | ✅ | e.g., `180d` — freshness window for team-repair |
- Custom fields co-exist with OKF frontmatter: `id`, `cdr_ref`, `created`, `modified`, `verified`, `age_days`, `evidence`.
- Directory structure: `context_modules/{type}/index.md` (progressive disclosure), `context_modules/{type}/log.md` (change history), cross-links between related concepts.
- </details>
- <details>
- <summary><strong>Workflows</strong></summary>
- **Team Directives setup:**
- ```
- team-setup → team-constitution → team-boot (auto at session start)
- ```
- **Product lifecycle:**
- ```
- Brownfield: product-init → product-clarify → product-implement → product-analyze
- Greenfield: product-specify → product-clarify → product-implement → product-analyze
- Roadmap: product-roadmap (anytime)
- ```
- **Architecture lifecycle:**
- ```
- Brownfield: architect-init → architect-clarify → architect-implement → architect-analyze
- Greenfield: architect-specify → architect-clarify → architect-implement → architect-analyze
- ```
- **CDR lifecycle:**
- ```
- Brownfield: team-init → team-levelup (extract + review + publish) → team-repair
- Session: team-levelup (extract + review + publish) → team-repair
- History: change-init → change-clarify → change-publish (change-boot injects chdr.md)
- Build to Delete: team-repair --build-to-delete → team-levelup (review deletion CDRs)
- Confidence: team-repair --update-confidence → team-boot (ranks CDRs by confidence)
- ```
- **Mission:**
- ```
- factory-mission "feature" → review brief → execute steps → converge → run archive (.adlc/workflows/runs/<run_id>/)
- ```
- **Multi-repo workspace:**
- ```
- workspace --init → create .adlc/ structure + configure .gitignore
- product-specify / architect-specify → create shared PDRs/ADRs in parent .adlc/
- workspace --link → register child repos as submodules
- workspace --status → audit branch, dirty, unpushed, SHA drift
- ```
- **Application Evaluation lifecycle:**
- ```
- Greenfield (Spec-Driven): evals-init → evals-specify (from spec) → evals-clarify → evals-implement → evals-validate
- Brownfield (Error-Driven): evals-init → evals-specify (from failures) → evals-clarify → evals-implement → evals-validate → evals-analyze
- ```
- </details>
- <details>
- <summary><strong>12-Factor Alignment</strong></summary>
- This repo implements the [Twelve-Factor Agentic SDLC](https://github.com/tikalk/agentic-sdlc-12-factors).
- | Factor | Skills | How |
- |--------|--------|-----|
- | **III — Mission Definition** | Product skills | PRD/PDR lifecycle ensures product decisions are documented, reviewed, and traceable before execution |
- | **IV — Structured Planning** | Architecture skills | ADRs and AD.md provide structured planning artifacts using Rozanski & Woods viewpoints |
- | **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 |
- | **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 |
- | **IX — Traceability** | Product + Architecture | Every decision traces from PDR → PRD → feature and from ADR → AD → code |
- | **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 |
- | **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 |
- | **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 |
- ### Deck ↔ code glossary (the deck-code glossary)
- Canonical names live in code; deck terms map to them (code is ground truth, except Pair 1 where the concept itself is harness-agnostic):
- | Deck term | Code term | Resolution |
- |-----------|-----------|------------|
- | `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 |
- | `evidence-chain.md` | Audit trail (comment bus + `runs/<id>/`) | Code wins — deck adopts "audit trail" |
- | Triage / Clarify Agents | `factory-queue` triage scoring + inline clarify gates | Code wins, no skill split (revisit if scoring grows independent owners/evals) |
- | "Lit Factory" / "Ratchet Effect" | Factory orchestrators / `team-levelup` + Twice-Mistake Threshold | Keep both — evocative deck names mapped to code refs |
- | `mission-brief` skill | `factory-mission` | Settled by history (renamed) |
- | `team-learn` | `team-levelup` | Settled by history (v0.30.0 hard rename) |
- </details>
- ## Release process
- See [RELEASE.md](./RELEASE.md) for the release runbook, tag naming conventions, security design, and recovery procedures.
- ## License
- MIT — see [LICENSE](./LICENSE).
skills/factory/factory-review/scripts/bash/check-verdict-head.sh · Bundled script · 462 lines · 2 findings marked
- #!/usr/bin/env bash
- # Verify that the latest factory-review verdict names the current PR head.
- #
- # CDR-022 exemption (no PowerShell twin): invoked only by CI
- # (.github/workflows/verdict-head.yml) on ubuntu runners, where bash is
- # guaranteed; a Windows twin would have no caller.
- #
- # A factory-review verdict certifies exactly ONE head SHA — the one carried in
- # its `head=<sha>` marker. Any push after the verdict (a fix, a rebase, a
- # force-push) moves the head and invalidates it, so the review must run again
- # on the new head before merge-readiness is claimed.
- #
- # The skill states that rule; this script makes it mechanical: it reads the
- # PR's comments and review bodies, finds the latest factory-review review
- # verdict, and compares the head it names with the head being merged.
- #
- # Usage:
- # check-verdict-head.sh --repo <owner/repo> --pr <number> --pr-head <sha>
- # check-verdict-head.sh --verdicts <file> --pr-head <sha> # offline
- # ... [--require-outcome]
- #
- # Exit codes (default mode — a staleness check):
- # 0 = no factory-review verdict, or the verdict names the current head
- # 1 = the verdict is stale or unbound — the review must be re-run on this head
- # 2 = usage or infrastructure error (bad arguments, unreadable comments)
- #
- # --require-outcome upgrades the check from "is this verdict current?" to the
- # merge gate "may this PR merge?". The head being current answers only the
- # first question: a verdict can name the current head and still be a
- # not-merge-ready verdict, or one reporting open Important findings. With the
- # flag set the gate additionally fails (exit 1) on a verdict that:
- # - does not exist at all (an unreviewed PR is not merge-ready)
- # - omits `outcome=` or `important=` from its marker (fails closed — a
- # marker published before this schema cannot claim merge-readiness by
- # silence)
- # - carries `outcome=not-merge-ready`
- # - carries `important=` greater than zero (this repository's review policy
- # treats an open Important finding as blocking a merge)
- # - carries an `outcome=` or `important=` value that is not a legal one
- # The head rules are unchanged: the gate is an additional question, not a
- # replacement, so a stale or unbound head still fails under the flag.
- #
- # EVERYTHING THAT COMES BACK FROM GITHUB IS UNTRUSTED. The repository is
- # public: any account can comment, and a comment body can say anything. A
- # body therefore never reaches the parser. jq extracts the fields the checker
- # needs — the timestamp, the author, the author's association with the
- # repository, and the head named inside the `<!-- factory-review:step=review
- # … -->` marker — and hands back one tab-separated record per comment or
- # review. A body can therefore neither create a record nor choose where that
- # record sits in the ordering, and no value a body carries (a timestamp, a
- # head, a separator line) can reach the comparison.
- #
- # The head is read from INSIDE the marker only: a `head=<sha>` that appears in
- # prose — outside any marker — is never read. The value must be a full
- # 40-character SHA.
- #
- # A verdict counts only when it comes from an account that collaborates with
- # the repository (owner, organization member, collaborator). When no such
- # account has posted a verdict, the newest verdict of any author is used
- # instead — the check must never turn green because it declined to read the
- # only verdict there is.
- #
- # The --verdicts file holds one or more records; a line of three percent
- # signs separates them and the LAST record is the newest. That separator is a
- # local fixture convention only: nothing that arrives over the network is
- # ever split on it.
- set -u
- export LC_ALL=C
- REPO=""
- PR=""
- PR_HEAD=""
- VERDICTS_FILE=""
- REQUIRE_OUTCOME=0
- usage_error() {
- echo "check-verdict-head: $*" >&2
- exit 2
- }
- # A flag must be followed by a value. Without this check, `shift 2` on a
- # trailing flag fails without shifting and the parser loops forever.
- require_value() {
- if [ "$2" = "" ]; then
- usage_error "$1 requires a value"
- fi
- }
- while [ "$#" -gt 0 ]; do
- case "$1" in
- --repo) require_value "$1" "${2:-}"; REPO="$2"; shift 2 ;;
- --pr) require_value "$1" "${2:-}"; PR="$2"; shift 2 ;;
- --pr-head) require_value "$1" "${2:-}"; PR_HEAD="$2"; shift 2 ;;
- --verdicts) require_value "$1" "${2:-}"; VERDICTS_FILE="$2"; shift 2 ;;
- --require-outcome) REQUIRE_OUTCOME=1; shift ;;
- --help|-h) awk 'NR>1 && /^#/ { sub(/^# ?/, ""); print; next } NR>1 { exit }' "$0"
- exit 0 ;;
- *) usage_error "unknown argument '$1'" ;;
- esac
- done
- if [ -z "$PR_HEAD" ]; then
- usage_error "--pr-head <sha> is required"
- fi
- # The jq library: the ONLY place that ever looks at a comment body.
- #
- # `verdict_record` answers one question about a body: does it carry a
- # factory-review verdict marker, and what does that marker declare? It
- # returns a state (none / unbound / malformed / ok), the head it names, and
- # the marker's outcome and important-count, never the body itself. Everything
- # it returns is validated: the timestamp must be a full ISO-8601 UTC instant,
- # the head must be a full 40-character SHA, the outcome must be one of the two
- # legal verdicts, the important-count must be a non-negative integer, and the
- # author and the author's association are reduced to safe alphabets. The
- # marker region is taken from the text between `<!--` and the marker's own
- # closing `-->`, so a `head=` that appears in prose — outside any marker — is
- # never read.
- #
- # An absent field and an illegal one are kept apart: `-` means the marker
- # declared nothing, `invalid` means it declared something that is not a legal
- # value. The merge gate treats both as failures, but for different reasons —
- # one is a marker published before this schema, the other is a marker that
- # violates it — so the script can say which.
- JQ_LIB=$(cat <<'JQEOF'
- 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;
- def trim_ws: sub("^[[:space:]]+"; "");
- def marker_regions:
- [ . | split("<!--")[1:][]
- | select(contains("-->"))
- | (trim_ws | split("-->")[0]) as $seg
- | select($seg | startswith("factory-review:step=review"))
- | $seg ];
- def head_token:
- ( [ splits("\\s+") | select(length > 0) | select(startswith("head=")) | .[5:] ] | .[0] // "-" );
- def outcome_token:
- ( [ splits("\\s+") | select(length > 0) | select(startswith("outcome=")) | .[8:] ] | .[0] // "-" );
- def important_token:
- ( [ splits("\\s+") | select(length > 0) | select(startswith("important=")) | .[10:] ] | .[0] // "-" );
- def verdict_record:
- if (test("factory-review:step=review") | not) then {state: "none", head: "-", outcome: "-", important: "-"}
- else
- ( [ marker_regions[] | head_token ] ) as $vals
- | ( [ $vals[] | select(test("^[0-9a-fA-F]{40}$")) ] | .[0] // "-" ) as $good
- | ( [ marker_regions[] | outcome_token ] | map(select(. != "-")) | .[0] // "-" ) as $oc
- | ( [ marker_regions[] | important_token ] | map(select(. != "-")) | .[0] // "-" ) as $im
- | ( if $oc == "-" then "-"
- elif ($oc == "merge-ready" or $oc == "not-merge-ready") then $oc
- else "invalid" end ) as $outcome
- | ( if $im == "-" then "-"
- elif ($im | test("^[0-9]+$")) then $im
- else "invalid" end ) as $important
- | if $good != "-" then {state: "ok", head: $good, outcome: $outcome, important: $important}
- elif ([ $vals[] | select(. != "-") ] | length) > 0 then {state: "malformed", head: "-", outcome: $outcome, important: $important}
- else {state: "unbound", head: "-", outcome: $outcome, important: $important}
- end
- end;
- JQEOF
- )
- # The live filter: one record per comment or per review. A record carries
- #
- # <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
- #
- # and never any part of a comment body. The outcome and the important-count
- # ride along so the merge gate can read what the verdict concluded; in the
- # default (head-only) mode they are simply unused.
- JQ_FILTER_JSON=$(cat <<'JQEOF'
- .[] | ((.submitted_at // .created_at // "") | iso_ts) as $ts
- | ((.user.login // "") | gsub("[^A-Za-z0-9._-]"; "")) as $who
- | ((.author_association // "NONE") | gsub("[^A-Za-z]"; "")) as $assoc
- | ((.body // "") | verdict_record) as $rec
- | "\($ts)\t\($who)\t\($assoc)\t\($rec.state)\t\($rec.head)\t\($rec.outcome)\t\($rec.important)"
- JQEOF
- )
- # The offline filter: the file's records are separated by a line of three
- # percent signs; the last record is the newest, so the records carry no
- # timestamp and no author.
- JQ_FILTER_RAW=$(cat <<'JQEOF'
- def split_records:
- reduce (split("\n")[]) as $line (
- {records: [[]]};
- if ($line | test("^[[:space:]]*%%%[[:space:]]*$")) then .records += [[]]
- else .records[-1] += [$line]
- end
- )
- | .records
- | map(join("\n"));
- split_records | .[] | (verdict_record) as $rec | "-\t-\t-\t\($rec.state)\t\($rec.head)\t\($rec.outcome)\t\($rec.important)"
- JQEOF
- )
- require_jq() {
- if ! command -v jq >/dev/null 2>&1; then
- echo "check-verdict-head: jq is required to read the verdicts" >&2
- exit 2
- fi
- }
- # Run jq over a filter, failing closed when jq cannot parse the input.
- # Reads stdin. $1 is the input mode ("raw" for raw text, "json" for JSON).
- run_jq() {
- _mode="$1"
- _filter="$2"
- _jqerr=$(mktemp) || {
- echo "check-verdict-head: could not create a temporary file for the parser error" >&2
- exit 2
- }
- trap '[ -n "${_jqerr:-}" ] && rm -f "$_jqerr"' EXIT HUP INT TERM
- if [ "$_mode" = "raw" ]; then
- # --slurp: the whole file is ONE input, not one input per line.
- jq --raw-input --slurp -r "$_filter" 2>"$_jqerr"
- else
- jq -r "$_filter" 2>"$_jqerr"
- fi
- _rc=$?
- if [ "$_rc" -ne 0 ]; then
- echo "check-verdict-head: could not parse the verdicts (jq exited $_rc):" >&2
- if [ -f "$_jqerr" ]; then sed 's/^/ /' "$_jqerr" >&2; fi
- rm -f "$_jqerr"
- trap - EXIT HUP INT TERM
- exit 2
- fi
- rm -f "$_jqerr"
- trap - EXIT HUP INT TERM
- }
- # Run one `gh api` call and print its raw payload. Fails closed: a failed
- # call is an infrastructure error, never "there is no verdict".
- gh_records() {
- _endpoint="$1"
- _label="$2"
- _err=$(mktemp) || {
- echo "check-verdict-head: could not create a temporary file for the gh error" >&2
- exit 2
- }
- trap '[ -n "${_err:-}" ] && rm -f "$_err"' EXIT HUP INT TERM
- _out=$(gh api "$_endpoint" --paginate 2>"$_err")
- _rc=$?
- if [ "$_rc" -ne 0 ]; then
- echo "check-verdict-head: could not read $_label (gh api exited $_rc):" >&2
- if [ -f "$_err" ]; then sed 's/^/ /' "$_err" >&2; fi
- rm -f "$_err"
- trap - EXIT HUP INT TERM
- exit 2
- fi
- rm -f "$_err"
- trap - EXIT HUP INT TERM
- printf '%s\n' "$_out"
- }
- # The records the checker parses. Every line is
- # <timestamp>\t<author>\t<association>\t<state>\t<head>
- # and no line carries any part of a comment body.
- fetch_records() {
- if [ -n "$VERDICTS_FILE" ]; then
- if [ ! -f "$VERDICTS_FILE" ]; then
- echo "check-verdict-head: could not read the verdicts file '$VERDICTS_FILE'" >&2
- exit 2
- fi
- require_jq
- run_jq "raw" "${JQ_LIB}${JQ_FILTER_RAW}" < "$VERDICTS_FILE"
- return 0
- fi
- if ! command -v gh >/dev/null 2>&1; then
- echo "check-verdict-head: gh is not available and --verdicts was not given" >&2
- exit 2
- fi
- if [ -z "$REPO" ] || [ -z "$PR" ]; then
- missing=""
- [ -z "$REPO" ] && missing="--repo"
- [ -z "$PR" ] && missing="${missing:+$missing }--pr"
- echo "check-verdict-head: $missing required without --verdicts" >&2
- exit 2
- fi
- require_jq
- # Issue comments and review bodies both carry the marker; inline review
- # comments have no body, so the review body is what matters. Each call is
- # checked on its own: a failure on either is an infrastructure error.
- _comments=$(gh_records "repos/$REPO/issues/$PR/comments" "the PR's issue comments") || exit 2
- _reviews=$(gh_records "repos/$REPO/pulls/$PR/reviews" "the PR's review bodies") || exit 2
- printf '%s\n%s\n' "$_comments" "$_reviews" | run_jq "json" "${JQ_LIB}${JQ_FILTER_JSON}"
- }
- # The newest verdict among the records.
- #
- # 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
- # where the state is one of
- # none — no record carries a verdict marker at all
- # unbound — a verdict exists but its marker names no head
- # malformed — a verdict names something that is not a full 40-character SHA
- # ok — the verdict names <head>
- # The newest record wins: the newest timestamp, and among equal timestamps
- # the later record. A record without a timestamp never beats a timestamped
- # one. A verdict only counts when it comes from an account that collaborates
- # with the repository; when no such account has posted one, the newest
- # verdict of any author is used, so that the check never goes green merely
- # because it declined to read the only verdict there is.
- select_verdict() {
- awk -F'\t' '
- function trusted(a) {
- return (a == "OWNER" || a == "MEMBER" || a == "COLLABORATOR")
- }
- BEGIN { FS = "\t"; n = 0 }
- NF == 0 { next }
- $4 == "none" { next }
- {
- n++
- ts[n] = $1; who[n] = $2; assoc[n] = $3; st[n] = $4; hd[n] = $5
- oc[n] = $6; im[n] = $7
- }
- END {
- has_trusted = 0
- for (i = 1; i <= n; i++) if (trusted(assoc[i])) has_trusted = 1
- best = 0
- for (i = 1; i <= n; i++) {
- if (has_trusted && !trusted(assoc[i])) continue
- if (best == 0) { best = i; continue }
- if (ts[i] != ts[best]) {
- if (ts[i] == "-") continue
- if (ts[best] != "-" && ts[i] < ts[best]) continue
- }
- best = i
- }
- if (best == 0) { print "none\t-\t-\t-\t-\t-"; exit 0 }
- print st[best] "\t" hd[best] "\t" who[best] "\t" assoc[best] "\t" oc[best] "\t" im[best]
- }
- '
- }
- RECORDS=$(fetch_records) || exit 2
- # printf '%s' (not '%s\n'): with zero comments and zero reviews RECORDS is
- # empty, and a trailing newline would hand the selector one blank record —
- # a phantom verdict with empty fields that failed every fresh PR.
- if ! SELECTED=$(printf '%s' "$RECORDS" | select_verdict); then
- echo "check-verdict-head: could not parse the PR's comments (the parser failed)" >&2
- exit 2
- fi
- STATE=$(printf '%s\n' "$SELECTED" | cut -f1)
- VERDICT_HEAD=$(printf '%s\n' "$SELECTED" | cut -f2)
- VERDICT_AUTHOR=$(printf '%s\n' "$SELECTED" | cut -f3)
- VERDICT_ASSOC=$(printf '%s\n' "$SELECTED" | cut -f4)
- VERDICT_OUTCOME=$(printf '%s\n' "$SELECTED" | cut -f5)
- VERDICT_IMPORTANT=$(printf '%s\n' "$SELECTED" | cut -f6)
- if [ "$VERDICT_AUTHOR" = "-" ]; then
- AUTHOR_NOTE="(author unknown)"
- elif [ "$VERDICT_ASSOC" = "OWNER" ] || [ "$VERDICT_ASSOC" = "MEMBER" ] || [ "$VERDICT_ASSOC" = "COLLABORATOR" ]; then
- AUTHOR_NOTE="(posted by $VERDICT_AUTHOR — $VERDICT_ASSOC)"
- else
- AUTHOR_NOTE="(posted by $VERDICT_AUTHOR — not a collaborator with the repository)"
- fi
- if [ "$STATE" = "none" ]; then
- if [ "$REQUIRE_OUTCOME" = "1" ]; then
- echo "check-verdict-head: FAIL — no factory-review verdict on this PR."
- echo " The merge gate asks whether this PR may merge. A PR with no verdict"
- echo " has not been certified merge-ready, so the gate cannot pass it:"
- echo " passing on silence would turn the check green for exactly the PRs"
- echo " nobody reviewed. Run the review on this head."
- exit 1
- fi
- echo "check-verdict-head: OK — no factory-review verdict on this PR; nothing to verify."
- exit 0
- fi
- if [ "$STATE" = "unbound" ]; then
- echo "check-verdict-head: FAIL — a factory-review verdict exists but names no head."
- echo " $AUTHOR_NOTE"
- echo " A verdict that names no head certifies nothing: it cannot be checked"
- echo " against a head, so it cannot support a merge-ready claim."
- echo " Re-run the review on the current head so the marker names it."
- exit 1
- fi
- if [ "$STATE" = "malformed" ]; then
- echo "check-verdict-head: FAIL — the verdict's head= value is not a full 40-character SHA."
- echo " $AUTHOR_NOTE"
- echo " A verdict that names no usable head certifies nothing: it cannot be checked"
- echo " against a head, so it cannot support a merge-ready claim."
- echo " Re-run the review on the current head so the marker names it."
- exit 1
- fi
- verdict_head=$(printf '%s' "$VERDICT_HEAD" | tr '[:upper:]' '[:lower:]')
- pr_head=$(printf '%s' "$PR_HEAD" | tr '[:upper:]' '[:lower:]')
- if [ "$verdict_head" != "$pr_head" ]; then
- echo "check-verdict-head: FAIL — the verdict names $VERDICT_HEAD but the head is $PR_HEAD."
- echo " $AUTHOR_NOTE"
- echo " A fix push invalidates the verdict: re-run the review passes on the current"
- echo " head and post the updated verdict naming $PR_HEAD before claiming merge-readiness."
- exit 1
- fi
- # The verdict is current. In the default mode that answers the whole question
- # and the check passes; the question asked there is staleness. The merge gate
- # asks one more: does this verdict say the PR may merge? A current verdict can
- # still be a not-merge-ready one, or one carrying open Important findings, and
- # neither may be shown as a green merge gate. Every field the gate reads is
- # checked fail-closed: a verdict that declares nothing cannot certify anything.
- if [ "$REQUIRE_OUTCOME" = "1" ]; then
- if [ -z "$VERDICT_OUTCOME" ] || [ "$VERDICT_OUTCOME" = "-" ]; then
- echo "check-verdict-head: FAIL — the verdict declares no outcome."
- echo " $AUTHOR_NOTE"
- echo " The marker names the head but omits outcome=, so it says nothing about"
- echo " merge-readiness. The gate fails closed: a verdict that declares nothing"
- echo " cannot certify that the PR may merge. Re-run the review so the marker"
- echo " carries outcome=merge-ready or outcome=not-merge-ready."
- exit 1
- fi
- if [ "$VERDICT_OUTCOME" = "invalid" ]; then
- echo "check-verdict-head: FAIL — the verdict's outcome= is not a legal value."
- echo " $AUTHOR_NOTE"
- echo " outcome= must be merge-ready or not-merge-ready; a value the gate does"
- echo " not recognise cannot be trusted to mean either. Re-run the review so the"
- echo " marker carries a legal outcome."
- exit 1
- fi
- if [ -z "$VERDICT_IMPORTANT" ] || [ "$VERDICT_IMPORTANT" = "-" ] || [ "$VERDICT_IMPORTANT" = "invalid" ]; then
- echo "check-verdict-head: FAIL — the verdict's important= is missing or not a count."
- echo " $AUTHOR_NOTE"
- echo " The gate reads important= to learn whether Important findings are open."
- echo " A marker that omits it, or makes it unreadable, cannot prove that none"
- echo " are, so the gate fails closed. Re-run the review so the marker carries"
- echo " important=<count>."
- exit 1
- fi
- if [ "$VERDICT_OUTCOME" = "not-merge-ready" ]; then
- echo "check-verdict-head: FAIL — the verdict says outcome=not-merge-ready."
- echo " $AUTHOR_NOTE"
- echo " The verdict is current, so it is not stale; it concludes the PR may not"
- echo " merge. The gate reports that conclusion instead. Address the blocking"
- echo " findings and re-run the review to clear it."
- exit 1
- fi
- if [ "$VERDICT_IMPORTANT" -gt 0 ] 2>/dev/null; then
- echo "check-verdict-head: FAIL — the verdict reports $VERDICT_IMPORTANT open Important finding(s)."
- echo " $AUTHOR_NOTE"
- echo " An Important finding blocks a merge, so a verdict counting one cannot"
- echo " certify merge-readiness even when its outcome= says merge-ready: the"
- echo " count is the fact, the outcome string only summarises it. Resolve the"
- echo " findings and re-run the review."
- exit 1
- fi
- echo "check-verdict-head: OK — the verdict names the current head and declares merge-ready."
- echo " $AUTHOR_NOTE"
- exit 0
- fi
- echo "check-verdict-head: OK — the verdict names the current head ($PR_HEAD)."
- echo " $AUTHOR_NOTE"
- exit 0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.