Release v1.2.0: workflow hardening and audit metadata

.github/workflows/release.yml

@@ -6,30 +6,68 @@ on:
       - 'v*'
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
-  github-release:
+  verify:
+    name: Verify release candidate
     runs-on: ubuntu-latest
     timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
 
       - name: Set up Node.js
         uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
           node-version: '22'
-          cache: npm
 
       - name: Verify tag matches package version
         run: node -e "const version=require('./package.json').version; if ('v' + version !== process.env.GITHUB_REF_NAME) throw new Error('Tag and package version differ')"
 
-      - name: Install dependencies
-        run: npm ci
+      - name: Verify tagged commit is on main
+        run: |
+          git fetch --no-tags origin main:refs/remotes/origin/main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+
+      - name: Run deterministic checks
+        run: npm run check
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Install official reference validator
+        run: >-
+          python -m pip install --disable-pip-version-check --only-binary=:all:
+          --require-hashes -r requirements-validation.txt
+
+      - name: Validate Agent Skills specification
+        run: agentskills validate "$GITHUB_WORKSPACE/skills/agentic-rd-skill"
 
-      - name: Validate repository layout
-        run: npm run validate
+      - name: Validate GitHub skill discovery
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh skill publish --dry-run
+
+  publish:
+    name: Publish GitHub release
+    needs: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
 
       - name: Publish GitHub release
         run: |

CHANGELOG.md

@@ -2,14 +2,34 @@
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-10-31
+
 ### Added
 
-- Documented direct installation through the cross-agent Skills CLI and added the official telemetry-backed `skills.sh` install-count badge, which will resolve automatically after catalog indexing.
+- Documented direct installation through the cross-agent Skills CLI and added the `skills.sh` catalog badge, which will resolve after catalog indexing.
+- The tag-triggered Release workflow now verifies the tag/version match and `main` ancestry, runs the full deterministic check suite, the official Agent Skills validator, and `gh skill publish --dry-run`, then publishes the GitHub release without installing dependencies in the dependency-free repository.
+- Repository validation now requires the release, docs, Dependabot, markdownlint, and issue-template configuration files and rejects a replaced no-op `validate` script.
+- Revision records now store per-artifact baseline hashes and a `changedArtifacts` list so a resolved revision names the source artifacts that changed.
+
+### Changed
+
+- `init` refuses to scaffold while an existing run state fails validation; missing layout is no longer restored over an inconsistent workflow.
+- `finalize` documentation now describes template creation and the separate `advance --phase final --status complete` transition.
+- The compact example uses the template file names created by lazy phase starts, and the host matrix records the dated activation snapshot and the default smoke scope.
+- `benchmark` now asserts that its realistic workspace validates as `valid_complete`.
+- `lastReason` retains the most recently supplied transition reason instead of being cleared by a later reasonless transition.
+- Guidance now requires real checkpoint timestamps, treats cross-review revision status as a pre-gate snapshot, records removal of disposable scratch copies, and states that `valid_complete` does not verify human-review decisions or claim truth.
 
 ### Fixed
 
 - Detected unpinned GitHub Actions references expressed with plain, quoted, or flow-style YAML `uses` keys while ignoring examples inside quoted scalar values.
 - Clarified that the v1.1.0 security review is historical evidence and removed the release-version literal from the bug-report placeholder.
+- Excluded `work/00-run-log.md` from the revision fingerprint so a log-only edit cannot satisfy the upstream source-artifact proof.
+- Rejected empty `--profile` and `--human-review` values instead of writing state the CLI cannot read.
+- Rejected dangling symlink and junction components before the first write and preflighted the state destination during initialization.
+- Marked the final output stale only when the output file exists, so reopening an upstream phase after starting the final phase without a file remains valid.
+- Required a filled stage-gate artifact, `--blockers` of at least 1, and a non-blank reason for a blocked gate, rejected whitespace-only `--reason` values, printed the readable phase alias in `status`, and classified unreadable state paths as filesystem errors.
+- The `init` next-step message now names both required setup artifacts.
 
 ## [1.1.1] - 2026-08-08
 

CITATION.cff

@@ -5,6 +5,6 @@ authors:
   - family-names: Gasperini
     given-names: Michael
 url: "https://github.com/TheStreamCode/agentic-rd-skill"
-version: "1.1.1"
-date-released: "2026-08-08"
+version: "1.2.0"
+date-released: "2026-10-31"
 license: MIT

