nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/docs/COMPATIBILITY.md

@@ -0,0 +1,371 @@
+# nobrainer-tech-flow compatibility evidence
+
+nobrainer-tech-flow keeps one portable `skills/` source, but portability is
+not the same as a proven client integration. Record these levels separately:
+
+1. `SOURCE_VALIDATED` — the portable `SKILL.md` folders pass repository
+   validators; this makes no client claim.
+2. `REPOSITORY_CHECKED` — the manifest, hook, plugin or installer has a
+   deterministic local parse or execution test against the repository's frozen
+   contract; this does not prove the client accepts it.
+3. `CLIENT_LOADED` — the exact installed client version accepts the package and
+   reports the expected skills or bootstrap as loaded.
+4. `RUNTIME_VERIFIED_EXPLICIT` — a clean client session loads and follows the
+   canonical body under explicit invocation; this does not prove discovery.
+5. `RUNTIME_VERIFIED` — a clean client session discovers and follows
+   `nobrainer-tech-flow` without manually pasting its body.
+6. `DISTRIBUTED` — the exact release is available through the claimed public
+   marketplace or install channel and was read back after installation.
+
+Never promote one level from evidence belonging to another.
+Merge is a repository delivery state, not a client-compatibility level; release
+evidence records it separately.
+
+The current source version is **2.1.1**. Its release scope and proof limits are
+recorded in the [2.1.1 verification record](releases/v2.1.1.md), which refines
+the communication defaults of [2.1.0](releases/v2.1.0.md).
+It builds on the [2.0.2 installer record](releases/v2.0.2.md).
+The [2.0.0](releases/v2.0.0.md) and [1.14.1](releases/v1.14.1.md) records are
+historical evidence, not statements about the current source. The package/entrypoint migration
+is documented in the [migration guide](MIGRATION_TO_FLOW.md).
+
+For 2.0.x, portable structure, installation, selected setup, personalization,
+update checks and guarded cleanup have repository-level tests. The historical
+client matrix below does not establish fresh 2.0 automatic discovery,
+parallel execution, live Jev/Laya access or marketplace acceptance.
+Source release availability must be verified separately against its public tag.
+The unchanged command runner retains its scoped [v1.7.0 evidence](releases/v1.7.0.md).
+
+The 1.6.1 instruction review
+clarifies skill precedence and sufficient verification. Its evidence is a
+source-contract review; the v1.6 runtime results apply only to the archived
+release bytes. It adds no model-wide or cross-client runtime claim.
+
+The source channel was `DISTRIBUTED` for `v1.5.0`, with its exact historical
+merge, tag and installation in the [publication evidence](releases/v1.5.0-publication-readback.md).
+That record and [v1.3.1](releases/v1.3.1-publication-readback.md) remain rollback evidence. Pin a reviewed full
+commit SHA when immutability matters. Neither source publication nor an installed
+folder proves marketplace acceptance or model behavior.
+
+## Model-neutral readiness
+
+`WORKFLOW_READY` is a product-positioning label, not a seventh compatibility
+level. It means the portable policy can carry a selected model, effort, budget
+and escalation gate; it does not prove that a provider exposes or follows that
+policy.
+
+| Model / family | Workflow posture | Runtime evidence |
+|---|---|---|
+| GPT-6 Astra | `WORKFLOW_READY`: host-selected policy, optional native capabilities | Bounded v1.6 Codex behavioral probes; exact source and limits in the [release evidence](releases/v1.6.0.md) |
+| Other OpenAI models | Same portable instructions and policy | Only exact tested model IDs in the release evidence; no family-wide pass |
+| Claude models | Same portable instructions and policy | Historical explicit client evidence below; no automatic claim for a new model |
+| Other models / clients | Portable Markdown plus available tools | Unverified until tested in that host |
+
+OpenAI [announced GPT-6 Astra](https://openai.com/index/gpt-6-astra/) on
+2026-09-03. Names and access change; inspect the host's actual model list rather
+than treating this document as a model catalogue. No provider is a dependency.
+
+`v1.0.0` remains a separately verified nine-skill rollback anchor with its own
+[publication readback](releases/v1.0.0.md).
+
+The v1.3.0 source release has additional local runtime evidence in
+[the historical harness evaluation](evals/v1.3.0-harness-clarity-2026-08-30.md)
+and current behavioral evidence in
+[the Autoimprove evaluation](evals/v1.3.0-autoimprove-integrity-2026-09-01.md).
+The older client transcripts remain hash-scoped and do not silently upgrade to
+marketplace or automatic-routing claims. Both clients retain explicit-runtime
+evidence only; automatic routing and client publication remain unverified.
+
+## Adapter contracts and historical client evidence
+
+`REPOSITORY_CHECKED` below means deterministic repository tests passed. It does
+not mean the external client's parser accepted or loaded the package.
+
+| Client / harness | Source | Repository contract | Client load | Runtime | Distribution |
+|---|---|---|---|---|---|
+| Claude Code | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: manifest, portable installer and Claude SessionStart output | `CLIENT_LOADED`: CLI `2.1.241`, isolated plugin, namespaced explicit invocation | `RUNTIME_VERIFIED_EXPLICIT`: final nobrainer-tech-flow route reached and read canonical Autoimprove; automatic routing remains unverified | `NOT_PUBLISHED` |
+| Codex | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: accepted manifest schema and portable installer | `CLIENT_LOADED`: CLI `0.149.1`, repo-scoped copy, explicit canonical invocation | `RUNTIME_VERIFIED_EXPLICIT`: final Luna cases and isolated implementation passed; automatic and alias-only routing remain unverified | `NOT_PUBLISHED` |
+| Cursor | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: manifest path and Cursor SessionStart output | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| OpenCode | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: skills registration plus idempotent first-user transform | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| GitHub Copilot CLI | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: portable installer and repository instructions; no bootstrap | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| Gemini CLI | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: extension manifest and owned context include | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| Kimi Code | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: canonical skills path, `nobrainer-tech-flow` session-start field and native-tool boundary | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| Devin CLI | `SOURCE_VALIDATED` | no dedicated adapter | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| Pi | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: package resources and per-request dedupe transform | `CLIENT_LOADED`: resource loader `0.87.1` only, no session (see the current-source readback) | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| Hermes Agent | `SOURCE_VALIDATED` | `REPOSITORY_CHECKED`: root Agent Plugins v1 manifest only; no bootstrap | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| Antigravity and other plugin hosts | `SOURCE_VALIDATED` | no host-specific contract | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+| Generic Agent Skills consumers | `SOURCE_VALIDATED` | canonical folders only | `NOT_VERIFIED` | `NOT_VERIFIED` | `NOT_PUBLISHED` |
+
+Adapter checks apply to the current source. The client/runtime cells retain their
+recorded historical versions and hashes; they do not silently transfer to the current source.
+Consult the current release record for new probes. There is deliberately no blanket “works everywhere”
+badge: an unknown harness gets portable skill folders, then needs its own
+discovery/bootstrap proof before promotion.
+
+## Adapter contract
+
+All adapters point at the same eighteen directories. They may expose discovery and
+one small `NOBRAINER_BOOTSTRAP_V1` routing context, but they must not copy or
+rewrite skill bodies.
+
+- Claude and Cursor hooks emit exactly one platform-specific JSON field.
+- OpenCode and Pi detect their marker so one request never carries the bootstrap
+  twice. OpenCode prefixes the first user message's text and, when that message
+  has none (after a compaction), adds a synthetic text part. Pi adds it to every
+  model request that lacks it, because the host rebuilds the message list per
+  request.
+- Gemini includes an extension-owned context file instead of changing a user's
+  global instructions.
+- Kimi maps native tools but explicitly refuses to treat a hidden subagent as
+  proof of visible cross-session transport.
+- Codex uses native skill discovery and has no hook entry or default
+  `hooks/hooks.json` file. Claude points explicitly to
+  `hooks/claude-hooks.json`, preventing Codex from auto-discovering the
+  Claude-specific SessionStart adapter.
+- The portable root manifest contains no client-specific bootstrap. Hermes can
+  consume it through its Agent Plugins path, where skills remain namespaced and
+  explicitly selected until a clean runtime transcript proves more.
+- Copilot and Devin use portable skill folders and repository instructions only;
+  no dedicated startup hook or client plugin contract is claimed.
+
+## Current-source readback (2026-09-29)
+
+Run against a checkout of the 2.0.1 source (2.0.2 changes no adapter or hook and
+only the version in the manifests) with isolated client configuration and
+no real model request: the Claude Code session ran against a local stand-in API
+endpoint and Codex against a closed network, and both plugin installs used a
+local checkout, not the GitHub source. The rows show what the client loads and
+sends, not how a model behaves.
+
+| Client | Readback | Level |
+|---|---|---|
+| Claude Code `2.1.284` (Linux) | `claude plugin validate` passed. `claude plugin marketplace add` and `claude plugin install nobrainer-tech-flow@nobrainer-tech` installed 2.0.1 with 18 skills. The `SessionStart` hook exited 0 and the request to the model carried the `NOBRAINER_BOOTSTRAP_V1` context once. With `CLAUDE_CONFIG_DIR` set, guided setup installed into that directory, the client listed the installed skills, the instruction block reached the request and `~/.claude` stayed untouched. | `CLIENT_LOADED`; bootstrap delivery observed; routing unverified |
+| Codex `0.158.0` (Linux) | `codex plugin marketplace add` and `codex plugin add nobrainer-tech-flow@nobrainer-tech-skills-dev` installed 2.0.1. The model prompt listed 18 skills as `nobrainer-tech-flow:nobrainer-*`, and the plugin listing returned both default prompts. With 2.0.0 neither plugin name installed. | `CLIENT_LOADED`; routing unverified |
+| Pi `0.87.1` (Linux, resource loader only) | The extension loaded with its `resources_discover` and `context` handlers, 18 skills and no diagnostics. | `CLIENT_LOADED` for the loader; no session |
+| Windows (CI only: GitHub-hosted `windows-latest`, Git Bash, Python 3.11, Node 22) | The Windows smoke job passed on this source: both validators, the adapter tests and `tests/test_windows_smoke.py` (the `cmd` wrapper reaching the bootstrap through Git Bash, a copy-mode install, personalization with `CODEX_HOME`, the UTC session title). | `REPOSITORY_CHECKED` on Windows; no client read back |
+
+The Codex row used the marketplace's earlier name, `nobrainer-tech-skills-dev`.
+Since 2.4.0 it is `nobrainer-tech`: on 2026-10-18, Codex `0.163.0` (macOS) with
+an empty `CODEX_HOME` added the 2.4.0 source checkout as a local marketplace
+`nobrainer-tech` and installed `nobrainer-tech-flow@nobrainer-tech` with 18
+skills (`CLIENT_LOADED`; routing unverified). An old `nobrainer-tech-skills-dev`
+install stays enabled next to the new one until it is removed; see the
+[migration guide](MIGRATION_TO_FLOW.md#existing-installation-identities).
+
+The other rows above keep their earlier level: no readback of OpenCode, Cursor,
+Gemini CLI, Kimi Code or Copilot CLI was made for this source. The Windows job
+runs the validators and the modules listed in [Testing](TESTING.md), not the
+whole suite.
+
+## Codex module names (2.3.2 readback)
+
+Checked on 2026-10-14 with Codex 0.157.1 on macOS and the 2.3.1 source. The real
+client ran against a local stand-in server with all other network blocked, so no
+model was involved. The table shows the name the client lists and whether a typed
+name made it add the module text to the request, not how a model behaves.
+
+| Install | Listed as | Typed `$nobrainer-tech-flow` | Typed `$nobrainer-tech-flow:nobrainer-tech-flow` |
+|---|---|---|---|
+| `scripts/install.sh` links into a git checkout, which holds the plugin manifests | `nobrainer-tech-flow:nobrainer-tech-flow` | no module text added | module text added |
+| The npm package (from `npm pack`; it ships `.codex-plugin` and `.claude-plugin`), linked by the installer | `nobrainer-tech-flow:nobrainer-tech-flow` | no module text added | module text added |
+| `install_skills.py --mode copy` (real folders, no manifest above them) | `nobrainer-tech-flow` | module text added | no module text added |
+
+Codex names a module `<plugin>:<skill>` when a `.codex-plugin`, `.claude-plugin` or
+`.cursor-plugin` manifest sits above the folder a link resolves to. A checkout that
+keeps only `.kimi-plugin`, the root `plugin.json`, `gemini-extension.json` or
+`.agents/plugins`, or none of them, lists the plain name and takes the plain form.
+A mention linked to the module's `SKILL.md` path added the module text in the first
+row, whichever of the two names its text showed. The Codex 0.158.0 row above, a
+plugin install, lists the skills under the plugin name as well.
+
+Not checked: what a model does with the plain form when the listing is namespaced,
+the terminal and desktop mention pickers, other Codex versions and operating
+systems, and a plugin-channel install on 0.157.1. Level: `CLIENT_LOADED`; routing
+unverified.
+
+## Clean-session acceptance
+
+The approved-plan [autopilot loop](../skills/nobrainer-tech-flow/references/autopilot.md)
+is development source after the v2.0.2 tag. It adds explicit select, execute,
+check, review, correct and advance guidance.
+It preserves the active client and its authority boundary. Source validation
+and the deterministic lifecycle checks do not establish fresh automatic
+discovery or unattended continuation in any client; those still need the
+clean-session evidence below. This guidance adds no CLI executor or scheduler.
+
+For each client, record the exact client version, model, operating system,
+installation source and commit or release. Start with no project-specific rule
+that names NoBrainer. Preserve the complete transcript and use these probes:
+
+For a long-running probe, read back `SESSION_HEALTH_GATE` at `START`,
+`AFTER_COMPACTION`, `MATERIAL_TRANSITION` and `BEFORE_CLOSEOUT`, using the
+host/configured policy rather than assuming universal limits. Record
+`UNKNOWN`/`UNSUPPORTED` signals and lower proof instead of guessing. Read back
+`RUNTIME_RELEASE` separately: `task_complete` does not prove that task-owned
+browser, tool or subprocess workers are closed.
+Missing optional telemetry does not block safe bounded work or artifact acceptance;
+it only limits the health claim. An explicitly required hard budget still needs
+reliable enforcement. A configured warning checkpoints goal/TODO and prevents optional new workers or
+large units; a hard threshold requires the clear/end-turn gate. Repository
+examples are not universal host limits.
+For resumable probes, persist one task-local Markdown `GOAL_FILE`. Before clear,
+prove its checkpoint and no active writer, then record `CLEAR_MODE` and host
+readback. After clear or a fresh turn, reload the file from disk and reconcile
+identity, checkout and evidence; a transcript summary or host-native goal is not
+the canonical recovery source.
+
+### Automatic routing
+
+The portable `ROUTED` policy describes how a plan may select an advertised
+capability tier; it is not a cross-provider gateway. A client must read back the
+actual model, effort and budget before claiming automatic routing. An unavailable
+target is `MODEL_ESCALATION_PROPOSED` or `OWNER_APPROVAL`, never a silent
+fallback.
+
+```text
+Use nobrainer-tech-flow to design and implement an ambiguous feature that crosses several modules
+and may affect production.
+```
+
+Passing behavior:
+
+- `nobrainer-tech-flow` is selected without pasting its body;
+- the agent enters a short requirements/acceptance gate before writes;
+- it creates one canonical plan and shows a compact Progress checklist;
+- production effects remain owner-gated;
+- it does not manufacture workers before work units exist.
+
+### Correction and review loop
+
+```text
+I changed my mind: keep the public API unchanged. Update the plan accordingly.
+```
+
+Passing behavior: the old requirement is marked superseded, dependent TODO
+items and evidence are invalidated, and the affected route is rebuilt without a
+second ordinary clarification round. A simulated verified review finding must
+return to Build and then fresh Review; it may not reuse the old green result.
+
+### Explicit technical invocation
+
+```text
+$nobrainer-tech-flow Deliver this task with the smallest safe workflow.
+```
+
+Type the name the client lists for the module. In Codex that is
+`$nobrainer-tech-flow:nobrainer-tech-flow` when the module is listed under the
+plugin name and `$nobrainer-tech-flow` when it is listed plainly (see
+[Codex module names](#codex-module-names-232-readback)).
+
+Passing behavior: the client loads the nobrainer-tech-flow technical
+`nobrainer-tech-flow` body and any
+required relative reference without the user pasting either one.
+
+### Compatibility alias control
+
+```text
+Use nobrainer-tech-flow to deliver this task with the smallest safe workflow.
+Compatibility alias probe: use nb-ultra or nb-flow to deliver this task with the smallest safe workflow.
+```
+
+`nb-ultra`, `nb-flow` and `nb-workflow` are compatibility trigger phrases, not
+the product name or additional skill names.
+Record whether the client supports and selects it through implicit matching.
+Do not present this as an explicit invocation guarantee. In the v1.3.0 Codex
+probe, alias-only selection failed under a crowded skill catalog and a prompt
+that prohibited file reads; the canonical `$nobrainer-tech-flow` probe passed.
+
+### Non-trigger control
+
+```text
+Fix this obvious typo in README.md.
+```
+
+Passing behavior: the visible MAIN coordinator makes this tiny correction
+directly, without SDD, a wiki or a native worker. One visible MAIN can coordinate
+many native workers for non-trivial work under the
+[delegation contract](../skills/nobrainer-tech-flow/references/delivery.md#coordinated-team-execution).
+
+## Runtime evidence record
+
+Store a transcript or durable report with:
+
+```text
+CLIENT:
+CLIENT_VERSION:
+MODEL:
+OS:
+INSTALL_SOURCE:
+RELEASE_OR_COMMIT:
+SKILL_SHA256:
+INVOCATION: CANONICAL_EXPLICIT | IMPLICIT_DESCRIPTION
+PROMPT:
+SKILL_DISCOVERED:
+FIRST_WRITE_BEFORE_GATE: YES | NO
+RESULT: PASS | FAIL | BLOCKED
+SESSION_HEALTH_GATE:
+RUNTIME_RELEASE:
+OWNED_WORKER_READBACK:
+EVIDENCE_PATH:
+```
+
+Marketplace screenshots, manifest parsing, an installer exit code, or a skill
+appearing on disk do not replace this acceptance test.
+
+For a hook-based client, preserve the emitted JSON and prove the client consumed
+the marker. For OpenCode or Pi, preserve both adapter logs/readback and the first
+model action. A prompt that pastes the skill body does not prove discovery. A
+valid explicit run by the name the client lists proves explicit loading, not
+automatic routing.
+
+## Optional bounded command runtime (1.7.0)
+
+The Sessions helper runs explicit argv commands using Python 3.11+ on POSIX.
+It is opt-in and ships with the skill; no daemon or new hook registration is
+required. Windows process-group enforcement is unsupported. The eighteen
+plain-text skills remain portable; this helper does not narrow their format
+compatibility. See [runtime limits and examples](BOUNDED_RUNNER.md).
+
+## Session restart capability levels
+
+The `session-restart` mode shipped in v1.8.0 and refined in v1.8.1 is a
+client/model-neutral Sessions
+protocol. The optional Python 3.11+ helper evaluates observations and runs without
+a model or client SDK. It does not implement native creation or archival.
+Explicit nobrainer-tech-flow entry invokes startup naming and health assessment through `nobrainer-tech-flow`.
+This is agent-executed care; no native transport backend is bundled.
+Human-readable startup and rollover titles use `<stable task title> | started DD-MM` where a
+host supports create-time titles or rename. The registry retains the full start
+timestamp and timezone, and IDs remain authoritative. A client without title
+mutation reports that cosmetic capability as unsupported; this is not a failed
+transfer and no universal rename API is implied.
+
+- No hooks: the model checks at task boundaries and prepares durable progress.
+- Hooks: a reviewed client adapter may supply normalized observations and invoke
+  the helper; hook names and output envelopes remain client-specific.
+- Native sessions: automatic rotation additionally requires fresh creation, exact
+  identity/readback, shared checkpoint access and authoritative ownership transfer.
+- No archive API: a verified successor can continue with source archive pending.
+- No safe transport/ownership: manual handoff; no hidden worker substitution.
+
+Existing client-load evidence does not establish restart support. Native
+end-to-end restart, all-model behavior and net cost savings are unverified until
+tested separately for the exact adapter/client version. No global hooks are
+installed by enabling portable instructions. See [the guide](SESSION_RESTART.md).
+# Optional typed-decision runtime
+
+The eighteen-skill Markdown lifecycle requires only the host's existing model.
+Jev/Laya are optional profiles, off by default; Python and model access are not
+core prerequisites. See [configuration](../skills/nobrainer-tech-flow/references/optional-decisions.md).
+
+| Profile | Required only when enabled | Current proof |
+|---|---|---|
+| Core | Host able to follow project instructions | Existing host-specific evidence below; no universal runtime assertion |
+| Jev shadow | Python 3, authorized TypeSafe key and HTTPS access | Live synthetic Noul/Choice/Score via direct Jev 1.13.0 on macOS |
+| Laya shadow | Apple Silicon, separately installed Laya-MLX, cached model and compatible Python | Live synthetic Noul/Choice/Score with multilingual MLX checkpoint, offline loading on macOS |
+
+Typed-answer validity is not semantic correctness: Laya assigned a middling
+urgency score to the no-deadline fixture. Do not advertise equivalence or
+promote suggestions into hard decisions based on this smoke test. Per-call
+timings include process/model startup and are not warm inference benchmarks.
+No clean-session proof for a new harness is implied by these helper tests.