nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/docs/releases/v2.0.1.md

@@ -0,0 +1,135 @@
+# nobrainer-tech-flow 2.0.1 verification record
+
+Source version: 2.0.1. Publication is a separate check against the public tag
+and release archive; this document alone does not establish distribution.
+
+Corrections made by 2.0.2 (see its [record](v2.0.2.md)): the statements below that
+a symlink-loop destination is reported (not on Python 3.13), that a Claude import is
+recognised "only when it is a plain, stand-alone one" (code spans, nested fences,
+comments, raw HTML and more were still mistaken for imports; 2.0.2 recognises only a
+file that holds nothing but the import), that a non-absolute environment variable is
+an error (for every client, not only the one that reads it; a blank one also counted
+as unset) and that copy mode ignores bytecode (any `.pyc`, not only `__pycache__`).
+
+2.0.1 is a corrective release for 2.0.0. It adds no skill and keeps the
+eighteen-skill portfolio. The only skill-text change with a behavioural effect is
+a fallback for a missing `nobrainer-sessions` (see "Documentation and skills").
+
+## What changed
+
+Client adapters
+
+- Codex marketplace entry: the plugin is named `nobrainer-tech-flow` like its
+  manifest and uses a local source, so `codex plugin add` finds and installs it.
+  Before, neither plugin name matched both files.
+- Codex manifest: the two default prompts fit the 128-character limit; longer
+  ones are ignored by the client.
+- OpenCode: the bootstrap is still added after a compaction, when the first user
+  message has no text part, and a missing bootstrap file no longer throws.
+- Pi: dead state removed; a missing bootstrap file no longer fails a request.
+- Hooks: `hooks/session-start`, `hooks/run-hook.cmd` and `adapters/bootstrap.md`
+  are pinned to LF, so a Windows checkout with `core.autocrlf=true` still runs the
+  scripts and the bootstrap reaches the model without carriage returns.
+  `session-start` accepts a backslash script path when run under Git Bash, which
+  is how the Windows batch half of the wrapper starts it. `run-hook.cmd` itself
+  is unchanged and must stay POSIX-sh compatible, because hosts start it
+  through `/bin/sh`.
+
+Installers and setup
+
+- `install_skills.py`: copy mode no longer calls `ctypes.CDLL(None)` on Windows;
+  repeating a copy install over an identical copy is a no-op, ignoring bytecode
+  and `.DS_Store` litter, and a foreign directory is rejected by comparing names
+  and sizes before any file is read; a destination that is a file, a symlink loop
+  or unreadable, and a dangling link, are reported instead of crashing; the
+  preview names links from a selected skill to a skill that will be absent.
+- Claude Code `CLAUDE_CONFIG_DIR` and OpenCode `XDG_CONFIG_HOME` select the skills
+  directory, and Codex `CODEX_HOME` and the same two select the instruction file,
+  when `--home` is not given. An explicit `--home` ignores them. A value that is
+  not an absolute path is an error, and a blank one counts as unset.
+- `install_personalization.py`: a Claude file that imports the Codex global file
+  is treated as inheriting only when the import is a plain, stand-alone one and
+  the Codex file holds the block; otherwise the block is written and the reason
+  printed. Codex's `AGENTS.override.md` blocks the write it would shadow. The new
+  `--keep-options` flag keeps earlier auto-update, session-restart and wiki-root
+  settings, recognising a grant only as the exact line the installer writes for it
+  (so a `--preferences` value quoting the wording cannot forge one), and the block
+  no longer carries a stray blank line.
+- `recommend_flow_setup.py`: without a terminal (including a closed stdin) and with
+  an answer missing it stops with `INPUT_REQUIRED` and the flags to pass, instead
+  of hanging or crashing; it follows the same environment variables, resolves a
+  relative `--home`, always keeps earlier options, treats a symlink loop as a
+  conflict and says what to do when the Codex override file blocks the write.
+- All three scripts write UTF-8 to a pipe, so paths and instruction-file lines
+  outside the Windows code page no longer abort them, and the guided setup reads
+  the `gh` output as UTF-8.
+- `session_title.py`: the default UTC title no longer needs a time-zone database,
+  which Windows does not ship.
+- `check_public_commit.py`: decodes Git output as UTF-8 and reports a missing Git.
+
+Upgrading
+
+- If you ran the guided setup with 2.0.0 while `CLAUDE_CONFIG_DIR` or
+  `XDG_CONFIG_HOME` was set, 2.0.0 had written to the default location instead.
+  Re-running with 2.0.1 then stops and says so; run the same command with
+  `--rollback --apply` once, or pass `--home` to keep that location.
+- The next personalization run rewrites the managed block once (the stray blank
+  line is gone) and shows the difference in its preview.
+
+Documentation and skills
+
+- README lists all eighteen skills, states six compatibility levels and no longer
+  says 1.6 is current; `CLAUDE.md`/`AGENTS.md` lose stray backslashes; one
+  machine path is removed from `tasks/todo.md`.
+- `docs/INSTALL.md`: correct code fences, the guided-setup flags, the Claude Code
+  and Codex plugin commands and invocation forms, a subset example that keeps
+  what the core skill links to, one-channel-per-client guidance, and a Windows
+  section. Adapter descriptions match the code, and Cursor is no longer called
+  tested.
+- Three small skill-text edits, none evaluated with model runs (none was
+  possible here):
+  - `references/worktrees.md` and `references/daily-update.md` name their helper
+    scripts through `<flow-skill-dir>`, as the other references do, instead of a
+    path that exists only inside this repository.
+  - `nobrainer-codex-context` starts its read-only probe from the project through
+    `<context-skill-dir>`. The old text said to run it from the skill directory,
+    where it inspected the skill folder and reported `MISSING`.
+  - The core skill runs the Sessions startup step only when `nobrainer-sessions`
+    is installed and otherwise stays in MAIN. Before, a subset install without
+    Sessions pointed at a file that does not exist. Nothing changes when Sessions
+    is installed.
+
+Release gates
+
+- The skill `VERSION` file and `package-lock.json` must match the manifests;
+  `check_flow_update.py` reads the former.
+- A cross-skill link map fails when a skill starts linking into another skill,
+  the subset example in `docs/INSTALL.md` must have no dead links, and the README
+  table must list every skill.
+- CI syntax-checks the skill helper scripts and runs a Windows job.
+
+## Reproduce the repository checks
+
+From the exact reviewed release checkout, run:
+
+```sh
+python3 scripts/validate_skills.py --suite
+python3 -m unittest discover -s tests -q
+```
+
+The Windows job runs the validators plus `tests.test_windows_smoke` and
+`tests.test_adapters`. It passed on GitHub's `windows-latest` (Git Bash, Python
+3.11, Node 22) for this source, including the `cmd` wrapper reaching the bootstrap
+through Git Bash and a copy-mode install. The whole suite is not run there: some
+historical evidence tests compare text byte for byte and assume LF checkouts.
+
+## Evidence limits
+
+These checks establish local helper behavior, source contracts and the client
+readbacks named in the [compatibility record](../COMPATIBILITY.md). They do not
+prove that a client routes a task through Flow, that a model followed a skill, or
+that Cursor, Gemini CLI, Kimi Code, OpenCode or Pi accept the adapters at
+runtime; the OpenCode synthetic text part follows the message shape simulated in
+the tests, not a real OpenCode session. Known gaps that this release does not address are the cost of starting
+Flow on a trivial task, the worktree-per-task default, and the differences between
+the Flow and Dispatcher ledgers.

