release: prepare v0.2.0 stable CLI + QA gates

Author: seanphan

.github/workflows/ci.yaml

@@ -32,6 +32,10 @@ jobs:
         run: |
           pytest -q tests/unit
 
+      - name: Run CLI smoke gate
+        run: |
+          bash scripts/release_readiness.sh --skip-tests --skip-node
+
   node-wrapper-smoke:
     runs-on: ubuntu-latest
     needs: python-tests

.github/workflows/release-node.yaml

@@ -23,10 +23,24 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install python package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+
       - name: Validate operation-id mappings
         run: |
           python3 scripts/check_operation_id_mappings.py
 
+      - name: Run CLI smoke gate
+        run: |
+          bash scripts/release_readiness.sh --skip-tests --skip-node
+
       - name: Setup Node
         uses: actions/setup-node@v4
         with:

.github/workflows/release-python.yaml

@@ -47,6 +47,14 @@ jobs:
         run: |
           python scripts/check_operation_id_mappings.py
 
+      - name: Install package with test dependencies
+        run: |
+          python -m pip install -e ".[dev]"
+
+      - name: Run release readiness gate
+        run: |
+          bash scripts/release_readiness.sh --skip-node
+
       - name: Install build tooling
         run: |
           python -m pip install --upgrade pip

.gitignore

@@ -14,3 +14,4 @@ build/
 node_modules/
 *.tgz
 *.log
+.minion-runs/

README.md

@@ -19,6 +19,7 @@ In shared docs, prefer the module/venv path for deterministic resolution:
 
 - Thin UX wrapper over `agenticflow_sdk` for high-level commands: `workflow`, `agent`, `node-types`, `connections`.
 - OpenAPI-backed discovery helpers: `ops`, `catalog`
+- Agent-native execution path: `code search`, `code execute`
 - Low-level OpenAPI transport via `call`
 - `call` resolves explicit `--operation-id` or raw `--method`/`--path` and executes the API request directly (not a high-level wrapper).
 - Preflight checks (`doctor`) and local policy guardrails (`policy`).
@@ -47,7 +48,6 @@ High-level commands in this section are SDK-driven. `call` is the only raw trans
   - `agent stream --agent-id <id> --body '{\"messages\":[]}' --dry-run`
   - `node-types dynamic-options --name <node_type> --field-name <field> --project-id <project_id> --input-config '{}' --dry-run`
   - `connections list --workspace-id <workspace_id> --project-id <project_id> --dry-run`
-  - `connections categories --workspace-id <workspace_id> --dry-run`
 
 Admin/internal endpoints are intentionally not included in the bundled snapshot.
 
@@ -106,6 +106,10 @@ agenticflow auth whoami --json
 
 `--token` bearer override is intentionally unsupported.
 
+Compatibility note:
+- `connections categories` maps to a server endpoint that currently requires user JWT bearer auth.
+- With API-key-only auth, use `connections list` and `node-types` discovery flows.
+
 ## Release docs smoke checks
 
 - `PYTHONPATH=. .venv/bin/python scripts/agenticflow_cli.py --help`
@@ -122,6 +126,24 @@ agenticflow auth whoami --json
 - `PYTHONPATH=. .venv/bin/python scripts/agenticflow_cli.py node-types dynamic-options --name google-drive --field-name folder --project-id proj_demo --input-config '{}' --dry-run`
 - `PYTHONPATH=. .venv/bin/python scripts/agenticflow_cli.py connections list --workspace-id ws_demo --project-id proj_demo --dry-run`
 
+## Release Readiness Gate
+
+Run the full local gate before tagging a release:
+
+```bash
+bash scripts/release_readiness.sh
+```
+
+This validates operation-id mappings, runs unit tests, executes CLI dry-run smoke checks, and verifies the Node wrapper.
+
+## Unattended Minion Flow
+
+This repository includes a tmux-based one-shot multi-agent workflow for `gpt-5.3-codex-spark`.
+
+- Runbook: `docs/minion_runbook.md`
+- Launcher: `scripts/minion_orchestrator.sh`
+- Worker runner: `scripts/minion_worker.sh`
+
 ## Node Wrapper (npm)
 
 This repo also ships a thin npm wrapper package (`@pixelml/agenticflow-cli`) that invokes the Python CLI.
