@cleocode/skills 2026.4.4 → 2026.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.4.4",
+  "version": "2026.4.6",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/ct-adr-recorder/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ct-adr-recorder
+description: "Records Architecture Decision Records from accepted consensus verdicts. Use when promoting a consensus outcome to a formal ADR: drafts the document in the proposed-then-accepted HITL lifecycle, links to the originating consensus manifest, persists the decision to the canonical SQLite decisions table, and triggers downstream invalidation when an accepted ADR is later superseded. Triggers on phrases like 'write ADR', 'record architecture decision', 'formalize this decision', 'lock in the choice', 'create ADR-XXX', or when a consensus task reaches completed status and needs formalization."
+---
+
+# ADR Recorder
+
+## Overview
+
+Drafts, persists, and lifecycles Architecture Decision Records (ADRs) derived from accepted consensus verdicts. The skill owns the proposed-then-accepted HITL gate, writes the canonical markdown artifact, inserts the record into the SQLite `decisions` table via Drizzle, and orchestrates downstream invalidation whenever an accepted ADR is later superseded.
+
+## Core Principle
+
+> ADRs capture decisions from consensus verdicts, never from the author's own judgment.
+
+## Immutable Constraints
+
+| ID | Rule | Enforcement |
+|----|------|-------------|
+| ADR-001 | ADR MUST be generated from an accepted consensus report verdict. | `validateArchitectureDecisionProtocol` rejects entries without `consensus_manifest_id`; missing link deducts 25 from score. |
+| ADR-002 | ADR MUST include a `consensus_manifest_id` field linking to the originating consensus. | Manifest entry field is required. |
+| ADR-003 | ADR MUST require explicit HITL approval to transition from `proposed` to `accepted`. | `hitlReviewed: false` with `status: accepted` is rejected; exit code 65 (HANDOFF_REQUIRED). |
+| ADR-004 | ADR MUST include Context, Options Evaluated, Decision, Rationale, and Consequences sections. | Regex check on the ADR body; missing section deducts 20 from score. |
+| ADR-005 | Superseded ADRs MUST trigger downstream invalidation of linked Specifications, Decompositions, and Implementations. | `downstreamFlagged: false` on `status: superseded` fails validation; exit code 18 (CASCADE_FAILED). |
+| ADR-006 | ADR MUST be persisted in the canonical `decisions` SQLite table via Drizzle ORM. | `persistedInDb: false` rejects the manifest entry. |
+| ADR-007 | Manifest entry MUST set `agent_type: "decision"`. | Validator rejects any other value. |
+| ADR-008 | ADR MUST block the Specification stage until status is `accepted`. | Lifecycle state machine refuses to advance past the ADR stage while status is `proposed`. |
+
+## Status Lifecycle
+
+```
+proposed  --HITL review-->  accepted  --supersession-->  superseded
+                               |
+                               +------deprecation------>  deprecated
+```
+
+| Status | Transition From | Required Input | Effect |
+|--------|-----------------|----------------|--------|
+| `proposed` | (initial draft) | Consensus manifest id | Pipeline pauses; exit 65 HANDOFF_REQUIRED |
+| `accepted` | `proposed` | Human review signal | Unblocks Specification stage |
+| `superseded` | `accepted` | New ADR id | Fires downstream cascade (see references/cascade.md) |
+| `deprecated` | `accepted` | Deprecation reason | Removed from canon without replacement |
+
+The `proposed -> accepted` edge is the only HITL gate in the pipeline. A human reviewer MUST explicitly sign off; auto-promotion is forbidden.
+
+## ADR Document Structure
+
+Every ADR markdown artifact MUST carry frontmatter plus six canonical sections. Keep sections 1-5 concise; prose belongs in the downstream spec, not the ADR.
+
+```markdown
+---
+id: ADR-0042
+title: "Adopt Drizzle ORM v1 beta for all SQLite access"
+status: proposed
+date: 2026-04-06
+consensus_manifest_id: CONS-2026-04-06-0017
+supersedes: []
+superseded_by: []
+---
+
+# ADR-0042: Adopt Drizzle ORM v1 beta for all SQLite access
+
+## 1. Context and Problem Statement
+Better-sqlite3 and raw drizzle 0.x diverge on schema introspection and block
+forward migration of the `decisions` table.
+
+## 2. Options Evaluated
+* Option A: Stay on drizzle 0.29 and backport fixes.
+* Option B: Move to drizzle 1.0.0-beta and accept API churn.
+* Option C: Drop Drizzle, switch to Kysely.
+
+## 3. Decision
+Adopt drizzle-orm@1.0.0-beta project-wide; pin to a single beta tag.
+
+## 4. Rationale
+Derived from CONS-2026-04-06-0017 (verdict PROVEN, 0.82 confidence).
+Option B preserves relational queries and unblocks the migration epic.
+
+## 5. Consequences
+### Positive
+* Single ORM path; no downgrades.
+### Negative
+* API churn in each beta; pin required per release.
+
+## 6. Downstream Impact (Traceability)
+Flags specs T4776, T4781; decomposition epic T4772; live impl T4790.
+```
+
+A longer, realistic example with all six sections filled out lives in [references/examples.md](references/examples.md).
+
+## HITL Approval Gate
+
+When a draft reaches `proposed`, the skill MUST:
+
+1. Write the markdown artifact to disk.
+2. Record the manifest entry with `status: proposed` and `agent_type: "decision"`.
+3. Exit with code 65 (`HANDOFF_REQUIRED`).
+4. Leave the pipeline paused until a human reviewer runs the approval path.
+
+The agent MUST NOT:
+
+- Promote a `proposed` ADR to `accepted` on its own.
+- Retry the transition on a loop after exit 65.
+- Edit the ADR body after exit 65 (any revision starts a new `proposed` cycle).
+
+The human reviewer is expected to:
+
+1. Read the markdown and the linked consensus manifest.
+2. Confirm that every option from the consensus verdict appears in section 2.
+3. Sign off by moving the status to `accepted` through the CLI and re-running validation with `hitlReviewed: true`.
+
+## Downstream Cascade (on supersession)
+
+When an accepted ADR is later superseded, the skill MUST:
+
+1. Query the `decision_evidence` relation for every specification, decomposition, and implementation that cited the old ADR.
+2. Flag each linked artifact as `needs-review`.
+3. Suspend any active implementation or contribution task tied to the old ADR.
+4. Record the cascade in the new ADR's manifest entry.
+
+A missing cascade fails validation with exit code 18 (`CASCADE_FAILED`). The full flow, including the `decision_evidence` query and the manifest fields to populate, is documented in [references/cascade.md](references/cascade.md).
+
+## Integration
+
+Validate every ADR manifest entry through `cleo check protocol`:
+
+```bash
+# Draft reaches proposed: runs inside the skill, before HITL hand-off.
+cleo check protocol \
+  --protocolType architecture-decision \
+  --taskId T4798 \
+  --status proposed \
+  --persistedInDb true \
+  --adrContent "$(cat docs/adr/ADR-0042.md)"
+
+# HITL accepts the ADR: rerun with the review flag.
+cleo check protocol \
+  --protocolType architecture-decision \
+  --taskId T4798 \
+  --status accepted \
+  --hitlReviewed true \
+  --persistedInDb true
+
+# Later supersession: include the cascade flag.
+cleo check protocol \
+  --protocolType architecture-decision \
+  --taskId T4798 \
+  --status superseded \
+  --downstreamFlagged true
+```
+
+Exit code 0 = valid. Exit code 65 = `HANDOFF_REQUIRED`. Exit code 18 = `CASCADE_FAILED`. Exit code 84 = `PROVENANCE_REQUIRED` (attempted ADR without a linked consensus).
+
+## Anti-Patterns
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Drafting an ADR without a consensus verdict | Violates ADR-001; decision lacks evidence base | Run the consensus skill first; copy the manifest id into the ADR frontmatter |
+| Auto-promoting `proposed` to `accepted` | Bypasses the HITL gate (ADR-003) | Stop at exit 65 and wait for the human reviewer |
+| Persisting only the markdown, skipping SQLite | Violates ADR-006; loses relational queries | Insert via the `architectureDecisions` Drizzle table before exiting the skill |
+| Omitting the Downstream Impact section | Future implementers can't find cascade targets (ADR-005) | Populate section 6 with every touched spec/epic/impl |
+| Using the ADR to list implementation requirements | Blurs the ADR/spec boundary | Keep the ADR decision-only; push requirements to the specification stage |
+| Superseding without running the cascade | Violates ADR-005; breaks the evidence chain | Query `decision_evidence`, flag artifacts, record the cascade in the new ADR |
+| Editing an accepted ADR in-place | Breaks immutability and audit trail | Create a new ADR that supersedes the old one |
+
+## Critical Rules Summary
+
+1. ADRs MUST be drafted from an accepted consensus verdict, with `consensus_manifest_id` populated.
+2. The `proposed -> accepted` transition MUST pass through a HITL review; agents stop at exit 65.
+3. The ADR body MUST contain all five canonical sections (Context, Options, Decision, Rationale, Consequences).
+4. The decision MUST be inserted into the canonical `decisions` SQLite table via Drizzle.
+5. The manifest entry MUST set `agent_type: "decision"` and reference the output markdown file.
+6. Superseding an accepted ADR MUST trigger the downstream cascade over linked specs, decomps, and impls.
+7. Agents MUST NOT retry the HITL handoff on a loop; wait for the human reviewer.
+8. Always validate via `cleo check protocol --protocolType architecture-decision` before exiting.