package/docs/releases/v2.0.2.md

@@ -0,0 +1,189 @@
+# nobrainer-tech-flow 2.0.2 verification record
+
+Source version: 2.0.2. Publication is a separate check against the public tag
+and release archive; this document alone does not establish distribution.
+
+2.0.2 builds on the [2.0.1 record](v2.0.1.md): everything in it is part of this
+release. It adds two installer scripts and fixes what two independent reviews found.
+It adds no skill (the portfolio stays eighteen) and changes no skill text, adapter
+or hook; the manifests change only their version.
+
+## What changed
+
+Installing without Python
+
+- `scripts/install.sh` is a POSIX sh script for one client (`claude`, `codex`,
+  `opencode` or `copilot`): `sh scripts/install.sh --client claude` previews,
+  `--apply` installs, `--undo --apply` reverses. It runs in dash, bash, zsh and
+  busybox on macOS, Linux and WSL, and in Git Bash on Windows, and needs only the
+  usual system tools (sed, grep, head, tail, mktemp, sha256sum or shasum, and git
+  to show the source commit).
+- The README opens its install section with a prompt to paste into any coding
+  agent: it clones or updates the repository and follows the install method the
+  README gives for that agent. It names no version, script or client list, so it
+  stays valid as they change. The same two commands follow for a terminal.
+- It uses the same locations, variables, conflict rule and setup record as the
+  Python scripts, and writes byte for byte the block the Python helper writes, so a
+  setup made by either one can be undone by the other.
+- It never grants an authorization, links only (like `install.py`), and leaves a
+  managed block that is already there exactly as it is, where `install.py` rewrites
+  it to the current text and keeps its options.
+- It refuses the paths the Python scripts refuse (a control character, a line or
+  paragraph separator, and, where `iconv` is installed, bytes that are not UTF-8),
+  so a record it writes stays readable to them, and it reads `--home=~/x` as
+  `install.py` does.
+
+One command with Python
+
+- `python3 scripts/install.py --client claude` does the same through the guided
+  setup with every skill selected. It asks nothing, prints the exact text it would
+  write, refuses a target that is not its own link, and runs the guided setup's own
+  checks in the preview, so the preview refuses whatever `--apply` would refuse.
+
+Undo that reverses the install
+
+- The setup record keeps the backup from the first install. Before, every later
+  run replaced it with the file as it was just before that run, so after an update
+  the undo restored a file that still held the block (found by the second review).
+- Undo puts the managed block back as it was before the first setup (removed, or
+  the block that was there) and leaves the rest of the file as it is now. The file
+  comes back byte for byte when nothing else changed, and edits made outside the
+  block since are kept. A block that was already there before the first install,
+  with its options and preference, is no longer deleted by the undo. That holds
+  for setups recorded by 2.0.2: a 2.0.0 or 2.0.1 record made when the block was
+  already there holds no backup, so its undo still removes the block.
+- The block is replaced as whole lines, the line break after its END marker
+  included, so both undos give the same bytes even after edits around the block,
+  and text added after a block that ended the file keeps a line of its own.
+
+Claude files that import the Codex instructions
+
+- The block is skipped only when the Claude file holds nothing but the import line
+  (`@~/.codex/AGENTS.md` or the absolute path) and the Codex file has the block;
+  every other Claude file gets its own block. 2.0.1 tried to recognise an import
+  anywhere in the file; the second review showed, against the real Claude Code
+  2.1.284, ordinary files where it saw an import that Claude Code does not load
+  (for example a list step whose closing fence sits at column 0, a quoted indented
+  example, a link definition, a tab after spaces), which left Claude without the
+  block. A second copy of the block is harmless; a missing one is not.
+
+Fixes from the independent review of 2.0.1
+
+Each has a regression test that fails against the 2.0.1 scripts.
+
+- An environment variable that the selected client never reads (a literal
+  `XDG_CONFIG_HOME=~/.config` with Claude Code, a relative `CODEX_HOME` with
+  Copilot) stopped every client and made a finished setup impossible to undo. Only
+  the variable the client reads is checked now, and its value is used exactly as
+  written. An empty `CODEX_HOME` or `XDG_CONFIG_HOME` counts as unset, as Codex
+  0.158.0 (checked) and the XDG specification treat it; spaces only, and an empty
+  `CLAUDE_CONFIG_DIR`, are relative paths and an error.
+- A grant could be forged under `--keep-options` from a `--wiki-root` path that
+  carried a line-separator character (U+2028, U+0085, U+001C and others), because
+  grant lines were found with `str.splitlines`. A grant is now a whole line ending
+  at `\n` or `\r\n`, and a preference or wiki path must be one printable line. An
+  edited grant line is not kept, and the run now says so and names the flag.
+- On Python 3.13 a destination that is a symlink loop was accepted (`resolve()` no
+  longer raises); it is reported again.
+- Copy mode ignored every `.pyc` and any directory named like litter, so a planted
+  `json.pyc` next to a script (importable, and it shadows the standard library) was
+  reported as an identical copy. Only `__pycache__` directories and `.DS_Store` and
+  `Thumbs.db` files are ignored now.
+- A home path that is not valid UTF-8, that holds a line break, or an empty or
+  relative `HOME` is refused before anything is written; such paths used to finish
+  a setup that could not be undone.
+- End of input at the interactive selection prompt ends the run instead of raising.
+- The 2.0.1 statement that Claude Code "does not accept" a relative or `~`
+  `CLAUDE_CONFIG_DIR` was wrong: Claude Code 2.1.284 creates the directory named by
+  a relative value in its working directory and takes `~` literally. The installer
+  still refuses such values because it cannot know what the client means.
+
+Smaller changes from the second review
+
+- The printed undo and install summaries are read from the setup record, not from
+  printed paths, and the undo counts the links it actually removed.
+- Messages name this command's flags (`--undo --apply`), a link left by an earlier
+  layout gets the migration command, Windows hints say `py -3`, and when
+  `CLAUDE_CONFIG_DIR`, `CODEX_HOME` or `XDG_CONFIG_HOME` chose the location the
+  output says to keep it set for the undo.
+- In `install.py` the link check before `--apply` runs where the skills go, not
+  only in the temp folder. `install.sh` checks in the temp folder; when a link still
+  fails where the skills go, it removes the links that run made and stops.
+
+Fixes from the review of the new scripts
+
+A third read-only review, of `install.sh`, the new undo and `install.py`, found no
+blocker and 13 smaller problems. Each fix below has a test that fails against the
+scripts before it, except the one for concurrent runs, which was checked by hand.
+
+- A hint that points to the Python undo keeps `--home`; following it used to undo
+  the default profile instead. On Windows it says `py -3`.
+- When the Claude file had become nothing but the Codex import, a repeat run left a
+  record that neither undo could reverse. The record now drops that file, as the
+  guided setup's does, and the undo removes the links.
+- Several runs at once could write links into the checkout, and a run could report
+  success after another one removed its links. A link is never made through a link
+  another run just made: one run wins, the others stop and remove only their own.
+- `sh scripts/install.sh` failed with `CDPATH` set.
+- When a record names another place, both installers now name the setting that
+  setup was made with (for example `CLAUDE_CONFIG_DIR=...`, or the variable unset),
+  and the undo command they print works as printed.
+- `install.sh` undoes a file that ends in a lone CR (old Mac line breaks) or holds a
+  NUL byte byte for byte; before, it installed and then refused to undo.
+- A variable of another client that holds a control character no longer stops
+  `install.sh`.
+- The mutation check found checks that no test reached; they now have tests (see
+  below).
+
+Documentation and gates
+
+- README, `docs/INSTALL.md`, `docs/TESTING.md` and `.opencode/INSTALL.md` describe
+  the new scripts and rules; the erratum for the 2.0.1 statements above is at the
+  top of its record.
+- Tests: `tests/test_shell_installer.py` and `tests/test_one_command_installer.py`
+  run the real scripts against a private home; the shell tests also run in every
+  POSIX shell found and with no Python on the `PATH`, and check both lists of skill
+  names against the Python installer. The regression tests fail against the
+  previous scripts.
+- Mutation check: 34 mutants of `install.sh`, each removing one check or behavior;
+  the shell tests catch 30. Of the other four, two change nothing (a second check
+  refuses the same backup paths, and `mktemp` already creates the record private)
+  and two matter only when another process changes the links during a run: the
+  re-check before an undo removes a link, and `ln -n` for runs at the same time,
+  checked by hand (12 rounds of 4 runs at once: one run succeeds each time, its
+  record matches its links, and nothing is written into the checkout). Of the
+  `install.py` mutants tried, only the link check at `--apply` is not caught; it
+  matters only where the skills folder refuses links that the temp folder allows.
+- CI runs both installers' tests in the Windows job (the shell one under Git Bash),
+  the whole suite on Python 3.13 with Node 22, checks `sh -n scripts/install.sh`,
+  and fails instead of skipping when a runner cannot create links.
+- `scripts/install.sh` is pinned to LF, like the hook scripts.
+
+## Reproduce the repository checks
+
+From the exact reviewed release checkout, run:
+
+```sh
+python3 scripts/validate_skills.py --suite
+python3 -m unittest discover -s tests -q
+```
+
+## Evidence limits
+
+These checks establish local helper behavior, source contracts and the client
+readbacks named in the [compatibility record](../COMPATIBILITY.md), which was made
+against the 2.0.1 adapters that this release leaves unchanged. They do not prove
+that a client routes a task through Flow, that a model followed a skill, or that
+Cursor, Gemini CLI, Kimi Code, OpenCode or Pi accept the adapters at runtime. No
+client was read back on an install made by either new script.
+
+- The shell installer ran here in dash, bash (POSIX mode), busybox sh and zsh
+  emulating sh on Linux; CI runs it under macOS's own `/bin/sh` and under Git Bash
+  on Windows. A Windows account without the right to create links was not run.
+- The single-line import rule was checked against the real Claude Code 2.1.284
+  only through the review's documents; the rule itself needs no Markdown parsing.
+- `install.sh` refuses a path that is not UTF-8 only where `iconv` is installed.
+  Runs at the same time were checked by hand, not in the suite.
+- Known gaps that this release does not address are the cost of starting Flow on a
+  trivial task, the worktree-per-task default, and the differences between the Flow
+  and Dispatcher ledgers.

