Render repository descriptions from canonical facts

.github/workflows/repo-description-drift.yml

@@ -0,0 +1,41 @@
+name: repository-description-drift
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - facts/facts.json
+      - facts/facts.schema.json
+      - facts/repo-descriptions.json
+      - scripts/repo_descriptions.py
+      - .github/workflows/repo-description-drift.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  public-descriptions:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Render exact proposed descriptions and review-only commands
+        run: |
+          mkdir -p description-proposals
+          python3 scripts/repo_descriptions.py render --facts facts/facts.json > description-proposals/descriptions.json
+          python3 scripts/repo_descriptions.py render --facts facts/facts.json --format commands > description-proposals/apply-commands.txt
+      - name: Check live public descriptions without applying changes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python3 scripts/repo_descriptions.py check --facts facts/facts.json --live > description-proposals/live-check.json
+      - name: Preserve exact proposals and live deltas even on drift
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: repository-description-proposals
+          path: description-proposals/
+          if-no-files-found: error

facts/README.md

@@ -54,3 +54,76 @@ format separators are escaped by the renderer so GitHub keeps every column.
 The hub's `publish` workflow triggers only on `v*` tags; `handle-upstream` only
 on upstream release dispatches. A facts-only branch or main change triggers
 neither. The ordinary test workflow may still run.
+
+## Public repository descriptions
+
+`repo-descriptions.json` is the versioned description policy, separate from the
+registry-derived facts. It contains only confirmed-public repository identities,
+approved product wording, templates, and license labels with exact public
+`LICENSE` commit URLs. It makes no new licensing decision. Held repositories
+retain their published text, are checked for drift, and never receive a command.
+Nonpublic repositories are excluded from public policy, output, and artifacts.
+
+Quantities, dates, release identifiers, and product commits use
+`{{facts:token.name|format}}` from the explicitly supplied `facts.json`; formats
+are `int`, `grouped` (thousands separators), `decimal`, and `text` (strings only).
+For example, `releases.1.0.1.scoreboard.graded` selects that immutable release,
+not current main. `{{license:id}}` inserts a centrally approved label and records
+its pinned source. `{{word:id}}` inserts approved static product wording, such as
+language/ABI standard names; it is not a quantity store.
+
+The engine preserves the approved published stopgap exactly. Its parenthesized
+open-corpus strategy and closed-test script counts are **historical inventory**
+from `inventory`, not the current graded-probe denominator. The policy records
+that scope explicitly. Corpus copy names the historical source release separately
+from current graded probes. Advancing the scoreboard never refills inventory or
+changes a released scoreboard.
+
+The approved engine all-graded claim fails closed unless `scoreboard.belowStrong`
+is zero and `scoreboard.excellent + scoreboard.strong == scoreboard.graded`.
+An unsupported snapshot is refused before output or live API calls, so it cannot
+produce partial command proposals. GitHub owner/repository identities compare
+case-insensitively for source verification, duplicates, live reads, and holds;
+pinned commits and the `LICENSE` source path still match exactly.
+
+At **every promotion**, without delayed batching:
+
+1. Immediately export canonical facts using `lab facts export`, following the
+   existing exporter/pinned-inventory process. A pipeline never creates a model.
+2. Render repository, README, website, and hosted-consumer outputs from that same
+   explicit snapshot; refresh pinned consumer copies and run `lab facts render`
+   and `lab facts check` for marked documentation.
+3. Render and inspect exact descriptions, source tokens, license sources, hashes,
+   and the proposed command text:
+
+   ```sh
+   python3 scripts/repo_descriptions.py render --facts facts/facts.json > descriptions.json
+   python3 scripts/repo_descriptions.py render --facts facts/facts.json --format commands > apply-commands.txt
+   ```
+
+4. TOP alone reviews and applies applicable commands. The renderer does not
+   execute its output; there is no apply mode. Held rows emit no command.
+5. Prove exact live agreement immediately after application:
+
+   ```sh
+   python3 scripts/repo_descriptions.py check --facts facts/facts.json --live
+   ```
+
+Use `--policy FILE` for a reviewed alternate policy. `check --gh PATH` accepts an
+operator-supplied executable without embedding workstation paths in source.
+Checks issue one read-only GitHub API GET per public row with a sixty-second
+timeout, no shell, and exact public identity verification. JSON output includes
+expected/actual deltas; null is distinct from empty text. Exit codes are zero for
+all matches, one for drift (including held text), and two for input, API, auth, or
+timeout errors. Failed reads never count as matches. Descriptions must be
+nonempty, at most 350 Unicode characters, and free of line separators/control
+characters; malformed JSON, duplicate keys, unknown fields/tokens, invalid
+numbers, and unresolved templates fail closed. Facts are validated against the
+unchanged public schema with the supported standard-library validator.
+
+The read-only `repository-description-drift` workflow runs on relevant pushes to
+main and manual dispatch, not pull requests. It fails on drift/errors and uploads
+exact proposals, review-only command text, and live deltas even on failure. It
+has no write permission or automatic application. Offline CLI acceptance uses a
+fake third-party executable, not live GitHub; run it in the approved test
+environment with `python3 -m unittest discover -s tests -p 'test_repo_descriptions.py' -v`.