package/skills/ct-adr-recorder/manifest-entry.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "CLEO-only metadata -- add to packages/skills/skills/manifest.json",
+  "name": "ct-adr-recorder",
+  "version": "1.0.0",
+  "tier": 2,
+  "token_budget": 8000,
+  "protocol": "architecture-decision",
+  "capabilities": {
+    "inputs": ["consensus-manifest-id", "task-id", "decision-context"],
+    "outputs": ["adr-markdown", "decisions-table-row", "manifest-entry"],
+    "dispatch_triggers": [
+      "write ADR",
+      "record architecture decision",
+      "formalize this decision",
+      "create ADR",
+      "lock in the choice"
+    ],
+    "compatible_subagent_types": ["general-purpose"],
+    "chains_to": ["ct-consensus-voter", "ct-spec-writer"],
+    "dispatch_keywords": {
+      "primary": ["adr", "decision", "architecture", "formalize"],
+      "secondary": ["proposed", "accepted", "superseded", "hitl"]
+    }
+  },
+  "constraints": {
+    "max_context_tokens": 60000,
+    "requires_session": false,
+    "requires_epic": false
+  }
+}

package/skills/ct-adr-recorder/references/cascade.md

@@ -0,0 +1,82 @@
+# Downstream Cascade Flow
+
+When an `accepted` ADR is superseded, the cascade skill MUST reach every artifact that cites the old decision and flag it for review. This is the mechanism enforced by ADR-005.
+
+## Cascade Trigger
+
+The cascade fires on exactly one transition:
+
+```
+accepted --> superseded
+```
+
+No other transition (deprecation, rewrite, revision) runs the cascade. Deprecation marks the ADR stale without replacing it and does not invalidate downstream work.
+
+## Query Model
+
+The canonical source of linkage is the `decision_evidence` relation in the SQLite schema. Every downstream artifact that relied on an ADR MUST have inserted a row at the time it was created.
+
+```sql
+SELECT artifact_type, artifact_id, cited_section, cited_at
+FROM decision_evidence
+WHERE decision_id = :old_adr_id
+  AND superseded_at IS NULL;
+```
+
+| Column | Meaning |
+|--------|---------|
+| `artifact_type` | `specification` / `decomposition` / `implementation` / `contribution` |
+| `artifact_id` | Task id (`T####`) or spec id |
+| `cited_section` | Which section of the ADR the artifact depended on |
+| `cited_at` | Timestamp of the link |
+| `superseded_at` | Set by the cascade when this row is flagged |
+
+## Cascade Steps
+
+1. **Query**: Run the query above. If the result set is empty, record `cascadeTargets: []` in the new ADR and continue — no downstream work exists.
+2. **Classify**: Group rows by `artifact_type`. Specifications and decompositions get flagged `needs-review`. Implementations and contributions get suspended if currently active.
+3. **Flag**: For each target, write the `needs-review` status to the task record and log the cascade manifest id.
+4. **Suspend**: Any `active` implementation task MUST move to `blocked` with blocker `adr-superseded`. Active contribution records MUST attach a `contested` note citing the new ADR.
+5. **Update** `decision_evidence`: Set `superseded_at = now()` on every flagged row.
+6. **Record** in the new ADR's manifest entry:
+
+```json
+{
+  "agent_type": "decision",
+  "status": "accepted",
+  "consensus_manifest_id": "CONS-2026-04-10-0021",
+  "supersedes": ["ADR-0042"],
+  "cascadeTargets": [
+    {"artifact_type": "specification", "artifact_id": "T4776", "action": "flagged"},
+    {"artifact_type": "implementation", "artifact_id": "T4790", "action": "suspended"}
+  ]
+}
+```
+
+## Cascade Failures
+
+Exit code 18 (`CASCADE_FAILED`) fires when any of the following occur:
+
+| Failure | Remediation |
+|---------|-------------|
+| Query returns rows but `cascadeTargets` is empty in the manifest | Populate `cascadeTargets` and rerun validation |
+| A downstream task refuses the status transition | Inspect task state; resolve manually before retrying |
+| `decision_evidence.superseded_at` could not be written | Check Drizzle transaction; do not split into partial writes |
+| The new ADR does not list the old ADR in `supersedes[]` | Add the reference and rerun |
+
+The cascade is a single atomic step from the lifecycle's point of view: either every downstream artifact is flagged or the supersession is rejected. Partial cascades are never acceptable.
+
+## Suspension and Resume
+
+A suspended implementation task stays blocked until:
+
+1. The spec that cited the old ADR is updated against the new ADR.
+2. The decomposition epic is re-planned.
+3. The implementation is re-attached to the new ADR via a fresh `decision_evidence` row.
+4. A human reviewer signs off the unblock.
+
+The skill does not auto-resume suspended work. That is deliberately out of scope — reconciliation is the Specification and Decomposition stages' job.
+
+## Relation to the HITL Gate
+
+The supersession path does not go through the HITL gate at the `superseded` transition. HITL review happened once, when the new ADR was promoted from `proposed` to `accepted`. That review MUST have examined the cascade plan; the cascade itself is mechanical and runs without a second human pause.

