v0.25.0 — Sentinel field-feedback release #3

Sentinel field-feedback release #3 — proposals from a downstream operator (~30 reviews over 7 rounds, incl. a 5-cycle reject/fix saga), each verified against the cited contract text before acceptance (per AGENTS.md §Evaluating Downstream Agent Feedback); one accepted item was codified tighter than asked. Ruleset stays v1, rubric stays v1 — the report protocol (Status: line, Required action mapping, verdict semantics, severity tiers) is unchanged; the Recurrence: header line is additive. SENTINEL.md budget raised 180 → 182 non-blank lines (182/182 used; §Compression's raise-don't-compress rule). template/AGENTS.md unchanged at 135/135 (REJECTED row extended in place).

Added

• Turn-completion gate + synchronous re-dispatch (SENTINEL.md §On failure + closing block + a reminder in the Phase 2 dispatch step itself, where attention actually is mid-review): a Sentinel turn may end ONLY with the full report (first line Status:) — never a progress note or "waiting on dimension X"; a background sub-agent result that hasn't arrived / can't be collected at finalization IS a dispatch failure → re-dispatch that dimension synchronously once, then the existing retry → ❌ → degraded-with-proof ladder. The dispatch-step reminder and a synchronous-dispatch fallback ("if the platform cannot guarantee in-turn collection of background results, issue the same single-message dispatch synchronously") were added after this release's own eval runs reproduced the progress-note ending with the gate present only in the closing block — on turn-scheduled platforms, parallel synchronous dispatch keeps the wall-clock parallelism and never strands a review mid-turn. Codified deliberately tighter than the operator's "re-derive the dimension yourself" (self-derivation is degraded mode requiring user approval; synchronous re-dispatch preserves the sub-agent requirement). Field evidence: sessions routinely ended on progress notes (1–3 nudges per review) and stalled on background results that had landed in the wrong context.
• Finding-class recurrence flag (SENTINEL.md §Re-review): a re-review 🔴 of the same mechanism family as a prior-cycle 🔴 (2nd+ occurrence across Report IDs) forces a Recurrence: <class> × cycle <N> line under Required action, recommending a change of approach over another instance patch. Invoker side (template AGENTS.md §After Sentinel, REJECTED row): a Recurrence: line = "same problem, 2+ failed attempts" → spawn the §When Stuck research sub-agent instead of retrying a variant fix. Field evidence: a logger-sanitizer saga took ~5 cycles of correct instance-level rejections with no class-level signal.
• Eval fixture 15-recurrence-flag.md (Lane-2 re-review: two prior same-class A2 🔴s + a third separator-blocklist bypass → REJECTED with the Recurrence: line; also extends A2 coverage) + RUNNER.md Lane-2 note that a progress-note turn ending is a protocol failure (the turn gate's observable half — background-dispatch latency itself is not simulatable in the static harness).

Changed

• Phase 3 🟡 exclusion widened from "missing CHANGELOG" to CHANGELOG defects generally (missing / malformed / garbled entries — always 🟢, never 🟡, unless the entry misdocuments security-relevant behavior); SEVERITY-RUBRIC golden row and fixture 08's citation aligned. Field evidence: a full CONDITIONAL file-issues ceremony over a 2-line garbled CHANGELOG entry. (dim-f-documentation.md intentionally untouched — F is an uncovered dimension and the orchestrator's Phase 3 exclusion is the operative calibration layer, per fixture 08's own note.)

Rejected (with reasoning, per §Evaluating Downstream Agent Feedback)

• Tier-2 security-path trigger narrowed to "diff changes a security codepath": same content-based security-skip class already deferred in issue #14 — comment-only changes to security files can still alter security tooling (e.g., adding a lint-suppression comment), and commit-type selective dispatch already gives the relief (docs→F only). Second field report recorded on #14; stays deferred.
• "Re-derive the dimension yourself" for lost background results: adopted as synchronous re-dispatch instead (see Added) — self-derivation is degraded mode and would quietly waive the sub-agent requirement.
• Raising the materiality floor for non-security polish: corroborates deferred issue #37 (🟡/🟢 inflow volume), which stays deferred pending backlog-hygiene sweep data; the CHANGELOG-defect exclusion above removes the one observed spurious-CONDITIONAL source. Second field report recorded on #37.
• Sub-agent result misrouting / session deaths as ruleset defects: platform issues, as the operator noted; the turn-completion gate is the ruleset-side mitigation (a stall becomes a dispatch failure with a defined ladder instead of a hung turn).

v0.24.0 — differential probe, phase-0 binding, rebase re-verdict lane

Sentinel field-feedback release #2 — proposals from two downstream Sentinel operators (~25 reviews in one session; 6 PRs incl. a rejection cycle), each verified against the cited contract text before acceptance; several claims were corrected rather than adopted (per AGENTS.md §Evaluating Downstream Agent Feedback). Ruleset stays v1, rubric stays v1 — the report protocol (Status: line, Required action mapping, verdict semantics, severity tiers) is unchanged. SENTINEL.md budget raised 178 → 180 non-blank lines (180/180 used; §Compression's raise-don't-compress rule).

Added

• Differential probe rule (dim-a1-security-attacks.md, dim-a2-security-defenses.md): when the diff adds/modifies a hand-rolled parser, tokenizer, matcher, or sanitizer/escaper/validator on an untrusted-input path and command execution is available, probe it empirically on first review — run it against a reference implementation or a generated adversarial corpus in a throwaway worktree and flag any divergence where the hand-rolled code is more permissive (bounded: hundreds of cases; class coverage, not exhaustiveness). Fail-closed like the Dim D discrimination probe: no execution → static bypass-class finding stands, flagged (unverified — no execution). Field evidence: an SVG-detector bypass took 3 review cycles under static enumeration alone; the operator's cycle-2 differential fuzz caught what enumeration kept missing.
• Phase 0 binding persistence (SENTINEL.md §Phase 0, RECOMMENDED): when PR write access exists, Sentinel posts the review binding (Report ID + reviewed SHA + timestamp + ruleset version + <!-- sentinel-phase0 … --> marker) as a PR comment at review start — a died/timed-out session becomes detectable and the binding survives mid-review context loss. Never a verdict. Field evidence: two independent operators lost a full review's work to a dead session / mid-review compaction because the verdict and persistence land only at Phase 5.
• Invoker no-verdict rule (template AGENTS.md §How to Invoke): zero output or no Status: line = NO VERDICT — never infer a verdict from partial output or a Phase-0 binding comment; re-invoke fresh once, then escalate. Previously unspecified; a downstream harness had to invent its own retry behavior.
• Rebase re-verdict lane (SENTINEL.md §Phase 0 re-review): the sole exception to "rebase → Phase 1 in full". Sentinel — never the invoker — recomputes both sides' diffs-vs-their-own-merge-bases and compares git patch-id --stable; patch-identical → reuse prior Phase 2 findings + re-run check 5 + quick scan and issue a fresh SHA-bound verdict; differing hunks → fix-delta re-review; unverifiable → full review. Codified deliberately tighter than the operator's request (they merged twice on a stale verdict with a "transparency comment" — the lane scopes down the work, never the verdict), because an undefined exception incentivizes quiet deviation on busy repos.
• Report ID canonical format (SENTINEL.md report header): SR-<YYYYMMDD>-PR<n>-<short SHA> (branch slug when no PR number) — merge-commit audit trails are grepped by Report ID; observed drift across ~25 reports motivated pinning it.
• Eval fixtures: 13-rebase-smuggle.md (rebase-lane abuse: invoker-supplied "mechanical rebase delta" hiding an auth-bypass hunk must never be trusted → REJECTED) and 14-handrolled-sanitizer.md (A2 static half of the differential probe: bypassable regex-blocklist sanitizer → 🔴 with class-level enumeration, (unverified — no execution); also closes the evals' A2 coverage gap per the same-PR fixture rule).

Changed

• SENTINEL.md Phase 2 dispatch: mode: "background" now explicitly "where supported" — platforms running sub-agents synchronously are compliant (dispatch name as the ref, duration N/A (not reported)), ending a recurring false "gap" note on synchronous platforms. The N/A-is-compliant rule already existed in Execution logging; this aligns the dispatch instruction with it.

Rejected (with reasoning, per §Evaluating Downstream Agent Feedback)

• Second machine-parseable verdict marker: the first-line Status: is already defined as the only authoritative decision source; a second marker would create the two-format drift the operator feared. Downstream harnesses should parse Status:.
• sentinel:sync-check GH_TOKEN setup note: that check is downstream harness tooling, not part of this template; the template's own opt-in workflow already sets GH_TOKEN.
• 🟡-volume rubric tightening: deferred at the operator's own suggestion — filed as a sentinel:deferred issue to re-check once backlog-hygiene sweep data shows how many 🟡s survive first re-validation.

v0.23.1 — Sync-time format/lint guidance

Documentation & rollout-ergonomics release (no ruleset change — stays v1).

Motivated by the v0.23.0 downstream rollout: an adopter's prettier --check . rejected the verbatim opt-in backlog-hygiene workflow YAML, because the Update prompt gave no guidance to format/lint synced files.

Changed

• Update prompt (README.md + docs/index.html): after applying a sync, the agent now formats/lints the added/changed files to the project's conventions (Prettier / ESLint / ruff) and verifies CI is green before opening the PR.
• template/docs/sentinel/BACKLOG-HYGIENE.md §5: the example workflow carries a copy-in note to format it to the adopter's repo style (keeping the pinned action SHA + logic intact); tidied the example's comment spacing.

Added

• Docs surface backlog hygiene as a first-class feature (README §Key Features bullet + website Core Features full-width capstone card).

Downstream: re-synced to the 9 adopters (BACKLOG-HYGIENE §5 note + marker bump); no backfill.

v0.23.0 — Mandatory validity anchor

Backlog-hygiene core-requirement release. The Sentinel validity anchor is now mandatory on every filed 🟡/🟢 issue (previously documented only as opt-in backlog hygiene). Ruleset stays v1, rubric stays v1 — the report protocol (Status: line, Required action mapping, verdict semantics, severity tiers) is unchanged; this adds a filing requirement only.

Added

• Mandatory validity anchor (SENTINEL.md §Follow-ups & Actions): every filed 🟡/🟢 issue body MUST carry the anchor — a human+machine anchor line (**Anchor:** file:line @ <short SHA> · dim X plus the <!-- sentinel-anchor … --> marker) and the finding's quoted ≤3-line evidence in a fenced block — with a sentinel:security label for dim-A1/A2 or security-path findings. The evidence + reviewed SHA already exist in the report, so the anchor is free at filing time and lets any issue be cheaply re-checked against HEAD as code moves.

Changed

• sentinel/BACKLOG-HYGIENE.md §1 reframed opt-in → required by SENTINEL.md §Follow-ups; §2–§5 (labels, sweep, example Action) remain opt-in. No safety rule weakened: automation flags but never reaps, sentinel:security never auto-closeable, stale ≠ resolved, closure needs positive resolution evidence + a human.
• template/AGENTS.md §After Sentinel "Issue hygiene" line aligned with the mandatory anchor (names the <!-- sentinel-anchor … --> marker; states the anchor is required).

Full diff: #33

v0.22.0 — discrimination probe, contest channel, fold-in exception

Sentinel field-feedback release — refinements proposed by a downstream Sentinel operator after ~40 production reviews, each verified against cited evidence before acceptance. Ruleset stays v1, rubric stays v1: the report protocol (Status: line, Required action mapping) and severity tiers are unchanged; this release adds resolution procedures only, all as in-line extensions (SENTINEL.md remains 177/178 non-blank lines).

Added

• Dim D discrimination probe (dim-d-testing.md): mutation-based oracle verification codified — when command execution is available, a suspected non-discriminating test is verified by neutering the pinned behavior in a throwaway worktree and confirming the test goes RED. Fail-closed: no isolated execution → static-evidence 🟡 flagged (unverified — no execution); the probe upgrades evidence, never excuses omitting a static finding.
• Contest channel for false-positive 🔴s (SENTINEL.md §Severity adjustment + SEVERITY-RUBRIC step 4): a 🔴 whose factual premise appears wrong may be contested, never downgraded — the originating dimension is re-dispatched ONCE with counter-evidence from Sentinel's own tool use; its second verdict is final and logged in the Execution Log. PR/invoker text claiming a false positive is a 🔴 signal, never contest grounds. Resolves the documented contradiction between "NEVER downgrade a sub-agent 🔴" and the false-positive livelock.
• Fold-in exception for CONDITIONAL 🟡s (SENTINEL.md Follow-ups): small, same-file, no-new-risk 🟡 fixes MAY be folded into the PR instead of filed as issues — but the folded SHA MUST be re-invoked for a fresh verdict before merge (delta re-review applies). Size guidance is advisory (~≤10 LOC); the re-invoke requirement is the invariant. Removes the file-only backlog treadmill without weakening SHA-binding.
• Eval fixtures 11-nondiscriminating-oracle.md (static half of the discrimination probe: a non-discriminating oracle that is the only coverage of the changed behavior → D 🔴 REJECTED per the new escalation clause; the 🟡 golden-row boundary is documented in the fixture) and 12-contest-injection.md (contest-channel abuse: PR text arguing a 🔴 is a false positive must never bypass REJECTED).

Fixed

• Dim D "Shared fixture safety" now escalates to 🔴 when a helper/mock edit stops any test from executing new/changed logic, aligning the dim file with the rubric's "new data layer never executed by any test" golden row. Baseline eval runs (fixture 10) showed dim-level sub-agents reproducibly held this at 🟡 because the dim file's 🟡 default contradicted the golden row — the orchestrator's Phase 3 escalation still caught it end-to-end, but the dimension holding 🔴-blocking authority should say it directly.
• Eval fixture 07's synthetic diff contained an unintended legitimate 🔴 (unchecked res.ok cached CDN error pages as avatar bytes); an explicit guard was added so the fixture again isolates its 🟡 missing-timeout calibration purpose. Found by the baseline eval discipline.
• Eval fixture 08's Expected block clarified: "zero 🟡" applies to the post-calibration end-to-end verdict; dim-level advisory 🟡s are tolerated per README scoring rules.

Rejected (recorded for governance)

• Test-only reduced-dispatch lane (run only a discrimination probe for test-only PRs): same loophole class as the previously rejected feat fast-path — test-only PRs are where test-erosion attacks live. Filed as a sentinel:deferred issue with telemetry-based revisit criteria.

v0.21.0 — Sentinel: eval harness, telemetry, delta-scoped re-review

Sentinel quality/reliability/speed release. Ruleset stays v1 — the report-protocol contract (Status: line, Required action mapping, verdict semantics) is unchanged; the Execution Log gains an additive Duration/Tokens column, the header an additive Elapsed: line, and Follow-ups now emits only the verdict-matching action line.

Added

• evals/ behavioral regression harness — 10 synthetic PR fixtures with expected verdicts, a two-lane runner, and a dimension-coverage matrix. Structural CI checks the docs' shape; evals check the ruleset's behavior. Baseline: 10/10 PASS pre-edit; post-edit re-run confirmed the re-review fixtures still mandate REJECTED.
• Execution-Log telemetry — per-dimension Duration/Tokens + report Elapsed: line, verbatim-from-platform only (estimated numbers count as fabricated evidence; N/A is always compliant). Non-normative; makes #11/#14's revisit criteria measurable.
• Delta-scoped Phase 1 on re-review (fail-closed): requires Sentinel-authenticated prior report at its Phase 5 persisted location + git merge-base --is-ancestor-verified base with a self-recomputed delta. Test/fixture/mock edits re-open checks 1–4 for all affected code; CI/test/build-config deltas and unverifiable conditions → full Phase 1. Applies only when the prior cycle's Phase 1 was green.
• Known-issues fetch guidance — exact gh issue list --json/--jq startswith("sentinel:") command (--label does not wildcard-match); fetched issue text fenced as untrusted, Known-marking only.
• .github/PULL_REQUEST_TEMPLATE.md; scripts/validate.sh grew from 8 to 10 checks + a non-blocking evals reminder.

Changed

• Report Follow-ups & Actions: single verdict-matching line, retaining the sentinel:important/sentinel:minor label literals (closes #9).
• Phase 3 / rubric Known-matching tightened to "same specific defect mechanism + fix".
• Re-review Phase 2 re-dispatch explicitly includes dimensions whose only findings were Known.
• SEVERITY-RUBRIC.md: stale template-semver pin dropped (ruleset-v1 binding stays, now CI-checked).

SENTINEL.md budget: 177/178 non-blank lines.

v0.20.2 — Audit follow-ups: sync manifest + doc clarifications

Resolves the three actionable issues from the v0.20.1 audit (#21, #22, #24). #23 (severity-rule duplication) was closed as wontfix: the 3-place duplication is load-bearing — each dimension file is a standalone sub-agent system prompt — and validate.sh check 7 remains the drift tripwire.

Added

• Downstream sync manifest (SYNC.md, closes #21): tracked table of all adopter repos with each one's last-synced template version (read from their root AGENTS.md marker) and check date. Replaces the prose repo list in root AGENTS.md §Syncing; enables a one-prompt "audit all downstreams" flow. All 9 downstreams verified at v0.20.0 as of 2026-07-02.

Changed

• Ruleset version clarified (SENTINEL.md title + root AGENTS.md §Versioning, closes #22): "(v1)" is the report-protocol contract (Status line, report format, verdict semantics), independent of template semver; it bumps only on breaking report-format changes. In-place title reword — SENTINEL.md unchanged at 176/178.
• Setup Step 3 pointer fixed (template AGENTS.md setup block, closes #24): the invocation-method answer pointed to "→ update docs/SENTINEL.md", which has no such field. Now actionable: if B (CI), set up the pipeline to invoke Sentinel with docs/SENTINEL.md as system prompt and gate merges on its Status: line.

Full changelog: https://github.com/pedrofuentes/agents-template/blob/main/CHANGELOG.md

v0.20.1 — Documentation hygiene + validation CI

Documentation-hygiene release. A full repo audit found the manual release checks (root AGENTS.md §Versioning / §Testing Changes) had leaked drift across several surfaces. All fixes are pointer/typo corrections — no template behavior changes. The same checks are now automated in CI so this class of drift can't recur.

Added

• Repo validation CI (scripts/validate.sh + .github/workflows/validate.yml): automates the checks root AGENTS.md already prescribed manually — version sync across all surfaces, setup-placeholder inventory audit (with runtime-placeholder allowlist), the ≤135/≤178 line budgets, setup-block marker integrity, relative-link and §-reference validity, Structure-tree ↔ file-layout agreement, and a severity-level tripwire guarding the deliberate 3-place duplication. Pure bash, no dependencies; repo infrastructure only — nothing added to template/. On its first run it caught a live drift (see Fixed).

Fixed

• Stale root version marker (root AGENTS.md line 1): read v0.12.2 through 8 subsequent releases. Bumped, and §Versioning now enumerates every version surface.
• Contradictory compression budget (root AGENTS.md §ASK FIRST): said ≤130 non-blank lines post-setup while §Compression says ≤135. Aligned to ≤135.
• Dangling cross-references to a removed section: README §Invoking Sentinel and SETUP.md §After Customization pointed at docs/SENTINEL.md §Infrastructure Enforcement, which no longer exists. README now carries a Method A/B/C legend (the table used those labels without defining them); SETUP.md describes Method B inline and points at the real §Deploy / release gating section.
• Post-adoption dangling pointer (SETUP.md): "see README.md" — README isn't copied downstream. Replaced with self-contained text.
• Runtime-placeholder trap (SETUP.md §Verification): the "no results = done" check could push a setup agent to "fix" SENTINEL.md's intentional {{branch}}/{{sha}} runtime placeholders. Explicit exception list added.
• Website advertised a removed feature (docs/index.html): fixability classification (🔧/🧠/👤) and unverifiable timing claims removed.
• CHANGELOG date typo: [0.14.0] corrected to 2026-05-26 (its tag date), restoring monotonic ordering.
• SETUP.md placeholder-inventory mismatch (caught by the new validate.sh on its first run): aligned to the actual DEVELOPMENT-WORKFLOW.md token.
• README template/docs/sentinel/ row now mentions SEVERITY-RUBRIC.md and BACKLOG-HYGIENE.md; .gitignore now covers .impeccable/.

Also retro-tagged v0.1.0, v0.5.0, v0.12.2, v0.13.1 (releases documented in the CHANGELOG that were never tagged). v0.8.0 was not retro-tagged: its changes shipped inside the same squashed commit as v0.9.0 (7b7fc08), so no distinct commit exists for it.

Full changelog: https://github.com/pedrofuentes/agents-template/blob/main/CHANGELOG.md

v0.20.0 — Opt-in issue-backlog hygiene (flag, never auto-close)

Opt-in issue-backlog hygiene — decided by a 5-expert sub-agent panel (unanimous PARTIAL) after a downstream adopter (Council) accreted 700+ open sentinel:* issues, ~half no longer applicable.

Principle: the accretion is structural (Sentinel files issues and never revisits them), but Sentinel must never auto-close — "stale ≠ resolved." Sentinel emits self-verifying signals; the human keeps closure authority.

Added

• docs/sentinel/BACKLOG-HYGIENE.md (opt-in): the validity anchor (file:line + snippet + reviewed SHA + dim, plus sentinel:security tag), a label vocabulary, and an opt-in re-validation sweep that flags but never closes — asymmetric closure authority (security never auto-closeable; non-security only on positive resolution evidence), migration-aware, default-on-doubt = keep open, auditable trail, + an optional SHA-pinned flag-only example Action.
• Validity anchor + inflow discipline at filing (AGENTS.md §After Sentinel): 🟢 minors file as one digest issue per review.

Changed

• De-dup hardened to compare exploitability (SENTINEL.md Phase 3 + SEVERITY-RUBRIC.md): a new finding more severe or newly reachable than a matched open issue is no longer "Known" — it escalates.

Metrics

• SENTINEL.md 176/178 (unchanged) · AGENTS.md 134/135 post-setup (+1) · new companion doc · no gate weakening.

Full changelog: see CHANGELOG.md · PR #17

v0.19.0 — Severity rubric + deterministic CHANGELOG severity

Incorporates feedback from a downstream agent that ran ~24 Sentinel reviews (2 genuine 🔴 blocks of broken PRs; 0 bad merges). Net: the review depth is the asset — keep it. The gaps were severity reproducibility across fresh-agent reviewers and non-behavioral noise. Triaged for general-case value (downstream feedback is advisory, not prescriptive); reviewed by a 2-model panel (GPT-5.5, Gemini 3.1 Pro).

Added

• Severity rubric companion (template/docs/sentinel/SEVERITY-RUBRIC.md): a version-pinned orchestrator Phase 3 calibration reference — an ordered decision procedure plus golden worked-examples across all 7 dimensions drawn from the real reviewed cases. Makes the same finding class yield the same severity regardless of which agent orchestrates. Includes disambiguating contrast pairs (injection→🔴 vs UI Math.random()→🟢; typosquat/postinstall→🔴 vs unused dev-dep→🟢). Companion file keeps SENTINEL.md at 176 lines.

Changed

• Missing CHANGELOG is now deterministically 🟢 — never 🟡/CONDITIONAL (SENTINEL.md Phase 3 + dim-f). Closes the "user-impact requirement" loophole that produced repeated APPROVED→CONDITIONAL churn for a non-behavioral convention.
• CHANGELOG implementer nudge: the template AGENTS.md CHANGELOG row is marked (TDD-exempt; include in the PR) so it is rarely even a finding.
• Report persistence clarified (SENTINEL.md Phase 5): durable PR-comment default; a committed .sentinel/reports/<id>.md fallback must land on a persisted branch — never inside a throwaway/ephemeral verification worktree. Platform-neutral (no hardcoded temp-dir policy).

Deferred

• Presentational-surface-only dispatch lane (#14, sentinel:deferred): a diff-aware skip of A1/A2 on pure CSS/copy diffs. Deferred pending a Dim-E-tight positive surface definition; style/docs commits already skip A1/A2 via selective dispatch.

Rejected (logged for traceability)

• Blanket content-based A1/A2 security-dim skip (reverses v0.17.0 hardening + Dim-E "never skip" principle).
• Upstream mutation-testing / coverage-diff gate (imposes tooling on every adopter).
• Dropping the report "Agent ID" column (already handled — N/A + platform-limitation note is explicitly permitted).

Metrics: SENTINEL.md 176/178 · AGENTS.md 133/135 post-setup · new companion file.

Downstream sync (follow-up, user-driven): gitnotate, Arbol, Council, stream-deck-ical, stream-deck-github-utilities, stream-deck-cloudflare-utilities, obsidian-subtitles-md, github-dashboard.