@@ -131,7 +153,9 @@ npm i -g @pixelml/agenticflow-cli
 agenticflow --help
 ```
 
-The wrapper requires Python 3.10+ with `agenticflow-cli` installed or importable.
+The wrapper requires:
+- Node.js 18+
+- Python 3.10+ with `agenticflow-cli` installed or importable.
 
 ## Release Tags
 

bin/agenticflow.js

@@ -4,12 +4,33 @@ const { spawnSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
 
+function parseNodeMajorVersion() {
+  const raw = process.versions && process.versions.node ? process.versions.node : "";
+  const major = parseInt(String(raw).split(".")[0], 10);
+  if (Number.isNaN(major)) {
+    return null;
+  }
+  return major;
+}
+
+const majorVersion = parseNodeMajorVersion();
+if (majorVersion === null || majorVersion < 18) {
+  const rendered = process.versions && process.versions.node ? process.versions.node : "unknown";
+  console.error(
+    "[agenticflow wrapper] Node.js >= 18 is required. " +
+      "Current runtime: " +
+      rendered +
+      ". " +
+      "Install a newer Node version and rerun."
+  );
+  process.exit(1);
+}
+
 const cliArgs = process.argv.slice(2);
 const repoRoot = path.resolve(__dirname, "..");
 const localVenvPython = path.join(repoRoot, ".venv", "bin", "python");
 
 const candidates = [
-  { cmd: "agenticflow", args: cliArgs, env: { AGENTICFLOW_NODE_WRAPPER: "1" } },
   ...(fs.existsSync(localVenvPython)
     ? [{ cmd: localVenvPython, args: ["-m", "agenticflow_cli", ...cliArgs] }]
     : []),
@@ -32,7 +53,7 @@ for (const candidate of candidates) {
     process.exit(1);
   }
 
-  process.exit(result.status ?? 0);
+  process.exit(typeof result.status === "number" ? result.status : 0);
 }
 
 console.error(

docs/agenticflow_cli_skill_usage.md

@@ -30,6 +30,7 @@ Use this sequence for production-safe automation:
    - `agenticflow ops show <operation_id>`
    - `agenticflow node-types search --query <topic>`
 5. Validate request shape before execution:
+   - `agenticflow code execute --plan /path/to/operation_plan.json --dry-run`
    - `agenticflow call --operation-id ... --dry-run`
    - `agenticflow workflow validate --body @workflow.json --dry-run`
 6. Execute and verify:
@@ -54,9 +55,11 @@ These playbooks are distilled from the internal skill docs into CLI-first execut
   - `ops list --public-only`
   - `ops show <operation_id>`
   - `node-types search --query <q>`
+  - `code search --task <goal>`
 - Execution:
   - `call --operation-id ...`
   - `call --method GET --path /v1/...`
+  - `code execute --plan /path/to/operation_plan.json --dry-run`
   - `workflow create|get|update|run|run-status|validate`
   - `agent create|get|update|stream`
 - Operational safety:

docs/cli_secured_ops_baseline.md

@@ -13,6 +13,38 @@ Use a curated bundled snapshot:
 - Add authenticated operations required by current CLI wrappers.
 - Exclude admin/internal endpoints from the bundled snapshot.
 
+## Declared public API vs CLI-supported coverage baseline
+
+- **Declared public API** is the bundled snapshot contract:
+  - `71` operations total (`59` public/no-security + `12` authenticated wrapper-backed operations).
+  - Exposed through `catalog`/`ops` and reflected in CLI command docs.
+- **CLI-supported coverage baseline** is the same operation set, with one `support_scope` per operation used by harness and release review.
+
+## Support matrix (single source of truth)
+
+The support scope baseline is stored in `src/agenticflow_cli/public_ops_manifest.json` on each operation record:
+
+- `support_scope`: one of `executed`, `blocked-by-policy`, or `unsupported/out-of-scope`.
+- `support_rationale`: operator-facing reason this operation is in its class.
+
+Current baseline totals:
+
+- `34` `executed`
+- `17` `blocked-by-policy`
+- `20` `unsupported/out-of-scope`
+
+Policy semantics:
+
+- `executed`: safe read/query/validation/public wrappers that coverage attempts as live API calls.
+- `blocked-by-policy`: command intent exists, but execution is intentionally blocked in harness for safety/policy.
+- `unsupported/out-of-scope`: intentionally not part of the CLI-supported public surface (internal, unsupported workflow, or unimplemented wrapper contract).
+
+## Release interpretation of support rows
+
+- `executed`: release as supported/available behavior. These operations are expected to remain runnable in public smoke checks.
+- `blocked-by-policy`: keep listed as “declared public API, unavailable by policy” in release notes and include policy rationale.
+- `unsupported/out-of-scope`: do not promote as supported features; these are intentionally outside the CLI contract even if visible in discovery.
+
 ## Added authenticated operation IDs
 
 - `create_workflow_model_v1_workspaces__workspace_id__workflows_post`

docs/n8n_translator_v2.md

@@ -0,0 +1,64 @@
+# n8n → AgenticFlow Translator v2
+
+This repository ships a v2 translator implementation in `scripts/module/translator_v2.py`.
+It enforces explicit capability-state tracking to prevent silent degradations.
+
+## Behavior
+
+- The translator maps known source patterns to AgenticFlow node types with a
+  `capability` status for each required source capability:
+  - `equivalent` — required behavior is represented in translated nodes.
+  - `partial` — translated output includes related behavior but not full parity.
+  - `unsupported` — translation cannot represent the behavior.
+- Hard failure is enabled by default.
+  - If any required critical capability (`tooling`, `memory`, plus any unsupported mapping)
+    resolves to `unsupported` (or non-equivalent for critical capabilities),
+    `translate_n8n_template(..., strict=True)` raises `TranslationFailure`.
+- Fail-loud is explicit in the returned/raised artifact:
+  - `required_capabilities` includes each required capability and its state.
+  - `node_results` tracks per-node mapping decisions.
+  - `workflow_payload` contains the synthesized AgenticFlow workflow payload.
+
+## Known tool-aware mappings
+
+- LLM patterns
+  - `@n8n/n8n-nodes-langchain.agent`
+  - `@n8n/n8n-nodes-langchain.lmChat*`
+  - `@n8n/n8n-nodes-langchain.chainLlm`
+  - `@n8n/n8n-nodes-langchain.openAi`
+  - `@n8n/n8n-nodes-langchain.googleGemini`
+  to `llm`.
+
+- Tool-like patterns
+  - `n8n-nodes-base.httpRequest` → `api_call`
+  - `n8n-nodes-base.gmail` → `mcp_run_action` (`gmail-send-email`)
+  - `n8n-nodes-base.googleSheets` → `mcp_run_action` (`google_sheets-upsert-row`)
+  - `n8n-nodes-base.googleDocs` → `mcp_run_action` (`google_docs-insert-text`)
+  - `n8n-nodes-base.linkedIn` → `mcp_run_action` (`linkedin-create-text-post-user`)
+  - `n8n-nodes-base.emailSend` → `send_email`
+
+- Memory
+  - `@n8n/n8n-nodes-langchain.memoryBufferWindow` is marked non-equivalent because
+    there is no automatic AgenticFlow equivalent mapping in v2.
+
+## Gap artifact format
+
+`build_gap_report()` and `write_gap_report()` produce a QA-friendly JSON object with:
+
+- `translator_version`
+- `source_template_id`
+- `required_capabilities`
+- `node_results`
+- `workflow_payload`
+
+This is intentionally similar to the translation payload summaries previously produced
+for quick-win translation artifacts.
+
+## Limits
+
+- Non-semantic parser-style nodes are skipped when known non-essential patterns are
+  encountered.
+- Unknown nodes are marked unsupported (`node:<node_type>` capability) so they are
+  visible in gaps and never silently dropped.
+- No claim of semantic equivalence is made for tooling/memory omissions.
+