docs: prepare Tobi Validator GitHub Action v2 release line

.github/workflows/public-surface-check.yml

@@ -29,6 +29,7 @@ jobs:
 
           import json
           import re
+          import subprocess
           import sys
           from pathlib import Path
 
@@ -48,6 +49,8 @@ jobs:
               Path("docs/STAGE1_INSTALL_AND_USAGE.md"),
               Path("docs/STAGE1_QUICKSTART_FIRST_10_MINUTES.md"),
               Path("docs/STAGE1_SUPPORT_AND_ISSUE_REPORTING.md"),
+              Path("docs/TOBI_ACTION_V2_MIGRATION.md"),
+              Path("docs/TOBI_ACTION_VERSION_POLICY.md"),
               Path("docs/TSUBASA_FOR_AGENTS_STAGE1.md"),
               Path("docs/TSUBASA_STAGE1_PUBLIC_SYNTAX_AND_AUTHORING_REFERENCE.md"),
               Path("examples/github-actions/stage1_tobi_validator_example.yml"),
@@ -153,6 +156,128 @@ jobs:
           if re.search(r"mode\s*[:=]\s*['\"]?validate\b", action, re.IGNORECASE):
               errors.append("unsupported validate mode appears in action.yml")
 
+          eval_token_block = re.search(
+              r"(?m)^  eval_token:\r?\n((?:    [^\r\n]*(?:\r?\n|$))*)",
+              action,
+          )
+          if not eval_token_block or not re.search(
+              r"(?m)^    required:\s*true\s*$", eval_token_block.group(1)
+          ):
+              errors.append("action.yml eval_token input must remain required")
+
+          live_integration_paths = [
+              Path("README.md"),
+              Path("docs/STAGE1_GITHUB_ACTION_STARTER.md"),
+              Path("examples/github-actions/stage1_tobi_validator_example.yml"),
+          ]
+          version_policy_path = Path("docs/TOBI_ACTION_VERSION_POLICY.md")
+          migration_path = Path("docs/TOBI_ACTION_V2_MIGRATION.md")
+          legacy_reference_allowlist = {version_policy_path, migration_path}
+          v1_reference = "OrganeticSphere/tobi-validator@v" + "1"
+          v2_reference = "OrganeticSphere/tobi-validator@v2"
+          historical_token = "dist" + "_token"
+
+          for path in live_integration_paths:
+              text = texts.get(path, "")
+              if v2_reference not in text:
+                  errors.append(f"current integration file missing {v2_reference}: {path}")
+              if v1_reference in text:
+                  errors.append(f"legacy v1 reference remains in current integration file: {path}")
+              if historical_token in text:
+                  errors.append(f"historical distribution input remains in current integration file: {path}")
+              if "eval_token" not in text or "TOBI_EVAL_TOKEN" not in text:
+                  errors.append(f"current token convention is incomplete in integration file: {path}")
+
+          tracked_text_paths = []
+          tracked_output = subprocess.run(
+              ["git", "ls-files"],
+              check=True,
+              capture_output=True,
+              text=True,
+              encoding="utf-8",
+          ).stdout
+          for tracked_name in tracked_output.splitlines():
+              tracked_path = Path(tracked_name)
+              if tracked_path.suffix.lower() in {".md", ".txt", ".yml", ".yaml"}:
+                  tracked_text_paths.append(tracked_path)
+
+          for path in tracked_text_paths:
+              text = path.read_text(encoding="utf-8")
+              historical_report = path.parts[:2] == ("docs", "reports")
+              if (
+                  v1_reference in text
+                  and path not in legacy_reference_allowlist
+                  and not historical_report
+              ):
+                  errors.append(f"v1 integration reference outside explicit allowlist: {path}")
+              if (
+                  historical_token in text
+                  and path != migration_path
+                  and not historical_report
+              ):
+                  errors.append(f"historical distribution input outside migration history: {path}")
+
+          policy_text = texts.get(version_policy_path, "")
+          required_policy_fragments = [
+              "Current supported Action major:",
+              "Current integration reference:",
+              v2_reference,
+              "First v2 release:",
+              "`v2.0.0`",
+              "`v1.0.0` is the legacy exact Marketplace release",
+              "frozen transitional line",
+              "Movement or deletion of `v1` is not planned",
+              "public Action contract and security boundary changed",
+              "does not change Tsubasa semantics",
+              "does not change Tobi canonicalization",
+              "`_h` remains compatibility identity only",
+              "`stage1-tobi-validator-v0.7.0`",
+              "does not add a\n  `validate` mode",
+              "does not create a public verification API",
+              "does not expose the production validator implementation",
+          ]
+          for fragment in required_policy_fragments:
+              if fragment not in policy_text:
+                  errors.append(f"Action version policy missing required boundary: {fragment}")
+
+          migration_text = texts.get(migration_path, "")
+          required_migration_fragments = [
+              v1_reference,
+              v2_reference,
+              historical_token,
+              "TOBI_EVAL_TOKEN",
+              "eval_token",
+              "canon_input: path/to/artifact.tsubasa",
+              "golden_fixtures: path/to/fixtures.json",
+              "`_h` is compatibility identity only",
+              "Canonical equality does not establish factual truth",
+              "Validator acceptance is not universal correctness",
+              "The consuming workflow owns merge, release, allow, block, and escalation",
+          ]
+          for fragment in required_migration_fragments:
+              if fragment not in migration_text:
+                  errors.append(f"v2 migration guide missing required boundary: {fragment}")
+          if ".tbs" in migration_text:
+              errors.append("v2 migration guide must use .tsubasa examples, not .tbs")
+
+          current_copy = "\n".join(texts.values())
+          maintained_v1_claims = [
+              "current supported action major:\n\n`v1`",
+              "`v1` is the maintained major",
+              "`v1` is the maintained line",
+              "v1 is the maintained major",
+              "v1 is the maintained line",
+          ]
+          for claim in maintained_v1_claims:
+              if claim in current_copy.lower():
+                  errors.append(f"current copy incorrectly maintains v1: {claim}")
+          if re.search(
+              r"\bv2\s+(?:changes|modifies|alters)\s+(?:Tobi|Tsubasa|validator)",
+              current_copy,
+              re.IGNORECASE,
+          ):
+              errors.append("current copy claims that v2 changes validator semantics")
+
           for fixture in [Path("examples/golden/fixtures.json")]:
               try:
                   json.loads(fixture.read_text(encoding="utf-8"))

