From 21935038befbc216e9a72287e2426a0bace3b80d Mon Sep 17 00:00:00 2001 From: salimlaimeche Date: Wed, 1 Jul 2026 00:40:47 +0200 Subject: [PATCH] docs: define npm publish automation policy --- docs/ALPHA_READINESS.md | 6 +++-- docs/ALPHA_RELEASE.md | 2 ++ docs/BACKLOG.md | 10 ++++---- docs/CODEX_RUNBOOK.md | 10 ++++++++ docs/NPM_ALPHA_PUBLISHING.md | 44 +++++++++++++++++++++++++++++++++--- docs/PROJECT_AUDIT.md | 1 + 6 files changed, 63 insertions(+), 10 deletions(-) diff --git a/docs/ALPHA_READINESS.md b/docs/ALPHA_READINESS.md index 09c07f0..9c663c5 100644 --- a/docs/ALPHA_READINESS.md +++ b/docs/ALPHA_READINESS.md @@ -38,7 +38,7 @@ All packages declare `license: MIT`, matching the root `LICENSE` file. | `@ignitionai/agent-trainer-rl` | ready | ready | partial | ready | prototype | Deterministic policy helpers, trajectory recorder, fixed-strategy bandits, offline policy evaluation, GRPO-style selection and PPO interface skeletons are tested; deeper RL is intentionally absent. | | `@ignitionai/agent-trainer` | ready | ready | ready | ready | ready | Deterministic recommendation, candidate evaluation and grid search are tested. | -## Verified Through PR #47 +## Verified Through PR #49 - Package names use the `@ignitionai/*` scope. - Root and workspace package versions are aligned on `0.1.0-alpha.0`. @@ -54,12 +54,14 @@ All packages declare `license: MIT`, matching the root `LICENSE` file. - `@ignitionai/agent-trainer-core` has dedicated package-level tests for dataset helpers, adapter helpers and score helpers. - The CLI can record local experiment history, select a baseline and run regression checks. - Ecosystem adapters have a deterministic grouped example covering LangChain, LangGraph, Mastra and Vercel AI SDK-style shapes. +- Core runtime validation helpers cover datasets, variants, run results, usage metrics, traces, metric/reward results, normalized scores and JSON-compatible fields. +- npm alpha publishing policy is manual-only for `v0.1.0-alpha.x`; automated publishing is disabled until a dedicated Trusted Publishing/OIDC PR exists. ## Known Work After Internal Alpha - Dogfood the alpha inside IgnitionRAG and collect trajectory/reward evidence. - Add a lightweight policy optimization loop after real dogfood produces trajectory data. -- Decide any next-step publishing automation policy before a future public release workflow. +- Add a future npm Trusted Publishing/OIDC workflow only if manual alpha consumption proves automation is needed. ## Explicit Non-goals diff --git a/docs/ALPHA_RELEASE.md b/docs/ALPHA_RELEASE.md index f341baf..0048084 100644 --- a/docs/ALPHA_RELEASE.md +++ b/docs/ALPHA_RELEASE.md @@ -4,6 +4,8 @@ This document defines the internal `v0.1.0-alpha.0` tag criteria and release pro The alpha tag is a repository milestone, not an npm publication. +For npm alpha publishing policy, see `docs/NPM_ALPHA_PUBLISHING.md`. Current npm alpha publishing is manual only; no GitHub Actions workflow should publish packages automatically. + ## Target Tag ```txt diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index d47dd21..ef29c1e 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -10,9 +10,9 @@ Status values: Current snapshot: -- Completed through PR #47. -- PR #48 is the current unblocked core validation PR. -- PR #49 and PR #50 are the next planned release-policy and CLI/environment ergonomics PRs. +- Completed through PR #48. +- PR #49 is the current release-policy PR. +- PR #50 is the next planned CLI/environment ergonomics PR. - The dogfood-driven policy optimization loop stays blocked until dogfood or representative trajectory fixtures exist. ## Stable PR sequence @@ -2978,7 +2978,7 @@ Next PR: Status: -- current +- completed Branch: @@ -3041,7 +3041,7 @@ Next PR: Status: -- planned +- current Branch: diff --git a/docs/CODEX_RUNBOOK.md b/docs/CODEX_RUNBOOK.md index bd90e94..1796fba 100644 --- a/docs/CODEX_RUNBOOK.md +++ b/docs/CODEX_RUNBOOK.md @@ -84,6 +84,16 @@ PR #42 packaging readiness PR #42 must not publish to npm during the PR and must not add runtime features. +Current npm alpha publication policy is documented in `docs/NPM_ALPHA_PUBLISHING.md`: + +```txt +manual alpha publish only +no GitHub Actions auto-publish workflow +no long-lived NPM_TOKEN +publish prereleases with --tag alpha +future automation must use npm Trusted Publishing/OIDC and manual approval +``` + After the npm alpha is published, the next phase is dogfooding inside IgnitionRAG: ```txt diff --git a/docs/NPM_ALPHA_PUBLISHING.md b/docs/NPM_ALPHA_PUBLISHING.md index 2863d1d..8a3385e 100644 --- a/docs/NPM_ALPHA_PUBLISHING.md +++ b/docs/NPM_ALPHA_PUBLISHING.md @@ -1,9 +1,45 @@ # npm Alpha Publishing -This document defines the manual npm alpha publishing process for `v0.1.0-alpha.1`. +This document defines the npm alpha publishing policy and manual publishing process for `v0.1.0-alpha.1`. The goal is to validate Ignition Agent Trainer as a real external dependency before dogfooding it inside IgnitionRAG. Do not publish these packages as `latest`. +## Publishing Policy + +Current decision: + +- `v0.1.0-alpha.x` publishing is manual only. +- This repository must not contain a GitHub Actions workflow that can publish to npm automatically. +- Alpha packages must be published with the `alpha` dist-tag. +- Never run `npm publish` without `--tag alpha` for an alpha or prerelease version. +- Do not create or store long-lived `NPM_TOKEN` secrets for this repo. +- Do not use granular access tokens for alpha publication unless a future security review explicitly changes this policy. +- Manual publishers must use an npm account with 2FA enabled and publish interactively with OTP when npm requests it. +- If package-level npm settings are configured after first publish, prefer requiring 2FA for publishing/settings and disallowing token-based publish for the manual-alpha phase. + +Future automation decision: + +- A publish workflow may be added only in a dedicated future PR. +- Any future GitHub Actions publish workflow must use npm Trusted Publishing / OIDC, not long-lived npm tokens. +- Any future publish workflow must use a protected GitHub environment or equivalent manual approval gate. +- Any future prerelease publish workflow must pass `--tag alpha` or another explicit prerelease tag. +- Any future stable publish workflow must be a separate explicit release process and may use `latest` only for a stable version. +- Any future automation PR must include a dry-run or pack verification path and must prove it cannot publish from ordinary pushes. + +Provenance policy: + +- Manual local alpha publishing does not claim CI provenance. +- If npm Trusted Publishing is introduced later, provenance must be enabled through the trusted-publisher flow and verified after publish. +- Do not add `--provenance` to local manual publish commands. + +Official npm references for this policy: + +- [npm publish docs](https://docs.npmjs.com/cli/v11/commands/npm-publish/) document that `npm publish` uses `latest` by default unless `--tag` is provided. +- [npm dist-tag docs](https://docs.npmjs.com/cli/v11/commands/npm-dist-tag/) recommend using tags such as prerelease tags for unstable versions. +- [npm Trusted Publishing docs](https://docs.npmjs.com/trusted-publishers/) describe OIDC-based publishing without long-lived npm tokens. +- [npm provenance docs](https://docs.npmjs.com/generating-provenance-statements/) note that Trusted Publishing generates provenance automatically. +- [npm 2FA docs](https://docs.npmjs.com/configuring-two-factor-authentication/) describe the current 2FA/token requirement for publishing. + ## Package Names The npm alpha uses Agent Trainer-specific package names because `@ignitionai/core` already exists on npm for another IgnitionAI package. @@ -76,6 +112,8 @@ Confirm npm authentication: npm whoami ``` +Use an npm account that belongs to the IgnitionAI npm organization, has publish access to the packages below, and has 2FA enabled. Keep OTP entry interactive unless npm requires `--otp ` for the local environment. + Publish in dependency order: ```bash @@ -91,7 +129,7 @@ cd ../adapter-ignitionrag && npm publish --access public --tag alpha cd ../cli && npm publish --access public --tag alpha ``` -Do not publish with the `latest` dist-tag. +Do not publish with the `latest` dist-tag. The explicit `--tag alpha` flag is mandatory because `npm publish` otherwise updates `latest` by default. ## Post-Publish Verification @@ -131,4 +169,4 @@ bunx --package @ignitionai/agent-trainer-cli@alpha ignition-agent-trainer eval r ## Later Automation -GitHub Actions publishing with npm provenance is intentionally out of scope for `v0.1.0-alpha.1`. Add it only after the manual alpha has been consumed successfully from IgnitionRAG. +GitHub Actions publishing with npm provenance is intentionally disabled for `v0.1.0-alpha.1`. Add it only after the manual alpha has been consumed successfully from IgnitionRAG, and only through a dedicated PR that follows the policy above. diff --git a/docs/PROJECT_AUDIT.md b/docs/PROJECT_AUDIT.md index eabc28d..5cb05bf 100644 --- a/docs/PROJECT_AUDIT.md +++ b/docs/PROJECT_AUDIT.md @@ -253,6 +253,7 @@ If a package exists but is intentionally narrow, minimal or untested, it is part | environment episodes | partial | `packages/environment` | No | Tested episode runner with max-step safety, seed forwarding, final state and metadata. | | trajectory recorder | partial | `packages/rl/src/trajectory.ts` | No | Local state/action/reward/outcome records with deterministic summaries. | | trajectory reports | partial | `packages/rl/src/episode-trajectory.ts` | No | Environment episodes can become trajectories, Markdown reports and offline policy records. | +| npm publishing policy | done | `docs/NPM_ALPHA_PUBLISHING.md` | Yes | Alpha publishing is manual-only with `--tag alpha`; future automation must use Trusted Publishing/OIDC and manual approval. | | bandit prototype | prototype | `packages/rl/src/strategy-bandit.ts` | No | Clearly experimental, fixed arms only, no PPO. | | contextual bandit prototype | prototype | `packages/rl/src/contextual-bandit.ts` | No | Deterministic fixed-feature scoring over task type, citation need, cost sensitivity, latency sensitivity and risk level. | | offline policy evaluation | prototype | `packages/rl/src/offline-policy-evaluation.ts` | No | Deterministic replay over local records or observed trajectory steps; no live traffic path. |