facts/repo-descriptions.json

@@ -0,0 +1,113 @@
+{
+  "schema": "pineforge/repo-descriptions/v1",
+  "version": 1,
+  "labels": {
+    "apache": "Apache-2.0",
+    "source": "PineForge Source License 1.2"
+  },
+  "licenses": {
+    "engine": {
+      "label": "apache",
+      "repo": "pineforge-4pass/pineforge-engine",
+      "commit": "59082e696f0c7a95c1aa0d3179e1aac23f79fc04",
+      "url": "https://github.com/pineforge-4pass/pineforge-engine/blob/59082e696f0c7a95c1aa0d3179e1aac23f79fc04/LICENSE"
+    },
+    "codegen": {
+      "label": "source",
+      "repo": "pineforge-4pass/pineforge-codegen-oss",
+      "commit": "1e6eb83354b74ede1326fe55e576e91ea81f156b",
+      "url": "https://github.com/pineforge-4pass/pineforge-codegen-oss/blob/1e6eb83354b74ede1326fe55e576e91ea81f156b/LICENSE"
+    },
+    "corpus": {
+      "label": "apache",
+      "repo": "pineforge-4pass/pineforge-corpus",
+      "commit": "262bab123176989464cbab04aa94c72b3d3143be",
+      "url": "https://github.com/pineforge-4pass/pineforge-corpus/blob/262bab123176989464cbab04aa94c72b3d3143be/LICENSE"
+    }
+  },
+  "wording": {
+    "cpp_standard": "C++17",
+    "pine_language": "Pine Script v6",
+    "pine_compact": "PineScript v6"
+  },
+  "repositories": [
+    {
+      "role": "engine",
+      "repo": "pineforge-4pass/pineforge-engine",
+      "public": true,
+      "disposition": "managed",
+      "reason": "Approved published stopgap. Graded probes use the current scoreboard. Parenthesized strategy/script counts are historical inventory bound to inventory.sourceRelease, not the graded-probe denominator.",
+      "source": {
+        "repo": "pineforge-4pass/pineforge-engine",
+        "commit": "59082e696f0c7a95c1aa0d3179e1aac23f79fc04",
+        "url": "https://github.com/pineforge-4pass/pineforge-engine/blob/59082e696f0c7a95c1aa0d3179e1aac23f79fc04/LICENSE"
+      },
+      "template": "Open-source {{word:cpp_standard}} engine for backtesting and forward execution, with a versioned C ABI; {{word:pine_language}} runs through code generation. Against TradingView's own trade lists, all {{facts:scoreboard.graded|grouped}} graded probes ({{facts:inventory.corpusScripts|int}} open-corpus strategies, {{facts:inventory.closedScripts|int}} closed-test scripts) grade excellent or strong: {{facts:scoreboard.excellent|grouped}} excellent, {{facts:scoreboard.strong|int}} strong. {{license:engine}}."
+    },
+    {
+      "role": "codegen-oss",
+      "repo": "pineforge-4pass/pineforge-codegen-oss",
+      "public": true,
+      "disposition": "managed",
+      "reason": "Approved published stopgap; retain the verified current license label and existing product wording without a new licensing decision.",
+      "source": {
+        "repo": "pineforge-4pass/pineforge-codegen-oss",
+        "commit": "1e6eb83354b74ede1326fe55e576e91ea81f156b",
+        "url": "https://github.com/pineforge-4pass/pineforge-codegen-oss/blob/1e6eb83354b74ede1326fe55e576e91ea81f156b/LICENSE"
+      },
+      "template": "{{word:pine_language}} to C++ transpiler for the pineforge-engine runtime. Pure Python; source-available under the {{license:codegen}}: free for noncommercial use and personal trading, commercial use needs a license."
+    },
+    {
+      "role": "corpus",
+      "repo": "pineforge-4pass/pineforge-corpus",
+      "public": true,
+      "disposition": "managed",
+      "reason": "Replace stale untracked quantities. Explicitly distinguish current graded corpus probes from historical authored-script inventory; omit unsupported trade totals.",
+      "source": {
+        "repo": "pineforge-4pass/pineforge-corpus",
+        "commit": "262bab123176989464cbab04aa94c72b3d3143be",
+        "url": "https://github.com/pineforge-4pass/pineforge-corpus/blob/262bab123176989464cbab04aa94c72b3d3143be/LICENSE"
+      },
+      "template": "Open Pine Script reference corpus and TradingView trade traces. Current graded corpus: {{facts:scoreboard.scopes.corpus.excellent|grouped}}/{{facts:scoreboard.scopes.corpus.graded|grouped}} excellent probes. Historical script inventory ({{facts:inventory.sourceRelease|text}}): {{facts:inventory.corpusScripts|grouped}} scripts. {{license:corpus}}."
+    },
+    {
+      "role": "hpo",
+      "repo": "pineforge-4pass/pineforge-hpo",
+      "public": true,
+      "disposition": "HOLD",
+      "reason": "Published description is held/read-only pending authorization. No new license claim, release/catalog change, or setting-change command.",
+      "source": {
+        "repo": "pineforge-4pass/pineforge-hpo",
+        "commit": "d66788a6160b271d78270652acf7f8f82d906343",
+        "url": "https://github.com/pineforge-4pass/pineforge-hpo/blob/d66788a6160b271d78270652acf7f8f82d906343/LICENSE"
+      },
+      "approved_text": "Native C++ hyperparameter optimization for PineForge strategies: grid, seeded random, dlib global search, and TPE (alpha)"
+    },
+    {
+      "role": "release",
+      "repo": "pineforge-4pass/pineforge-release",
+      "public": true,
+      "disposition": "static",
+      "reason": "Preserve verified published product wording; no quantitative parity claim.",
+      "source": {
+        "repo": "pineforge-4pass/pineforge-release",
+        "commit": "f93dfca830b8a4a20d43c682a84d52a62bd942fd",
+        "url": "https://github.com/pineforge-4pass/pineforge-release/blob/f93dfca830b8a4a20d43c682a84d52a62bd942fd/LICENSE"
+      },
+      "template": "Full {{word:pine_compact}} → deterministic backtest: pineforge-engine runtime + bundled codegen transpiler"
+    },
+    {
+      "role": "backtest-mcp",
+      "repo": "pineforge-4pass/pineforge-backtest-mcp",
+      "public": true,
+      "disposition": "static",
+      "reason": "Preserve verified published product wording; no quantitative parity claim.",
+      "source": {
+        "repo": "pineforge-4pass/pineforge-backtest-mcp",
+        "commit": "7ced51880a47af6793e80c65d5de0599c251e25a",
+        "url": "https://github.com/pineforge-4pass/pineforge-backtest-mcp/blob/7ced51880a47af6793e80c65d5de0599c251e25a/LICENSE"
+      },
+      "template": "Offline MCP server: an AI agent transpiles {{word:pine_compact}} → C++ and runs deterministic, TradingView-parity backtests locally (transpile, backtest, parameter grid, Binance OHLCV, Pine coverage lookup). One Docker container, no API key; code & data stay on your machine."
+    }
+  ]
+}