README.md

@@ -202,11 +202,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: OrganeticSphere/tobi-validator@v1
+      - uses: OrganeticSphere/tobi-validator@v2
         with:
           eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
           mode: canon
-          canon_input: examples/sample.tsubasa
+          canon_input: path/to/artifact.tsubasa
 ```
 
 ### Minimal Windows `golden` Example
@@ -225,16 +225,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: OrganeticSphere/tobi-validator@v1
+      - uses: OrganeticSphere/tobi-validator@v2
         with:
           eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
           mode: golden
-          golden_fixtures: examples/golden/fixtures.json
+          golden_fixtures: path/to/fixtures.json
 ```
 
-### Current `v1` Reading
+### Current `v2` Reading
 
-Action `v1` is intentionally narrow:
+Action `v2` is intentionally narrow:
 
 - `canon` mode
 - `golden` mode
@@ -244,6 +244,10 @@ Action `v1` is intentionally narrow:
 - OS-aware archive selection for Windows, Linux, and macOS
 - no runtime, backend, public API, or platform claims
 
+See the [Action version policy](./docs/TOBI_ACTION_VERSION_POLICY.md) and
+[v2 migration guide](./docs/TOBI_ACTION_V2_MIGRATION.md) for the supported line
+and legacy migration boundaries.
+
 ---
 
 ## What This Repository Contains