package/docs/releases/v2.1.0.md

@@ -0,0 +1,64 @@
+# nobrainer-tech-flow 2.1.0 verification record
+
+Source version: 2.1.0. Publication requires separate tag and release-archive
+readback; this document does not by itself establish distribution.
+
+## Scope
+
+This release adds explicit idea intake and connects generated SDD acceptance
+criteria to the existing autopilot loop. It adds plain technical English as a
+mode of Writing. There are still eighteen skills and no new background runner,
+scheduler, model benchmark or provider call. Existing installers and adapters
+are unchanged except for release versions.
+
+The source since 2.0.2 also includes the
+[approved-plan autopilot change](https://github.com/nobrainer-tech/nobrainer-tech-flow/pull/71).
+The [2.0.2 record](v2.0.2.md) remains the installer baseline.
+
+## Sources and adaptation
+
+- [Karpathy's original post](https://x.com/karpathy/status/2105819303471976479):
+  writing and explanation guidance, not a new language or a Flow benchmark.
+- [ASD-STE100 overview](https://www.asd-ste100.org/about_STE.html) and
+  [official FAQ](https://www.asd-ste100.org/STE_faq.html): the existing controlled
+  language and the distinction between procedures and descriptions.
+- [Writing adaptation](../../skills/nobrainer-writing/references/plain-technical-english.md):
+  independently phrased guidance, without the dictionary or a conformance claim.
+
+## Verification
+
+The new paths were reviewed against a frozen source baseline and small writing
+exercises. The baseline already supported end-to-end work: this change makes
+the idea intake, requested SDD and final acceptance binding explicit. It is not
+a measured reliability improvement.
+
+An English procedure exercise preserved the literal command, production
+prohibition, UNKNOWN status, named operator, permission and backup condition.
+A Polish rewrite retained its language, exact quote and command, combined
+conditions, unknown actor and uncertainty. These were same-session native
+worker exercises, with MAIN inspecting the saved source and output. They were
+not blind trials or clean-session skill discovery; the small holdout does not
+establish general performance. No model benchmark or provider call was added.
+
+A separate native source review found no verified actionable defect in its
+inspected slice. It did not verify runtime discovery, all adapters or deployed
+behavior. Repository validation and public distribution are separate gates;
+exact CI and publication readback are linked from the release.
+
+Local checks on 2026-10-02: both skill validators passed; the full Python
+unit/archive suite passed 391 tests with 2 platform/environment skips; staged
+Gitleaks found no secrets. Version consistency is checked by the suite.
+These are repository results, not client-runtime acceptance. The site has its own
+validator/tests and browser checks at 1024 × 800 and 390 × 844. Copying the idea
+prompt must produce the visible text in the clipboard, and the technical
+writing details must expand without horizontal overflow.
+
+## Limits and rollback
+
+No cross-client discovery, autonomous uptime, lower task cost, token savings,
+formal STE compliance or superiority over another workflow is claimed. The
+English mode preserves other requested languages and marketing styles.
+
+For rollback, use the reviewed v2.0.2 source and the documented installer dry-run,
+conflict and backup checks. The versioned installation source must stay present
+while client links point to it. No user settings are changed by this source release.

package/docs/releases/v2.1.1.md

@@ -0,0 +1,43 @@
+# nobrainer-tech-flow 2.1.1 verification record
+
+Source version: 2.1.1. This corrects the communication defaults introduced with
+[2.1.0](v2.1.0.md). Publication is a separate tag and source-archive check.
+
+## Scope
+
+One Flow communication policy governs operational prose between agents and
+user-facing replies. Agent exchanges default to plain technical English, while
+user replies are written directly in the requested language. Team, Dispatcher and Sessions reference the same policy. The unchanged
+bootstrap already routes to Flow, which owns that default. Existing task schemas,
+source literals, language overrides, permissions and evidence remain binding.
+
+Writing selects TECHNICAL for English technical artifacts when no other mode
+is requested. Other languages use natural plain language with the same factual
+contract. Marketing, creative work and author voice keep their purpose.
+
+There is no additional translation call, provider, model setting, benchmark,
+runtime process or skill. This policy concerns visible messages, not hidden
+reasoning. It does not claim full ASD-STE100 compliance or performance savings.
+
+## Evidence and limits
+
+The frozen v2.1.0 baseline already passed the two small communication exercises;
+its instructions did not mandate the agent-language default. This release makes
+the policy explicit. The same two pressure cases and three fresh holdout
+exercises passed meaning checks, including a Polish worker-language override,
+exact code/JSON/quoted warnings, and a warm Polish marketing artifact. MAIN
+checked the actual saved outputs and literal preservation. Same-session exercises are not a blind causal comparison
+or proof that every client loads and follows the skill.
+
+Release gates: source/link/version validators, adapter and installer-link
+regressions, full Python tests, staged secret scan, semantic pressure and holdout
+checks, source review, and separate release/archive readback. The release notes
+link exact CI results after validation. No cross-client runtime or cost claim
+is inferred from these gates.
+
+## Rollback
+
+Use the reviewed v2.1.0 source and the documented installation dry-run and
+backup checks. No persisted schema or data migration is introduced. Keep the
+source checkout present while client links point to it. Explicit user language
+and style instructions override the new default without a rollback.

package/docs/releases/v2.2.0.md

@@ -0,0 +1,64 @@
+# nobrainer-tech-flow 2.2.0 verification record
+
+The communication reference now chooses the simplest useful presentation and
+closes non-trivial work with inspected proof and visible unfinished requirements.
+Text remains the default; diagrams explain relationships; HTML needs useful
+interaction. Explicit formats and artifact-only output take precedence. Video
+requires a bounded purpose and available tools, with a text/storyboard fallback.
+
+## Scope and weight
+
+One existing reference owns these rules. The eighteen skills, bootstrap and skill
+bodies are unchanged. No new renderer, provider, dependency, helper, data schema
+or result store is shipped. The reference also makes two observed failure classes
+explicit: machine-only output must not gain Markdown fences, and exact source
+text must stay separate from process metadata. Other execution stages and their
+workflow diagrams are unchanged; no diagram refresh is needed for this prose policy.
+
+## Actual checks and limits
+
+The [frozen inputs and raw answers](../evals/clear-results-v2.2.0.json) record
+fresh local CLI processes on 3 October 2026, using an explicitly supplied
+communication reference. Codex CLI 0.157.1 requested `gpt-6-astra` at `xhigh`;
+its event stream does not independently identify the served model. Claude Code
+2.1.286 requested `opus` at `xhigh`; returned usage identifies first-party
+`claude-opus-5-5` for the text trials. The HTML artifact receipt reports both
+`claude-opus-5-5` and `claude-opus-4-8`; the reason is unproven. Tools and external
+actions were disabled for these probes.
+No provider or client configuration was changed.
+
+Each baseline answered three development cases; each first candidate answered
+those three plus three fresh holdout cases. All per-case coarse assertions passed,
+but independent review found two failures in the first candidate output: Codex
+combined an exact error with the exit status; Claude fenced the outer JSON map.
+Those failures remain in the record. After the narrow instruction clarification,
+both clients passed a fresh single-task case: strict JSON, exact stdout, separate
+integer exit status and unverified public work. This is a focused correction
+check, not a re-score of the earlier run or proof of a quality gain.
+
+Two earlier candidate artifacts were inspected and exercised by MAIN: a Python
+stable-deduplication function passed six checks, including unhashable values,
+order, input preservation and an iterator; a self-contained retry explanation
+worked in the Codex browser at default, zero and four failures. Keyboard increment,
+390-pixel layout without overflow and inert markup-like label text were checked.
+These artifact checks bind the first candidate reference, before the format/literal
+clarification. They do not establish autonomous client tool execution.
+
+This is explicit-source behavior evidence, not automatic installed-skill discovery,
+a full-task client benchmark, a matched competitor comparison or proof of lower
+cost, faster work or better completion rates. Single runs do not estimate reliability.
+The current models can still violate instructions; MAIN must inspect real outputs.
+Video rendering, full client lifecycle and general compatibility remain unverified.
+
+Required release gates are the structure/suite validators, full unit tests, staged
+secret scan, independent source/output review and separate release/archive/site
+readback. CI results belong to the published commit, not the initial failed local
+run: that run encountered an installed `tests` namespace conflict, an intermittent
+short-timeout case and a release-note link before its target was written.
+
+## Rollback
+
+Return to v2.1.1 through the documented installer preview/backup flow. No persisted
+schema or migration is introduced. Keep the source checkout while client links
+refer to it. A requested simpler format or explicit language overrides the defaults
+without requiring rollback.

package/docs/releases/v2.2.1.md

@@ -0,0 +1,11 @@
+# v2.2.1: install Flow from npm and use the skills plugin
+
+This release adds distribution paths without adding modules or a task-execution service. The eighteen skill bodies remain unchanged from v2.2.0.
+
+- npm provides a named command to preview, apply and undo the existing client setup. Application retains a verified copy of release files at a stable profile path, so npx cache removal does not break installed links. Python 3.11+ is required for installation; help/version need only Node.
+- A hook-free plugin ZIP contains the same skills, references and helpers, portable identity, OpenAI presentation metadata and Claude compatibility metadata.
+- ChatGPT/Codex and Claude support skills plugins. Available tools and permissions remain the client's responsibility. Directory approval and client runtime acceptance are separate from package validation.
+
+See [installation](../INSTALL.md) for npm commands, [native plugins](../CHAT_PLUGINS.md) for supported surfaces and [privacy](../PRIVACY.md) for the package's data boundary.
+
+Verification records must distinguish packed-tarball installation, ZIP content checks, repository regression, npm publication and directory/client readback. A ZIP or a published npm tarball alone does not prove task performance in every client.

package/docs/releases/v2.3.0.md

@@ -0,0 +1,97 @@
+# nobrainer-tech-flow 2.3.0: delegate ready work and verify the result
+
+Release date: 2026-10-12. Theme: delegation-first.
+
+Use available native workers for independent work while the main session keeps
+coordination, integration and acceptance in one place. For example, independent
+implementation, documentation and test tasks can start together when their
+inputs, write scopes, capacity and authorized usage allow it. The main session
+inspects the returned artifacts before accepting the result.
+
+## What changes
+
+- In non-trivial work, every useful independent ready unit goes promptly to a
+  native worker, up to verified host capacity and authorized usage. The main
+  session coordinates, integrates, verifies and refills slots. If eligible ready
+  work stays in the main session while a slot is free, the plan records the
+  concrete reason. A missing measured speedup alone is not a reason to keep it
+  there.
+- Each native worker receives a compact packet: `TASK`, `INPUTS`, `WRITE_SCOPE`,
+  `DEPENDENCIES`, `METHOD`, `MODEL_AND_EFFORT`, `AUTHORITY`, `ACCEPTANCE`,
+  `BUDGET_AND_STOP` and `RETURN`. The packet carries the task's actual constraints
+  and proof requirements.
+- After each completion, the main session audits the result and refills the free
+  slot with ready work without waiting for unrelated slow workers. Waiting,
+  suspended and uncertain workers carry a reason and a bounded next observation.
+- Before a large or risky group of writers starts, a builder-readiness check
+  identifies missing implementation inputs. Routine choices stay within existing
+  authority; material unresolved decisions return to the owner.
+
+The [delivery contract](../../skills/nobrainer-tech-flow/references/delivery.md),
+[team assignments](../../skills/nobrainer-team/SKILL.md) and
+[dispatcher](../../skills/nobrainer-dispatcher/SKILL.md) own these rules. The
+portfolio remains eighteen skills. This release changes workflow instructions;
+it adds no task-execution service.
+
+## Safety and client limits
+
+One writer owns each mutable state. Exact worker IDs bind dispatch and readback;
+an uncertain send must be reconciled before another attempt can create a
+duplicate. Delegation remains flat unless recursion is expressly authorized.
+Visible conversations require an explicit owner request. The main session
+audits artifacts and preserves quota and cost ceilings.
+
+Native worker availability, tool access and capacity depend on the client. When
+usable native workers are unavailable, the main session continues authorized
+work and reports the limitation. Passing source checks does not prove that every
+client follows the contract during a real task.
+
+## Verification record
+
+Local checks on the final candidate bytes (macOS, Python 3.14):
+
+- `python3 scripts/validate_skills.py` and `python3 scripts/validate_skills.py --suite`:
+  both passed.
+- `python3 -m unittest tests.test_delegation_contract`: 7 source-contract tests
+  passed, including the route from ordinary fan-out to the builder-readiness check.
+- `python3 -m unittest discover -s tests`: 403 tests ran; all passed except 2
+  skipped platform-specific tests.
+- Root instructions stay within budget: `AGENTS.md` and `CLAUDE.md` are
+  identical at 204 lines and 1,600 words, the entry skill has 239 lines and 1,748
+  words, the bootstrap has 220 words and the portfolio has eighteen skills.
+- A secret scan with the repository's gitleaks configuration found no leaks.
+
+An independent release review found one routing gap: ordinary fan-out did not
+reach the builder-readiness check. The delivery contract now links it, and a
+regression test covers the link. The pull request's Validate workflow runs the
+repository checks on Linux, macOS and Windows for the exact candidate commit; the
+GitHub release records that run.
+
+No runtime benchmark was run for this release. No measured speed or token saving
+is claimed. Static contract tests and repository regression checks do not
+establish live scheduling behavior, task quality or a performance advantage over
+another workflow.
+
+## Distribution and rollback
+
+npm registry publication is still pending owner publisher access. The public
+[npm latest endpoint](https://registry.npmjs.org/nobrainer-tech-flow/latest)
+returned HTTP 404 on 2026-10-11. The v2.3.0 commands in
+[installation](../INSTALL.md) become available after registry publication and
+readback. A source release or locally packed tarball does not establish that.
+
+The separate [native plugin export](https://github.com/nobrainer-tech/nobrainer-tech-flow-plugin)
+follows the canonical GitHub release and its checked plugin ZIP. Export
+verification, directory approval and target-client acceptance each need their
+own readback.
+
+To roll back, return to v2.2.1 through the documented installer preview and undo
+flow, then restore the reviewed source. Keep retained source files while any
+client links refer to them.
+
+Sources (inspiration only): [GSD Core](https://github.com/open-gsd/gsd-core) for
+fresh-context parallel waves; [oh-my-openagent v5.1.29](https://github.com/code-yeongyu/oh-my-openagent/releases/tag/v5.1.29)
+for background-task states; and a public workflow pack's recent builder
+feasibility check and parallel-dispatch guidance, attributed on the
+[website comparison pages](https://nobrainer.tech/flow/compare/). These are
+design references, not measured comparisons.