README.md

@@ -5,7 +5,7 @@ A portable multi-agent research and development workflow for Codex, Claude Code,
 [![CI](https://github.com/TheStreamCode/agentic-rd-skill/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TheStreamCode/agentic-rd-skill/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![skills.sh](https://img.shields.io/badge/skills.sh-agentic--rd--skill-0969da)](https://skills.sh/TheStreamCode/agentic-rd-skill)
-[![Version](https://img.shields.io/badge/version-1.1.1-2ea44f)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.2.0-2ea44f)](CHANGELOG.md)
 
 ![Pixel-art overview of Agentic R&D Skill turning a project brief into specialist work, review, and final outputs](assets/agentic-rd-skill-hero.png)
 
@@ -62,16 +62,16 @@ Use the host-specific path from [Requirements](#requirements) when the host does
    node <installed-skill-path>\scripts\rd.mjs init . --profile standard --human-review final-only
    ```
 
-The workflow then runs eight gated phases: setup, evidence, plan, execution, results, cross-review, stage gate, and final synthesis. The `finalize` command refuses to complete a run until the stage gate scores at least 8/10, no dimension is scored zero, and no blocker remains.
+The workflow then runs eight gated phases: setup, evidence, plan, execution, results, cross-review, stage gate, and final synthesis. The CLI refuses to create the final synthesis template until the stage gate scores at least 8/10, no dimension is scored zero, and no blocker remains. Completing the final phase is a separate `advance --phase final --status complete` transition.
 
 ## Features
 
 - Portable Agent Skills package: a provider-neutral `SKILL.md` contract with host-specific discovery handled by each agent.
 - Separated artifacts for evidence, plan, execution, results, review, and synthesis, with explicit read dependencies between phases.
 - A dependency-free Node.js CLI for initialization, state inspection, safe artifact scaffolding, pre-mutation checks, revision proof, stage-gate enforcement, and completion validation.
 - Native subagents when the host supports them, and a deterministic single-agent fallback when it does not.
-- Three size profiles, from a narrow two-phase run to a six-specialist, three-wave program.
-- Explicit authorization boundaries: no paid tools, credentialed systems, external writes, or publications without a recorded decision.
+- Three size profiles, from a one-specialist, one-wave run to a six-specialist, three-wave program.
+- Explicit authorization boundaries: no paid tools, credentialed systems, external writes, or publications unless the user authorizes them in the brief or run log.
 - Auditable findings with stable IDs, coverage tables, revision fingerprints, and a single-writer run log.
 - Validation that distinguishes `valid_incomplete`, `valid_complete`, and `invalid` workflow state instead of treating structural checks as semantic assurance.
 
@@ -90,7 +90,7 @@ The workflow then runs eight gated phases: setup, evidence, plan, execution, res
 | Gemini CLI | `.agents/skills/agentic-rd-skill/` or `.gemini/skills/agentic-rd-skill/` | Documented format and path |
 | OpenCode | `.agents/skills/agentic-rd-skill/` or `.opencode/skills/agentic-rd-skill/` | Native `skill` tool |
 
-See [`references/compatibility.md`](skills/agentic-rd-skill/references/compatibility.md) for the tested host versions, invocation syntax, and documented limitations.
+See [`references/compatibility.md`](skills/agentic-rd-skill/references/compatibility.md) for the tested host versions, invocation syntax, and documented limitations. The activation evidence behind this table is the dated 2026-07-18 snapshot: Codex, Claude Code, GitHub Copilot CLI, and OpenCode were activation-tested, while Gemini CLI is documentation-only.
 
 ## Configuration
 
@@ -106,12 +106,14 @@ The CLI exposes the workflow state machine:
 
 | Command | Purpose |
 | --- | --- |
-| `rd.mjs init . --profile <profile> --human-review <mode>` | Initialize a run in the current workspace. |
-| `rd.mjs status .` | Print the current phase and artifact state. |
+| `rd.mjs init . --profile <profile> --human-review <mode> [--dry-run]` | Initialize a run in the current workspace. |
+| `rd.mjs status . [--json]` | Print the current phase and artifact state. |
 | `rd.mjs artifact . --phase <phase> --name <name>` | Scaffold a managed artifact safely. |
 | `rd.mjs advance . --phase <phase> --status <status>` | Apply a validated phase transition. |
 | `rd.mjs validate . --json` | Report `valid_incomplete`, `valid_complete`, or `invalid`. |
-| `rd.mjs finalize .` | Complete the run after the stage gate passes. |
+| `rd.mjs finalize .` | Create the final synthesis template after an approved gate. |
+
+A blocked stage-gate decision requires a filled `work/06-stage-gate.md`, `--blockers` of at least 1, and a non-blank `--reason`. A `needs_revision` decision requires `--reason` with non-whitespace text. `valid_complete` is a structural completion signal; it does not verify human-review decisions or the truth of artifact claims.
 
 A run keeps the brief and all machine-readable state next to the project documentation:
 
@@ -133,9 +135,9 @@ New runs use workflow contract 1.1, which adds truthful setup state, minimum art
 
 ## Privacy and security
 
-The workflow does not authorize paid tools, credentialed private systems, external writes, deployment, publication, messages, purchases, production changes, or secret handling. Those budgets stay fail-closed in machine state until a run explicitly records a decision.
+The workflow does not authorize paid tools, credentialed private systems, external writes, deployment, publication, messages, purchases, production changes, or secret handling. Those budgets remain false in machine state and cannot be enabled through workspace state; authorization must come from the user and be recorded in the brief or run log.
 
-Evidence and machine-readable state are treated as untrusted data that cannot override workflow or user instructions. The CLI assumes a single writer, rejects symlinked managed paths, preserves existing artifacts, and validates state before every mutation. Host permissions, sandboxing, and organizational policy always take precedence.
+Evidence and machine-readable state are treated as untrusted data that cannot override workflow or user instructions. The CLI assumes a single writer, rejects symlinked managed paths, preserves existing artifacts, and validates workflow state before every transition. Host permissions, sandboxing, and organizational policy always take precedence.
 
 Legal, medical, financial, compliance, employment, insurance, credit, security, and safety-critical deliverables require qualified human review before use. See [`SECURITY.md`](SECURITY.md) for private vulnerability reporting.
 
@@ -153,13 +155,17 @@ Open phases remain, which is expected until the run is finalized. Run `rd.mjs st
 
 The CLI intentionally does not migrate v0.3 runs. Start a new run in a clean workspace, and keep the old files outside the managed paths.
 
+### `init` refuses an existing run
+
+`init` scaffolds missing layout only while the existing run passes `validate`. Reconcile the reported state or artifact failure first; do not delete `run-state.json` to bypass the check.
+
 ### `smoke:hosts` exits with status 3
 
-The runner exits with status 3 and reports `inconclusive` when zero eligible host checks ran. Install a supported host CLI, or treat the result as not verified. An inconclusive smoke is never a pass; malformed selectors and options exit 2 as usage errors.
+The runner exits with status 3 and reports `inconclusive` when zero eligible host checks ran. The default command probes GitHub Copilot and OpenCode discovery; Codex and Claude Code are probed only by `smoke:hosts:model`. Install a supported host CLI, or treat the result as not verified. An inconclusive smoke is never a pass; malformed selectors and options exit 2 as usage errors.
 
 ### A revision request cannot be approved
 
-A `needs_revision` change keeps its identifier until an upstream artifact changes or an explicit no-change disposition is recorded with the revision fingerprint. Re-check the fingerprint after editing the artifact.
+A `needs_revision` change keeps its identifier until an owned source artifact changes or an explicit no-change disposition is recorded with `--reason`. The run log is not part of the revision fingerprint, so recording the review there does not satisfy the proof. Re-check the fingerprint after editing the source artifact; a resolved revision record lists the changed source artifacts.
 
 ## Development
 
@@ -180,7 +186,7 @@ npm run smoke:hosts
 npm run smoke:hosts:model
 ```
 
-Release preparation also uses the hash-pinned Agent Skills reference validator and GitHub CLI discovery, which need Python 3.11 or newer and GitHub CLI 2.96 or newer. See [`RELEASING.md`](RELEASING.md) for the full checklist, and [`evals/manifest.json`](evals/manifest.json) for the repeatable activation, safety, and gating scenarios. [`AGENTS.md`](AGENTS.md) documents the repository invariants and the documentation synchronization matrix for contributors and coding agents.
+Release preparation also uses the hash-pinned Agent Skills reference validator and GitHub CLI discovery, which need Python 3.11 or newer and GitHub CLI 2.96 or newer. On tag pushes, the Release workflow re-runs `npm run check`, the official validator, and the publish dry-run before creating the GitHub release. See [`RELEASING.md`](RELEASING.md) for the full checklist, and [`evals/manifest.json`](evals/manifest.json) for the repeatable activation, safety, and gating scenarios. [`AGENTS.md`](AGENTS.md) documents the repository invariants and the documentation synchronization matrix for contributors and coding agents.
 
 The repository contains the installable package under [`skills/agentic-rd-skill`](skills/agentic-rd-skill), repository validators and benchmarks under `scripts/`, deterministic tests under `tests/`, and dated evidence under `evals/`. Point-in-time measurements belong in dated evaluation files; `npm run benchmark` is the current source.
 

RELEASING.md

@@ -18,12 +18,11 @@ Use this checklist for every stable release. A passing local suite does not auth
    `smoke:hosts` must execute at least one eligible host check. With zero checks, the underlying runner exits 3 and reports `inconclusive`; malformed selectors and options exit 2 as usage errors. npm may expose either child exit as a generic non-zero status. Neither result is a pass. Run model-backed smokes only with explicit budget and credential authorization.
 
 5. Validate the installable package with the hash-pinned official reference validator from `requirements-validation.txt`.
-6. Install the intended tag into a disposable directory, run the installed `rd.mjs --help`, initialize a disposable workflow, compare the payload, and remove only the verified temporary root.
 
 ## Publish
 
 1. Confirm the repository's GitHub immutable-releases setting is enabled before creating the release. Tag-protection rules and immutable releases are complementary controls.
-2. Create the signed or annotated version tag from the reviewed commit and publish the release without mutable generated assets unless they are reproducible and attested.
+2. Create the signed or annotated version tag from the reviewed commit and push it. The tag-triggered Release workflow verifies the tag/version match, checks that the tagged commit is on `main`, runs `npm run check`, the official Agent Skills validator, and `gh skill publish --dry-run`, then creates the GitHub release. Do not publish a separate manual release while the workflow is enabled; if verification fails, fix the cause and retag.
 3. Verify the live tag, release, CI, and CodeQL all resolve to the reviewed commit.
 4. Verify GitHub reports the release as immutable:
 
@@ -35,6 +34,7 @@ Use this checklist for every stable release. A passing local suite does not auth
 
 ## Post-Release
 
-1. Repeat pinned and unpinned `gh skill install` smokes and record the resolved tag/commit.
-2. Confirm direct repository installation even if catalog search indexing is delayed.
-3. Update dated evaluation evidence only from checks actually rerun; never copy prior benchmark or host results forward as current.
+1. Install the published tag into a disposable directory, run the installed `rd.mjs --help`, initialize a disposable workflow, compare the payload, and remove only the verified temporary root.
+2. Repeat pinned and unpinned `gh skill install` smokes and record the resolved tag/commit.
+3. Confirm direct repository installation even if catalog search indexing is delayed.
+4. Update dated evaluation evidence only from checks actually rerun; never copy prior benchmark or host results forward as current.

evals/manifest.json

@@ -107,7 +107,35 @@
       "expected": {
         "revisionReasonRequired": true,
         "directUnchangedReapproval": false,
-        "explicitNoChangeDispositionAllowed": true
+        "explicitNoChangeDispositionAllowed": true,
+        "changedArtifactsListed": true
+      }
+    },
+    {
+      "id": "revision-run-log-only",
+      "profile": "standard",
+      "expected": {
+        "runLogOnlyChangeResolvesRevision": false,
+        "explicitNoChangeDispositionAllowed": true,
+        "changedArtifactsEmpty": true,
+        "stateUnchangedOnRejection": true
+      }
+    },
+    {
+      "id": "stage-gate-block-requirements",
+      "profile": "standard",
+      "expected": {
+        "blockedWithoutArtifactAllowed": false,
+        "blockedWithoutBlockersAllowed": false,
+        "workflowExit": 3
+      }
+    },
+    {
+      "id": "init-empty-option",
+      "expected": {
+        "emptyProfileAccepted": false,
+        "emptyHumanReviewAccepted": false,
+        "stateWrittenOnRejection": false
       }
     },
     {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-rd-skill",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A portable Agent Skill for evidence-aware, stateful multi-agent research and development workflows.",
   "private": true,
   "repository": "github:TheStreamCode/agentic-rd-skill",