diff --git a/.github/workflows/public-surface-check.yml b/.github/workflows/public-surface-check.yml index 336b3dc..ab8ee04 100644 --- a/.github/workflows/public-surface-check.yml +++ b/.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")) diff --git a/README.md b/README.md index d37942e..0d90a58 100644 --- a/README.md +++ b/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) diff --git a/docs/STAGE1_GITHUB_ACTION_STARTER.md b/docs/STAGE1_GITHUB_ACTION_STARTER.md index 03433b6..f1e9f93 100644 --- a/docs/STAGE1_GITHUB_ACTION_STARTER.md +++ b/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 diff --git a/docs/TOBI_ACTION_V2_MIGRATION.md b/docs/TOBI_ACTION_V2_MIGRATION.md new file mode 100644 index 0000000..3828273 --- /dev/null +++ b/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. diff --git a/docs/TOBI_ACTION_VERSION_POLICY.md b/docs/TOBI_ACTION_VERSION_POLICY.md new file mode 100644 index 0000000..5e3385e --- /dev/null +++ b/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). diff --git a/examples/github-actions/stage1_tobi_validator_example.yml b/examples/github-actions/stage1_tobi_validator_example.yml index 1d6af1b..e2ea152 100644 --- a/examples/github-actions/stage1_tobi_validator_example.yml +++ b/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