@manhquy/flow-skill 0.1.0-rc.2 → 0.1.0-rc.3

package/CHANGELOG.md

@@ -2,7 +2,30 @@
 
 All notable changes to `@manhquy/flow-skill`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
-## [0.1.0-rc.2] — 2026-07-17 (not yet published — see release command below)
+## [0.1.0-rc.3] — 2026-07-18
+
+Ships the same skill product **v0.22.0** as rc.2, plus pipeline/UX fixes found after the first
+OIDC publish + independent verification.
+
+### Fixed
+- **Nightly registry health false-red:** `scripts/smoke.mjs` ran `npx` from inside
+  `npm-wrapper/`, so npx resolved the **local workspace package** instead of the registry
+  (`flow-skill: not found`) even when the published package was healthy. Smoke now uses an
+  empty temp cwd + `npx --package=… flow-skill`; nightly runs from `$RUNNER_TEMP`.
+- **CI bash-suite Windows cancelled at 15m:** full 33-suite run needs ~20–25m on Windows Git
+  Bash (measured run `29630992330` — mid-`test_flow_eval` when cut). `timeout-minutes` is now
+  **30 on windows-latest**, 15 elsewhere. `tests/run_all.sh` prints per-suite `wall_s`.
+- **`promote_to`:** early-exit before install/test (no full job burn); input description states
+  it is **manual-only** (OIDC cannot `npm dist-tag add` — E401 on run `29556075144`).
+
+### Added
+- Dual-version UX: `--help` shows `flow-skill v<pkg> (ships skill v<skill>)`; JSONL `plan`
+  event gains additive `skillVersion`. Unit tests pin values from `package.json` + `SKILL.md`.
+
+### Changed
+- `bin/cli.mjs` git mode `100755` (executable bit in tarball).
+
+## [0.1.0-rc.2] — 2026-07-17 — LIVE (published 2026-07-17, `latest` + `rc` both point here)
 
 Ships `skills/flow` v0.22.0 (concierge front-door + standalone native rituals — see the root
 repo's CHANGELOG.md `## 0.22.0` entry for the full skill-content changelog). This wrapper
@@ -68,10 +91,38 @@ two hardening items found while verifying it all.
   both `install.sh` and `install.ps1` carry the Antigravity restart/reload hint, and the old
   hardcoded Claude+Codex-only Done line is gone from both.
 
-### Release command (operator-gated — not run by this change)
+### Fixed — CI publish guard (found on the actual first real run of this workflow)
+- `publish-npm-wrapper.yml`'s `Guard — assert no NODE_AUTH_TOKEN present (OIDC only)` step
+  **hard-failed every run, including this release's first attempt** (run `29554226397`,
+  2026-07-17). Root-caused via a temporary diagnostic step (added, run 3×, removed same
+  session): `NODE_AUTH_TOKEN` is unset right after `actions/checkout@v4` but becomes a real
+  short-lived OIDC-exchanged value the instant `actions/setup-node@v4` runs with
+  `registry-url` set — that's the current `actions/setup-node@v4` (a moving tag) doing its own
+  native npm OIDC handling, not a leaked static secret. The guard's 2026-07-12 design assumed
+  the older model where `npm publish` alone performed the OIDC exchange with nothing set
+  beforehand; it never matched real `actions/setup-node@v4` behavior and had a 0% pass rate
+  since the day it was written. **Removed** — see the workflow file's inline comment for the
+  full evidence chain.
+- **npm Trusted Publisher was never actually bound** on npmjs.com for this package (confirmed:
+  first real publish attempt after the guard fix still 404'd — `PUT
+  .../@manhquy%2fflow-skill — Not found`). The 2026-07-12 runbook flagged this config as `TBD`
+  and it was never closed out. Configured now: `owner=manhquydev`, `repo=flow-skill`,
+  `workflow=publish-npm-wrapper.yml`, `environment=npm-publish`. `npm publish --provenance`
+  now succeeds via pure OIDC — confirmed live, SLSA attestation present.
+- **`npm dist-tag add` does NOT work via OIDC** (confirmed live: `E401 Unable to authenticate`
+  even immediately after a successful OIDC-authenticated publish in the same job). npm has not
+  extended Trusted Publishing to this endpoint yet (matches
+  `plans/reports/researcher-260712-1006-npm-trusted-publisher-first-publish-edge-cases-report.md`
+  item #12, "OIDC support in development", no ship date). Promoting `0.1.0-rc.2` to `latest`
+  required the same manual Granular-Access-Token-with-Bypass-2FA flow used for the rc.1
+  bootstrap publish — see `RELEASE_CHECKLIST.md` for the exact steps and why this account
+  (created 2026-07-11, after npm's Sept-2025 TOTP-enrollment cutoff) has no other CLI-auth path
+  for write operations.
+
+### Release command (already run for this release)
 ```
-cd npm-wrapper && npm test   # confirm green first
-git tag npm@0.1.0-rc.2 && git push --tags   # triggers .github/workflows/publish-npm-wrapper.yml
+cd npm-wrapper && npm test   # confirmed green first
+git tag npm@0.1.0-rc.2 && git push origin npm@0.1.0-rc.2   # triggered the workflow (after the guard fix + TP config above)
 ```
 
 ## [0.1.0-rc.1] — 2026-07-12

package/README.md

@@ -10,13 +10,21 @@ One-command installer that copies the [flow](https://github.com/manhquydev/flow-
 ## Install
 
 ```
-# Pre-release channel (current — v0.1.0-rc.2)
+# Pre-release channel (current — v0.1.0-rc.3, ships skill v0.22.0)
 npx @manhquy/flow-skill@rc
 ```
 
 An interactive prompt asks which agents to install to. Pick one or more, confirm, done.
 
-> **RC phase**: pin `@rc` (dist-tag) or a specific version like `@0.1.0-rc.2`. `npx @manhquy/flow-skill@0.1.x` will start working after stable `0.1.0` is published — semver ranges do **not** match pre-release tuples by default. See [SECURITY.md](./SECURITY.md).
+> **RC phase**: pin `@rc` (dist-tag) or a specific version like `@0.1.0-rc.3`. `npx @manhquy/flow-skill@0.1.x` will start working after stable `0.1.0` is published — semver ranges do **not** match pre-release tuples by default. See [SECURITY.md](./SECURITY.md).
+>
+> **`npm i` alone is not enough.** `npm install @manhquy/flow-skill` only adds the installer
+> package to `node_modules`. You must **run** it (`npx @manhquy/flow-skill@rc` or
+> `npx flow-skill` after install) to copy the skill into agent homes.
+>
+> **Two version axes:** package `version` in this folder is the **installer** (e.g. `0.1.0-rc.3`).
+> Skill product version lives in `skills/flow/SKILL.md` (`metadata.version`, e.g. `0.22.0`).
+> `--help` and the JSONL `plan` event expose both (`version` + `skillVersion`).
 
 ## Non-interactive
 
@@ -58,7 +66,7 @@ line tells you exactly what to do for whichever targets you installed:
 - Claude Code: type `/flow`.
 - Codex CLI: type `$flow` (restart Codex once to load a new skill).
 - Antigravity: restart/reload the IDE (or restart `agy`) to load the new skill, then type `/flow`.
-- Agents home: restart/reload your tool if it does not auto-detect new skills.
+- Agents home (`~/.agents/skills/`): restart/reload your tool if it does not auto-detect new skills.
 - Cursor: **install verified, live runner execution not yet independently confirmed** — Cursor
   has no headless CLI probe available for automated verification (unlike Antigravity's `agy -p`
   or Codex's `codex exec`); restart/reload Cursor after install and check the Agent panel for
@@ -86,6 +94,8 @@ rm -rf <project>/.claude/skills/flow
 - **Windows `EBUSY` / `EPERM` mid-install**: an agent (Claude Code, Codex, Antigravity IDE) is holding a file inside the destination. Close the agent and re-run. The installer already retries with 100/300/900 ms backoff before surfacing the error.
 - **Stale advisory lock**: a prior run crashed. The next run detects the dead PID and reclaims the lock automatically. If it does not (very rare — the recorded PID was recycled by another live process), delete `<parent-of-dest>/.flow-skill.installing.lock`.
 - **`No matching version found` on `@0.1.x`**: you are trying to install a pre-release version through a stable range. Use `@rc` (dist-tag) or an explicit `@0.1.0-rc.N` until stable `0.1.0` ships.
+- **`No matching version found` on `@0.22.0`**: that is the **skill product** version, not the npm package version. Use `@rc` / `@0.1.0-rc.N` (installer) — skill content version is printed by `--help` as `ships skill v…`.
+- **Installed package but agent has no `/flow`**: `npm i` does not run the installer. Run `npx @manhquy/flow-skill@rc` (or `npx flow-skill` if already installed) and restart the agent.
 - **Node too old** (`requires Node.js >=22.14.0`): upgrade with your preferred version manager (`nvm install 22`, `fnm install 22`, or Node's official installer). Node 20 reached end-of-life April 2026; npm OIDC Trusted Publishing needs npm >=11.5.1 which bundles with Node 22.14+.
 
 ## JSONL contract
@@ -93,7 +103,7 @@ rm -rf <project>/.claude/skills/flow
 `--json` streams one JSON object per line:
 
 ```jsonl
-{"event":"plan","version":"0.1.0-rc.1","dryRun":false,"scope":"global","targets":["claude","codex"]}
+{"event":"plan","version":"0.1.0-rc.3","skillVersion":"0.22.0","dryRun":false,"scope":"global","targets":["claude","codex"]}
 {"event":"install:start","target":"claude","dests":["~/.claude/skills/flow"]}
 {"event":"install:done","target":"claude","dests":["~/.claude/skills/flow"],"result":"success","error":null,"warnings":[]}
 {"event":"summary","success":true,"total":2,"attempted":2,"installed":2,"failed":0,"skipped":0,"aborted":false}
@@ -105,7 +115,7 @@ rm -rf <project>/.claude/skills/flow
 
 | Event | Required fields | Notes |
 |---|---|---|
-| `plan` | `version` (string), `dryRun` (bool), `scope` (`global`\|`project`), `targets` (string[]) | Always the first event. |
+| `plan` | `version` (string), `dryRun` (bool), `scope` (`global`\|`project`), `targets` (string[]), optional `skillVersion` (string\|null) | Always the first event. `version` = npm package; `skillVersion` = bundled `SKILL.md` product version. |
 | `install:start` | `target` (string), `dests` (string[]) | One per selected target. |
 | `install:done` | `target`, `dests`, `result` (`success`\|`failed`), `error` (string\|null), `warnings` (string[]) | Fired after each target. `error` is `null` on success. |
 | `summary` | `success` (bool), `total`, `attempted`, `installed`, `failed`, `skipped`, `aborted` (bool) | Always the last event. Counts sum: `attempted = installed + failed`; `skipped = total - attempted`. |

package/README_VN.md

@@ -110,6 +110,11 @@ Mỗi phiên bản publish có [npm provenance](https://docs.npmjs.com/generatin
 npm view @manhquy/flow-skill@<version> dist.attestations.provenance
 ```
 
+> **Ngoại lệ RC-window**: `v0.1.0-rc.1` được publish thủ công từ máy developer để bootstrap npm
+> Trusted Publisher (TP không thể bind tới package chưa tồn tại) — bản này không có provenance.
+> Từ `v0.1.0-rc.2` trở đi, mọi bản publish đều qua CI workflow với OIDC và có attestation
+> SLSA Build Level 2 đầy đủ.
+
 ## Bảo mật
 
 Threat model + WILL/WON'T list + kênh report — xem [SECURITY.md](./SECURITY.md). Tóm tắt: pure Node, không network call, không spawn shell/PowerShell, không postinstall hook, không chạm settings/hooks/MCP config.

package/SECURITY.md

@@ -55,7 +55,7 @@ These match the behavior of the upstream `install.sh`; they are documented rathe
   ```
   npm view @manhquy/flow-skill@<version> dist.attestations.provenance
   ```
-  **`v0.1.0-rc.1` exception**: this bootstrap version was published manually (Trusted Publisher requires the package to already exist before it can bind) and carries no attestation. All subsequent versions publish via CI and are attested. If provenance is a hard requirement for you, wait for `v0.1.0-rc.2` or later.
+  **`v0.1.0-rc.1` exception**: this bootstrap version was published manually (Trusted Publisher requires the package to already exist before it can bind) and carries no attestation. `v0.1.0-rc.2` (2026-07-17) is the first version published from CI via OIDC — confirmed live with an SLSA Build Level 2 attestation. All versions from rc.2 onward are attested; if provenance is a hard requirement, pin `@0.1.0-rc.2` or later.
 - **Publisher account.** npm 2FA `auth-and-writes` is enabled as defense-in-depth for the git + npm identity behind the workflow.
 - **Pin your version.** During the RC window use `@rc` (dist-tag) or an explicit `@0.1.0-rc.N`. After stable ships, pin `@0.1.x` (or a specific version). `@latest` invites blind updates on a package that writes to your agent home.
 - **Completeness signal (not tamper detection).** The tarball ships `skills-manifest.json` recording the synced skill's file count + list. The publish workflow re-counts the checked-out tree against this manifest to catch an incomplete sync. It is **not** a supply-chain integrity proof — that role belongs to npm provenance above. `.integrity` SHA-256 sidecar was intentionally not adopted because it would have been generated from the same source it hashed (circular trust).

package/bin/cli.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { join, resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 
-import { TARGETS, TARGET_NAMES, PKG_VERSION } from '../src/constants.mjs';
+import { TARGETS, TARGET_NAMES, PKG_VERSION, SKILL_VERSION } from '../src/constants.mjs';
 import { defaultSelection, detectAll } from '../src/detect.mjs';
 import { renderHelp } from '../src/help.mjs';
 import { install, installAntigravity } from '../src/installer.mjs';
@@ -288,6 +288,9 @@ async function main() {
     {
       event: 'plan',
       version: PKG_VERSION,
+      // Additive: skill product version (SKILL.md). `version` stays the npm package version
+      // for back-compat with existing JSONL consumers.
+      skillVersion: SKILL_VERSION,
       dryRun: opts.dryRun,
       scope,
       targets: plan.map((p) => p.target),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhquy/flow-skill",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "description": "Install the flow skill (buildflow gated build process) into your coding agent(s) via one npx command",
   "type": "module",
   "bin": {

package/skills/flow/harness/README.md

@@ -67,7 +67,7 @@ Linking a trace to an unverified story prints a **pre-close gate** warning.
 All wiring degrades gracefully: if python is absent or `FLOW_HARNESS_DISABLE=1`, the
 mechanical engine runs unchanged.
 
-## Usage signal: accessed_count (read-only, schema 005)
+## Usage signal: accessed_count (read-only, schema 009 — see Backends re-homing note above)
 `query decisions|friction|backlog` increment an `accessed_count` on every surfaced row and order
 output **most-reused-first**, so `recall` floats the knowledge you actually reuse to the top. It is
 a **read-only ordering signal** — never used to prune, delete, or archive a row. Low count is not
@@ -76,7 +76,7 @@ rare*. Security-class rows (`auth|authoriz|admin|tenan|payment|migrat|valid|secr
 always sort first and are never deprioritized. The story `matrix` view is intentionally left
 ordered by id (it is a status table, not recalled knowledge).
 
-## Usage log: mechanical flight-recorder (schema 006)
+## Usage log: mechanical flight-recorder (schema 010 — see Backends re-homing note above)
 Distinct from the curated, agent-authored records above: `flow.sh` itself self-records **every
 invocation** (no agent action needed) to append-only JSONL — `.flow/events.jsonl` (full, per-project)
 plus `~/.claude/flow/usage.jsonl` (compact, device-global). Fields: ts/epoch_s, session_id, cycle_id
@@ -93,7 +93,7 @@ stage_from→to, card, project_type, mode, flow_version, tier, host, read_only.
 - JSONL is the source of truth; `usage_event` is a derived, queryable mirror. Semantic events keep
   using `trace`/`intervention`/`decision` — the usage log does not duplicate them.
 
-**Closed feedback loop (schema 007).** The recorded data feeds the surfaces where you already act:
+**Closed feedback loop (schema 011 — see Backends re-homing note above).** The recorded data feeds the surfaces where you already act:
 - `recall` appends a one-line digest (`flow_harness.py usage --summary`): cycles, cycle-time, gate
   fail-rate, top gate-fail stage — so build history reaches you at stage/card start (silent if no data).
 - `propose` (`_build_proposals`) emits a backlog proposal when a stage's gate fail-rate ≥ 50% across

package/skills/flow/harness/flow_harness.py

@@ -1034,7 +1034,7 @@ def build_parser():
     q1 = pqs.add_parser("matrix"); q1.add_argument("--json", action="store_true"); q1.add_argument("--numeric", action="store_true")
     q2 = pqs.add_parser("backlog"); q2.add_argument("--open", action="store_true"); q2.add_argument("--closed", action="store_true"); q2.add_argument("--json", action="store_true")
     q3 = pqs.add_parser("friction"); q3.add_argument("--json", action="store_true")
-    q4 = pqs.add_parser("tools"); q4.add_argument("--responsibility"); q4.add_argument("--json", action="store_true"); q4.add_argument("--summary", action="store_true")
+    q4 = pqs.add_parser("tools"); q4.add_argument("--responsibility"); q4.add_argument("--json", action="store_true")
     q4.add_argument("--capability"); q4.add_argument("--status", choices=D.TOOL_STATUSES)
     q5 = pqs.add_parser("decisions"); q5.add_argument("--json", action="store_true")
 

package/skills-manifest.json

@@ -2,7 +2,7 @@
   "source": "../skills/flow",
   "destRelative": "skills/flow",
   "fileCount": 74,
-  "syncedAt": "2026-07-17T04:53:07.141Z",
+  "syncedAt": "2026-07-18T07:42:58.153Z",
   "fileList": [
     "SKILL.md",
     "_templates/00-idea.md",

package/src/constants.mjs

@@ -72,11 +72,26 @@ export const CLI_NAME = 'flow-skill';
 
 // F3 fix: read version from package.json at runtime so `npm version` bumps propagate to the
 // JSON `plan` event without a hand-edit here.
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, '..');
 const pkgJson = JSON.parse(
-  readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8')
+  readFileSync(resolve(pkgRoot, 'package.json'), 'utf8')
 );
 export const PKG_VERSION = pkgJson.version;
+
+// Skill product version (SKILL.md metadata.version) is a SEPARATE axis from the npm
+// installer package version. Surface both so `npx … --help` / plan events cannot be
+// misread as "stale skill" when the user expected 0.22.x and saw 0.1.0-rc.N.
+function readSkillVersion() {
+  const skillMd = resolve(pkgRoot, 'skills', 'flow', 'SKILL.md');
+  if (!existsSync(skillMd)) return null;
+  const text = readFileSync(skillMd, 'utf8');
+  // Frontmatter only — first `version: "x.y.z"` under metadata (or any YAML version line).
+  // Indented under `metadata:` in YAML frontmatter (two spaces typical).
+  const m = text.match(/^\s*version:\s*["']?([0-9][0-9A-Za-z.+-]*)["']?\s*$/m);
+  return m ? m[1] : null;
+}
+export const SKILL_VERSION = readSkillVersion();

package/src/help.mjs

@@ -1,16 +1,18 @@
-import { CLI_NAME, PKG_VERSION, TARGETS } from './constants.mjs';
+import { CLI_NAME, PKG_VERSION, SKILL_VERSION, TARGETS } from './constants.mjs';
 
 export function renderHelp() {
   const targetRows = TARGETS.map((t) => `    ${t.name.padEnd(12)} ${t.label}`).join('\n');
   // v0.23 H5 (red-team): derive the count from TARGETS.length so a future target addition can
   // never again leave a stale hardcoded number in the help text.
   const targetCount = TARGETS.length;
-  return `${CLI_NAME} v${PKG_VERSION}
+  const skillBit = SKILL_VERSION ? ` (ships skill v${SKILL_VERSION})` : '';
+  return `${CLI_NAME} v${PKG_VERSION}${skillBit}
 
 Install the flow skill into your coding agent(s).
 
 USAGE
-  npx @manhquy/flow-skill [options]
+  npx @manhquy/flow-skill@rc
+  # or after stable ships: npx @manhquy/flow-skill
 
 OPTIONS
   -y, --yes                    Skip prompts; install to default selection (detected + Claude)