@@ -316,3 +320,4 @@ In short:
 - controlled validator delivery: **separate from unrestricted public repository access**
 
 [![Telegram Channel](https://img.shields.io/badge/Telegram-Join_Organetic-blue?logo=telegram&logoColor=white)](https://t.me/+wKVUzIlax44yYjhi)
+[![X Profile](https://img.shields.io/badge/X-Follow_Organetic-black?logo=x&logoColor=white)](https://x.com/OrganeticSphere)

docs/STAGE1_GITHUB_ACTION_STARTER.md

@@ -111,7 +111,7 @@ A narrow Tobi Validator workflow should:
 
 - request a 7-day evaluation token from Organetic
 - store it as `TOBI_EVAL_TOKEN`
-- use `OrganeticSphere/tobi-validator@v1`
+- use `OrganeticSphere/tobi-validator@v2`
 - pass `eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}`
 - run `canon` and/or `golden`
 
@@ -129,13 +129,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: OrganeticSphere/tobi-validator@v1
+      - uses: OrganeticSphere/tobi-validator@v2
         with:
           eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
           mode: canon
-          canon_input: examples/sample.tsubasa
+          canon_input: path/to/artifact.tsubasa
 ```
 
+For the maintained major and legacy boundaries, see the
+[Action version policy](./TOBI_ACTION_VERSION_POLICY.md) and
+[v2 migration guide](./TOBI_ACTION_V2_MIGRATION.md).
+
 ## Current Public Tsubasa Reference
 
 For the most complete current public-safe authoring guide for repository-owned

docs/TOBI_ACTION_V2_MIGRATION.md

@@ -0,0 +1,76 @@
+# Migrate to Tobi Validator GitHub Action v2
+
+## Current Floating `@v1` User
+
+A current floating-line integration may look like this:
+
+```yaml
+- uses: OrganeticSphere/tobi-validator@v1
+  with:
+    eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
+    mode: canon
+```
+
+Change only the Action reference:
+
+```yaml
+- uses: OrganeticSphere/tobi-validator@v2
+  with:
+    eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
+    mode: canon
+```
+
+For this consumer class, the token input, secret name, mode, and default
+validator release identifier do not change. The Action reference changes to the
+maintained `v2` line.
+
+## Exact `@v1.0.0` User
+
+The exact historical release used an earlier contract that may include the
+`dist_token` input. To migrate:
+
+1. Obtain approved Organetic evaluation access.
+2. Store the issued token in the repository secret `TOBI_EVAL_TOKEN`.
+3. Change the Action reference to `OrganeticSphere/tobi-validator@v2`.
+4. Pass the secret through the required `eval_token` input.
+5. Remove direct-distribution credential configuration.
+6. Preserve `canon` and/or `golden` usage as applicable.
+
+Do not expose private repository credentials. `dist_token` is not a hidden
+compatibility input in `v2`.
+
+## Minimal Examples
+
+For `canon`:
+
+```yaml
+- uses: OrganeticSphere/tobi-validator@v2
+  with:
+    eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
+    mode: canon
+    canon_input: path/to/artifact.tsubasa
+```
+
+For `golden`:
+
+```yaml
+- uses: OrganeticSphere/tobi-validator@v2
+  with:
+    eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
+    mode: golden
+    golden_fixtures: path/to/fixtures.json
+```
+
+## Common Boundaries
+
+`_h` is compatibility identity only.
+
+Canonical equality does not establish factual truth.
+
+Validator acceptance is not universal correctness.
+
+The consuming workflow owns merge, release, allow, block, and escalation
+policy.
+
+See the [Action version policy](./TOBI_ACTION_VERSION_POLICY.md) for the
+supported and legacy release lines.

docs/TOBI_ACTION_VERSION_POLICY.md

@@ -0,0 +1,47 @@
+# Tobi Validator GitHub Action Version Policy
+
+## Supported Line
+
+Current supported Action major:
+
+`v2`
+
+Current integration reference:
+
+`OrganeticSphere/tobi-validator@v2`
+
+First v2 release:
+
+`v2.0.0`
+
+The floating `v2` reference is the maintained integration line after the first
+v2 release is published.
+
+## Legacy Line
+
+`v1.0.0` is the legacy exact Marketplace release. The floating `v1` reference
+is a frozen transitional line. Movement or deletion of `v1` is not planned.
+
+Existing workflows are not automatically rewritten. Consumers must select the
+version appropriate to their integration and migrate explicitly.
+
+## Compatibility Boundary
+
+The exact `v1.0.0` release used an earlier credential and distribution
+contract. Action `v2` uses controlled evaluation access through the required
+`eval_token` input and the public `TOBI_EVAL_TOKEN` secret convention. This is
+a new major because the public Action contract and security boundary changed.
+
+The version-line change does not alter the validator contract:
+
+- `v2` does not change Tsubasa semantics.
+- `v2` does not change Tobi canonicalization.
+- `v2` does not change `_h`; `_h` remains compatibility identity only.
+- `v2` does not change the default validator release identifier,
+  `stage1-tobi-validator-v0.7.0`.
+- `v2` continues to expose only `canon` and `golden`; it does not add a
+  `validate` mode.
+- `v2` does not create a public verification API.
+- `v2` does not expose the production validator implementation.
+
+For consumer changes, see the [v2 migration guide](./TOBI_ACTION_V2_MIGRATION.md).

examples/github-actions/stage1_tobi_validator_example.yml

@@ -17,7 +17,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Run Tobi canon
-        uses: OrganeticSphere/tobi-validator@v1
+        uses: OrganeticSphere/tobi-validator@v2
         with:
           eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
           mode: canon
@@ -31,7 +31,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Run Tobi golden
-        uses: OrganeticSphere/tobi-validator@v1
+        uses: OrganeticSphere/tobi-validator@v2
         with:
           eval_token: ${{ secrets.TOBI_EVAL_TOKEN }}
           mode: golden