package/skills/ct-adr-recorder/references/examples.md

@@ -0,0 +1,141 @@
+# ADR Examples
+
+Full, realistic ADR artifact. Use as a copy-paste starting point; replace every field before committing.
+
+## Example: ADR-0042 (Adopt Drizzle ORM v1 beta)
+
+```markdown
+---
+id: ADR-0042
+title: "Adopt Drizzle ORM v1 beta for all SQLite access"
+status: proposed
+date: 2026-04-06
+consensus_manifest_id: CONS-2026-04-06-0017
+supersedes: []
+superseded_by: []
+---
+
+# ADR-0042: Adopt Drizzle ORM v1 beta for all SQLite access
+
+## 1. Context and Problem Statement
+
+The CLEO monorepo currently pins `drizzle-orm@0.29.x`. That line diverges from
+the v1 beta schema introspection model and no longer supports the `defineRelations`
+primitive we need for the `decision_evidence` cascade query. Backporting patches
+is feasible but compounds tech debt for every new migration. The consensus skill
+(T4797) produced a PROVEN verdict at 0.82 confidence recommending immediate
+migration to the v1 beta line.
+
+## 2. Options Evaluated
+
+The consensus skill evaluated three options:
+
+* **Option A**: Stay on `drizzle-orm@0.29` and backport v1 schema fixes into a
+  fork. Low risk in the short term; high tech debt curve.
+* **Option B**: Move the project to `drizzle-orm@1.0.0-beta` pinned to a single
+  beta tag per release, accept API churn, migrate one package per wave.
+* **Option C**: Drop Drizzle entirely and move all SQLite access to Kysely.
+  Cleanest long-term abstraction but invalidates the entire migrations
+  directory and loses eight months of tooling.
+
+## 3. Decision
+
+Adopt `drizzle-orm@1.0.0-beta` across every package that touches SQLite. Each
+release pins exactly one beta tag. Rollbacks happen per package, never per
+release.
+
+## 4. Rationale
+
+Derived from CONS-2026-04-06-0017 (verdict PROVEN, 0.82 confidence). Three
+agents voted Option B with high confidence, one voted Option A, none voted
+Option C. The deciding evidence was the `defineRelations` primitive's ability
+to express the `decision_evidence` cascade in a single declarative pass, which
+the 0.29 line cannot do. The dissenting Option-A vote flagged API churn risk,
+which is mitigated by the per-release pin in the Decision section.
+
+## 5. Consequences
+
+### Positive
+
+* Single ORM path across the monorepo; no per-package downgrades.
+* `defineRelations` unblocks the cascade query this ADR depends on.
+* Migrations directory stays canonical.
+
+### Negative
+
+* Every beta release requires a compatibility review before pin bump.
+* Type surface changes per beta; downstream packages must rebuild.
+* No long-term stability guarantee from upstream until the beta closes.
+
+## 6. Downstream Impact (Traceability)
+
+The following artifacts are flagged as directly dependent on this ADR and MUST
+be updated or re-validated when the decision lands:
+
+| Artifact | Type | Reason |
+|----------|------|--------|
+| T4776 | specification | Defines the `decisions` table schema; must adopt v1 primitives |
+| T4781 | specification | Defines the `decision_evidence` relation |
+| T4772 | decomposition | Epic that owns the migration waves |
+| T4790 | implementation | Live work on the decisions migration path |
+
+Rejected alternatives remain in the manifest for institutional memory but MUST
+NOT be cited by any downstream artifact.
+```
+
+## Example: ADR-0043 (Deprecate ADR-0042)
+
+A deprecation ADR removes a decision from canon without replacing it. No downstream cascade runs; the `decision_evidence` rows stay live because nothing supersedes them.
+
+```markdown
+---
+id: ADR-0043
+title: "Deprecate Drizzle v1 adoption decision"
+status: deprecated
+date: 2026-05-12
+consensus_manifest_id: CONS-2026-05-12-0003
+supersedes: []
+superseded_by: []
+---
+
+# ADR-0043: Deprecate Drizzle v1 adoption decision
+
+## 1. Context and Problem Statement
+
+Upstream has frozen the v1 beta line without a GA date. The migration planned
+in ADR-0042 is paused pending a new decision path.
+
+## 2. Options Evaluated
+
+* Option A: Supersede ADR-0042 with a new ORM choice.
+* Option B: Deprecate ADR-0042 without replacement and defer the decision.
+
+## 3. Decision
+
+Deprecate ADR-0042 without replacement. Downstream specs remain stable; no
+cascade fires.
+
+## 4. Rationale
+
+Derived from CONS-2026-05-12-0003. No replacement is ready; forcing a
+supersession would produce a contested cascade.
+
+## 5. Consequences
+
+### Positive
+* Downstream work on v0.29 is not invalidated.
+
+### Negative
+* `defineRelations` work stays blocked until a future ADR is authored.
+
+## 6. Downstream Impact (Traceability)
+
+None. Deprecation is a canon-only operation.
+```
+
+## Things to Notice
+
+- Frontmatter `supersedes` and `superseded_by` are always arrays, even when empty.
+- The `consensus_manifest_id` in the frontmatter MUST match the id in the manifest entry; the validator cross-checks.
+- Section 6 is the only section that links to tasks by id. Sections 1-5 stay prose-only.
+- Rejected alternatives live in section 2, not in a separate "rejected" section, so they travel with the options list forever.

package/skills/ct-artifact-publisher/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: ct-artifact-publisher
+description: "Builds and publishes artifacts to registries (npm, PyPI, cargo, docker, GitHub releases, generic tarballs) following the validate, then dry-run, then build, then publish, then record-provenance pipeline. Invoked by ct-release-orchestrator as a sub-skill when a release has artifact config. Never stores credentials in output or manifest (ARTP-008), always dry-runs first (ARTP-002), halts and attempts rollback on failure (ARTP-009). Triggers when a release config has at least one enabled artifact handler."
+---
+
+# Artifact Publisher
+
+## Overview
+
+Sub-protocol of ct-release-orchestrator. Runs the build-then-publish pipeline for every enabled artifact in `release.artifacts[]`: pre-validates the config, dry-runs each build, produces SHA-256 checksums, publishes sequentially, and delegates signing plus attestation to ct-provenance-keeper. Handles nine artifact types via a uniform handler interface.
+
+## Core Principle
+
+> Every artifact gets a checksum, a dry-run, and a rollback plan.
+
+## Immutable Constraints
+
+| ID | Rule | Enforcement |
+|----|------|-------------|
+| ARTP-001 | Artifact config MUST be validated before build. | `validate_artifact()` must return 0 before `build_artifact()` runs; exit 86. |
+| ARTP-002 | Dry-run MUST execute before any real publish. | Pipeline halts if dry-run fails; exit 86. |
+| ARTP-003 | Every handler MUST implement `{prefix}_validate`, `{prefix}_build`, `{prefix}_publish`. | Missing handler function exits 85. |
+| ARTP-004 | SHA-256 checksums MUST be generated for every built artifact. | Missing checksum blocks publish. |
+| ARTP-005 | Provenance metadata MUST be recorded via `record_release()` after publish. | Composition handoff to ct-provenance-keeper. |
+| ARTP-006 | Multi-artifact publish MUST execute sequentially. | No parallel publishes; prevents race conditions. |
+| ARTP-007 | Manifest entry MUST set `agent_type: "artifact-publish"`. | Validator rejects any other value. |
+| ARTP-008 | Credentials MUST NOT appear in config, output, or manifest. | Agents declare env vars by name only; actual values stay in the environment. |
+| ARTP-009 | Pipeline MUST halt and attempt rollback on the first publish failure. | Exit 88 on rollback success, exit 89 on rollback failure. |
+
+## Supported Artifact Types
+
+Nine registered handler types cover the common publishing surface. Each has a default build and publish command that the handler can override via config.
+
+| Type | Build command (default) | Publish command (default) | Registry |
+|------|-------------------------|---------------------------|----------|
+| `npm-package` | (none, `npm publish` reads `files`) | `npm publish` | npmjs.org |
+| `python-wheel` | `python -m build` | `twine upload dist/*` | pypi.org |
+| `python-sdist` | `python -m build --sdist` | `twine upload dist/*` | pypi.org |
+| `go-module` | `go mod tidy` | (tag push triggers proxy) | proxy.golang.org |
+| `cargo-crate` | `cargo build --release` | `cargo publish` | crates.io |
+| `ruby-gem` | `gem build *.gemspec` | `gem push *.gem` | rubygems.org |
+| `docker-image` | `docker build -t <ref> .` | `docker push <ref>` | configurable (OCI) |
+| `github-release` | (none) | `gh release create` | github.com |
+| `generic-tarball` | `tar czf ...` | (custom) | configurable |
+
+Per-type edge cases and exact invocation patterns live in [references/artifact-types.md](references/artifact-types.md).
+
+## Handler Interface
+
+Every handler is three Bash functions with a uniform contract:
+
+```bash
+# Validate config, check tool availability, verify version consistency.
+{prefix}_validate(artifact_config_json) -> exit 0 | 1
+
+# Produce build output in a known location. Respects dry_run.
+{prefix}_build(artifact_config_json, dry_run) -> exit 0 | 1
+
+# Push build output to the registry. Respects dry_run.
+{prefix}_publish(artifact_config_json, dry_run) -> exit 0 | 1
+```
+
+A full pseudocode example for a custom handler is in [references/handler-interface.md](references/handler-interface.md). To register a new handler:
+
+```bash
+source lib/release-artifacts.sh
+register_artifact_handler "my-custom-type" "my_custom"
+```
+
+## Pipeline Phases
+
+The sub-protocol runs in three ordered phases:
+
+| Phase | Scope | Halt condition |
+|-------|-------|----------------|
+| 1. Pre-validate | All artifacts | Halt before any build |
+| 2. Build | Sequential per artifact | Halt pipeline |
+| 3. Publish | Sequential per artifact | Rollback published artifacts, then halt |
+
+Sequential order matters: if artifact 1 (npm) publishes successfully but artifact 2 (docker) fails, the pipeline rolls back artifact 1 using `npm unpublish` (within 72 hours) before exiting. Rollback feasibility varies by registry — see composition.md in ct-release-orchestrator for the full table.
+
+## Credentials Handling
+
+Credentials are referenced, never stored. The skill reads environment variables by name from the config and verifies they are set before publishing:
+
+```json
+{
+  "credentials": {
+    "envVar": "NPM_TOKEN",
+    "ciSecret": "NPM_TOKEN",
+    "required": true
+  }
+}
+```
+
+The skill MUST NOT:
+
+- Echo or log credential values.
+- Write credential values to `config.json` or the manifest entry.
+- Pass credentials as CLI arguments (visible in `ps`).
+- Include credential values in output files.
+
+In CI, trusted publishing is preferred: the workflow exchanges an OIDC token for a short-lived registry credential, and the skill never sees the token. The CI path is already configured in `.github/workflows/release.yml` for npm.
+
+Missing credentials exit 90 (`E_PROVENANCE_CONFIG_INVALID` bubbled from provenance) or fail the credential check with a clear error pointing at the missing env var.
+
+## Integration
+
+Validate the sub-protocol entry through `cleo check protocol`:
+
+```bash
+cleo check protocol \
+  --protocolType artifact-publish \
+  --taskId T4901 \
+  --artifactType npm-package \
+  --buildPassed true
+```
+
+Exit code 0 = artifact published successfully. Exit code 85 = unknown artifact type. Exit code 86 = validation failed. Exit code 87 = build failed. Exit code 88 = publish failed, rollback attempted. Exit code 89 = rollback failed, dirty state.
+
+This skill always hands off to ct-provenance-keeper after publish, before writing the manifest entry, so the provenance chain is recorded in the same pipeline.
+
+## Anti-Patterns
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Publishing without a dry-run first | Irreversible registry state on failure | ARTP-002 requires dry-run; the skill refuses to skip it |
+| Storing credentials in `config.json` | Committed to VCS, visible to every agent | Reference by env var name; actual values stay in the environment |
+| Parallel multi-artifact publish | Race conditions; partial state on failure | Sequential execution in config order (ARTP-006) |
+| Skipping checksum generation | Cannot verify artifact integrity downstream | Generate SHA-256 for every build output |
+| Logging credential values | Exposure in audit trail and agent context | Never echo credentials; test only the env var is set, not its value |
+| Hardcoding registry URLs | Breaks across environments | Use the `registry` field in the config |
+| Manual rollback without recording | Lost provenance chain | Record rollback in the manifest and the `releases.json` chain |
+| Building before validating | Wastes time on invalid config | Pre-validate every artifact before the first build |
+| Ignoring rollback failures | Leaves the pipeline in dirty state | Exit 89 and require manual intervention — do not retry blindly |
+
+## Critical Rules Summary
+
+1. Every artifact MUST be pre-validated before any build starts.
+2. Every publish MUST be preceded by a successful dry-run.
+3. Credentials MUST NEVER leave the environment — no logging, no config, no manifest.
+4. Publishes run sequentially in config order; no parallel publishes.
+5. SHA-256 checksums are mandatory for every build output.
+6. Provenance MUST be recorded via `record_release()` after publish, via ct-provenance-keeper.
+7. On first publish failure, halt and attempt rollback; exit 88 on clean rollback, 89 on dirty.
+8. Validate every run via `cleo check protocol --protocolType artifact-publish`.

package/skills/ct-artifact-publisher/manifest-entry.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "CLEO-only metadata -- add to packages/skills/skills/manifest.json",
+  "name": "ct-artifact-publisher",
+  "version": "1.0.0",
+  "tier": 2,
+  "token_budget": 8000,
+  "protocol": "artifact-publish",
+  "capabilities": {
+    "inputs": ["release-config", "version", "commit-sha"],
+    "outputs": ["built-artifacts", "checksums", "publish-results", "manifest-entry"],
+    "dispatch_triggers": [
+      "publish artifacts",
+      "build and publish",
+      "run artifact publish",
+      "ship packages",
+      "push to registry"
+    ],
+    "compatible_subagent_types": ["general-purpose"],
+    "chains_to": ["ct-provenance-keeper"],
+    "dispatch_keywords": {
+      "primary": ["artifact", "publish", "registry", "package"],
+      "secondary": ["npm", "docker", "cargo", "tarball"]
+    }
+  },
+  "constraints": {
+    "max_context_tokens": 60000,
+    "requires_session": false,
+    "requires_epic": false
+  }
+}