From 19492fb1ab19d09aec3c4ca6b8d27b46d7c9b8b2 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 13:09:41 -0700 Subject: [PATCH 01/11] Add shared architecture-docs as submodule + CLAUDE.md + freshness check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wires NaradaAI/architecture-docs as a git submodule at architecture-docs/ (relative URL, branch=main). Adds a top-level CLAUDE.md pointing at the shared docs with python-sdk.md emphasized, and a small GitHub Actions workflow that fails when the submodule pointer falls behind architecture-docs/main. The freshness check uses ARCHITECTURE_DOCS_READ_PAT (needs to be added as a repo secret with read access to NaradaAI/architecture-docs). Until the secret is configured, the check emits a warning annotation and exits 0 so this PR can land cleanly. Note: this repo is public, so PRs from forks won't have access to the secret — graceful-degrade ensures those PRs still pass. --- .../workflows/architecture-docs-freshness.yml | 57 +++++++++++++++++++ .gitmodules | 4 ++ CLAUDE.md | 26 +++++++++ architecture-docs | 1 + 4 files changed, 88 insertions(+) create mode 100644 .github/workflows/architecture-docs-freshness.yml create mode 100644 .gitmodules create mode 100644 CLAUDE.md create mode 160000 architecture-docs diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml new file mode 100644 index 0000000..60f78eb --- /dev/null +++ b/.github/workflows/architecture-docs-freshness.yml @@ -0,0 +1,57 @@ +name: architecture-docs freshness + +on: + pull_request: + branches: [main] + push: + branches: [main] + +jobs: + check-submodule-current: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + submodules: false + + - name: Compare pinned submodule SHA against architecture-docs/main + env: + GH_TOKEN: ${{ secrets.ARCHITECTURE_DOCS_READ_PAT }} + run: | + set -euo pipefail + + if [ -z "${GH_TOKEN:-}" ]; then + echo "::warning::ARCHITECTURE_DOCS_READ_PAT secret is not configured. Skipping freshness check." + echo " Configure a fine-grained PAT with read access to NaradaAI/architecture-docs" + echo " and add it as the secret ARCHITECTURE_DOCS_READ_PAT in this repo." + exit 0 + fi + + PINNED=$(git ls-tree HEAD architecture-docs | awk '{print $3}') + if [ -z "$PINNED" ]; then + echo "::error::No architecture-docs submodule pointer found in this commit." + exit 1 + fi + + REMOTE=$(gh api repos/NaradaAI/architecture-docs/git/refs/heads/main --jq '.object.sha') + if [ -z "$REMOTE" ]; then + echo "::error::Failed to read architecture-docs/main HEAD via gh api. Check the PAT scope." + exit 1 + fi + + echo "Pinned: $PINNED" + echo "Latest: $REMOTE" + + if [ "$PINNED" = "$REMOTE" ]; then + echo "architecture-docs submodule is at main HEAD." + exit 0 + fi + + echo "::error::architecture-docs submodule is stale." + echo "" + echo "To bump the pointer:" + echo " git submodule update --remote architecture-docs" + echo " git add architecture-docs" + echo " git commit -m 'Bump architecture-docs'" + echo " git push" + exit 1 diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..d38194b --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "architecture-docs"] + path = architecture-docs + url = ../architecture-docs.git + branch = main diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..60131fd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,26 @@ +# Project context + +`narada-python-sdk` is Narada's public Python SDK — a uv workspace with three packages (`narada`, `narada-core`, `narada-pyodide`) that lets external callers drive Narada agents programmatically. It's one of three sibling repos in the Narada system; shared cross-repo architecture lives in [`architecture-docs/`](./architecture-docs/) (a git submodule). + +## Before changing code, read + +- [`architecture-docs/CLAUDE.md`](./architecture-docs/CLAUDE.md) — rules for AI coding agents (read **first**) +- [`architecture-docs/overview.md`](./architecture-docs/overview.md) — 10-minute orientation across the three-repo system +- [`architecture-docs/python-sdk.md`](./architecture-docs/python-sdk.md) — workspace layout, parity rule, public types (this repo) +- [`architecture-docs/api-contracts.md`](./architecture-docs/api-contracts.md) — `/remote-dispatch`, `/extension-actions`, and other endpoints this SDK calls +- [`architecture-docs/conventions.md`](./architecture-docs/conventions.md) — naming, code style +- Other docs in `architecture-docs/` for backend / browser-automation / agent-studio context + +## When to update the docs + +When you change a public type, add a new SDK action, change the wire shape between SDK and backend, or change the parity rule between `narada` and `narada-pyodide` — update `architecture-docs/python-sdk.md` (and `api-contracts.md` if a wire shape moved) **in the same PR**. The full trigger list is in `architecture-docs/CLAUDE.md` §3. + +## Updating the submodule pointer + +```bash +git submodule update --remote architecture-docs +git add architecture-docs +git commit -m "Bump architecture-docs" +``` + +CI runs a freshness check (`.github/workflows/architecture-docs-freshness.yml`) that fails when the submodule pointer falls behind `architecture-docs/main`. diff --git a/architecture-docs b/architecture-docs new file mode 160000 index 0000000..d2a82e1 --- /dev/null +++ b/architecture-docs @@ -0,0 +1 @@ +Subproject commit d2a82e1c76af3e702a13cd760f39af02bdf2bc0e From 7aa521a640e87571e97d257c856890cdb3f8bcb1 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 14:50:58 -0700 Subject: [PATCH 02/11] fix: make architecture docs freshness explicit --- .../workflows/architecture-docs-freshness.yml | 32 +++++++++++++++++-- CLAUDE.md | 8 +++++ 2 files changed, 37 insertions(+), 3 deletions(-) diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml index 60f78eb..485215b 100644 --- a/.github/workflows/architecture-docs-freshness.yml +++ b/.github/workflows/architecture-docs-freshness.yml @@ -6,6 +6,9 @@ on: push: branches: [main] +permissions: + contents: read + jobs: check-submodule-current: runs-on: ubuntu-latest @@ -17,13 +20,36 @@ jobs: - name: Compare pinned submodule SHA against architecture-docs/main env: GH_TOKEN: ${{ secrets.ARCHITECTURE_DOCS_READ_PAT }} + EVENT_NAME: ${{ github.event_name }} + ACTOR: ${{ github.actor }} + REPOSITORY: ${{ github.repository }} + PR_HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }} run: | set -euo pipefail + ENFORCE=true + SKIP_REASON="" + PR_HEAD_REPOSITORY="${PR_HEAD_REPOSITORY:-$REPOSITORY}" + + if [ "$EVENT_NAME" = "pull_request" ]; then + if [ "$PR_HEAD_REPOSITORY" != "$REPOSITORY" ]; then + ENFORCE=false + SKIP_REASON="fork pull_request runs do not receive ARCHITECTURE_DOCS_READ_PAT" + elif [ "$ACTOR" = "dependabot[bot]" ]; then + ENFORCE=false + SKIP_REASON="Dependabot pull_request runs do not receive normal Actions secrets" + fi + fi + if [ -z "${GH_TOKEN:-}" ]; then - echo "::warning::ARCHITECTURE_DOCS_READ_PAT secret is not configured. Skipping freshness check." - echo " Configure a fine-grained PAT with read access to NaradaAI/architecture-docs" - echo " and add it as the secret ARCHITECTURE_DOCS_READ_PAT in this repo." + if [ "$ENFORCE" = "true" ]; then + echo "::error::ARCHITECTURE_DOCS_READ_PAT is required to enforce architecture-docs freshness." + echo "Configure a fine-grained PAT with read access to NaradaAI/architecture-docs." + exit 1 + fi + + echo "::warning::Skipping architecture-docs freshness check: $SKIP_REASON." + echo "Trusted same-repo branches require ARCHITECTURE_DOCS_READ_PAT and fail closed when it is missing." exit 0 fi diff --git a/CLAUDE.md b/CLAUDE.md index 60131fd..3924dd9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,14 @@ `narada-python-sdk` is Narada's public Python SDK — a uv workspace with three packages (`narada`, `narada-core`, `narada-pyodide`) that lets external callers drive Narada agents programmatically. It's one of three sibling repos in the Narada system; shared cross-repo architecture lives in [`architecture-docs/`](./architecture-docs/) (a git submodule). +## Bootstrap shared docs + +If `architecture-docs/CLAUDE.md` is missing, initialize the shared docs before following the links below: + +```bash +git submodule update --init architecture-docs +``` + ## Before changing code, read - [`architecture-docs/CLAUDE.md`](./architecture-docs/CLAUDE.md) — rules for AI coding agents (read **first**) From 21d5ea99993dad93deea800b98dc92f809e36974 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 15:19:52 -0700 Subject: [PATCH 03/11] fix: soft-pass architecture docs check without token --- .../workflows/architecture-docs-freshness.yml | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml index 485215b..a2ac180 100644 --- a/.github/workflows/architecture-docs-freshness.yml +++ b/.github/workflows/architecture-docs-freshness.yml @@ -27,29 +27,25 @@ jobs: run: | set -euo pipefail - ENFORCE=true SKIP_REASON="" PR_HEAD_REPOSITORY="${PR_HEAD_REPOSITORY:-$REPOSITORY}" if [ "$EVENT_NAME" = "pull_request" ]; then if [ "$PR_HEAD_REPOSITORY" != "$REPOSITORY" ]; then - ENFORCE=false SKIP_REASON="fork pull_request runs do not receive ARCHITECTURE_DOCS_READ_PAT" elif [ "$ACTOR" = "dependabot[bot]" ]; then - ENFORCE=false SKIP_REASON="Dependabot pull_request runs do not receive normal Actions secrets" + else + SKIP_REASON="ARCHITECTURE_DOCS_READ_PAT is not configured for this repository yet" fi + else + SKIP_REASON="ARCHITECTURE_DOCS_READ_PAT is not configured for this repository yet" fi if [ -z "${GH_TOKEN:-}" ]; then - if [ "$ENFORCE" = "true" ]; then - echo "::error::ARCHITECTURE_DOCS_READ_PAT is required to enforce architecture-docs freshness." - echo "Configure a fine-grained PAT with read access to NaradaAI/architecture-docs." - exit 1 - fi - echo "::warning::Skipping architecture-docs freshness check: $SKIP_REASON." - echo "Trusted same-repo branches require ARCHITECTURE_DOCS_READ_PAT and fail closed when it is missing." + echo "This workflow enforces freshness only in runs that receive ARCHITECTURE_DOCS_READ_PAT." + echo "Configure a fine-grained PAT with read access to NaradaAI/architecture-docs to enable enforcement." exit 0 fi From 4d370020c84fd9e3259bb2bad5c1289b26068c61 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 16:07:31 -0700 Subject: [PATCH 04/11] fix: use absolute architecture docs submodule url --- .gitmodules | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitmodules b/.gitmodules index d38194b..348c52c 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "architecture-docs"] path = architecture-docs - url = ../architecture-docs.git + url = https://github.com/NaradaAI/architecture-docs.git branch = main From 5d6596bc18a6054d23eed10bc3bd2afbfa57a0bb Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 16:17:21 -0700 Subject: [PATCH 05/11] fix: use ssh architecture docs submodule url --- .gitmodules | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitmodules b/.gitmodules index 348c52c..4e76a34 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "architecture-docs"] path = architecture-docs - url = https://github.com/NaradaAI/architecture-docs.git + url = git@github.com:NaradaAI/architecture-docs.git branch = main From 2b67a8b8ce209e90431f2e5e361564c212d74c25 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 16:30:27 -0700 Subject: [PATCH 06/11] fix: finalize architecture docs workflow hardening --- .github/workflows/architecture-docs-freshness.yml | 12 ++++++------ .gitmodules | 2 +- CLAUDE.md | 2 ++ 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml index a2ac180..524f8da 100644 --- a/.github/workflows/architecture-docs-freshness.yml +++ b/.github/workflows/architecture-docs-freshness.yml @@ -19,7 +19,7 @@ jobs: - name: Compare pinned submodule SHA against architecture-docs/main env: - GH_TOKEN: ${{ secrets.ARCHITECTURE_DOCS_READ_PAT }} + GH_TOKEN: ${{ secrets.ARCHITECTURE_DOCS_READ_PAT || secrets.ALL_REPO_CHECKOUT_TOKEN }} EVENT_NAME: ${{ github.event_name }} ACTOR: ${{ github.actor }} REPOSITORY: ${{ github.repository }} @@ -32,20 +32,20 @@ jobs: if [ "$EVENT_NAME" = "pull_request" ]; then if [ "$PR_HEAD_REPOSITORY" != "$REPOSITORY" ]; then - SKIP_REASON="fork pull_request runs do not receive ARCHITECTURE_DOCS_READ_PAT" + SKIP_REASON="fork pull_request runs do not receive repository secrets" elif [ "$ACTOR" = "dependabot[bot]" ]; then SKIP_REASON="Dependabot pull_request runs do not receive normal Actions secrets" else - SKIP_REASON="ARCHITECTURE_DOCS_READ_PAT is not configured for this repository yet" + SKIP_REASON="ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN is not configured for this repository yet" fi else - SKIP_REASON="ARCHITECTURE_DOCS_READ_PAT is not configured for this repository yet" + SKIP_REASON="ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN is not configured for this repository yet" fi if [ -z "${GH_TOKEN:-}" ]; then echo "::warning::Skipping architecture-docs freshness check: $SKIP_REASON." - echo "This workflow enforces freshness only in runs that receive ARCHITECTURE_DOCS_READ_PAT." - echo "Configure a fine-grained PAT with read access to NaradaAI/architecture-docs to enable enforcement." + echo "This workflow enforces freshness only in runs that receive ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN." + echo "Configure one of those tokens with read access to NaradaAI/architecture-docs to enable enforcement." exit 0 fi diff --git a/.gitmodules b/.gitmodules index 4e76a34..2dfcd02 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "architecture-docs"] path = architecture-docs - url = git@github.com:NaradaAI/architecture-docs.git + url = ../../NaradaAI/architecture-docs.git branch = main diff --git a/CLAUDE.md b/CLAUDE.md index 3924dd9..79910a2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,6 +25,8 @@ When you change a public type, add a new SDK action, change the wire shape betwe ## Updating the submodule pointer +Merge shared documentation changes into `architecture-docs/main` first, then bump this repo's submodule pointer. CI enforces exact equality with `architecture-docs/main`. + ```bash git submodule update --remote architecture-docs git add architecture-docs From 3ec6ca1790e58bb39d2cd0c358d659968c56fcd1 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 16:46:35 -0700 Subject: [PATCH 07/11] fix: relax architecture docs freshness gating --- .../workflows/architecture-docs-freshness.yml | 26 +++++++++++++++++++ CLAUDE.md | 6 ++--- 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml index 524f8da..8cc3ebf 100644 --- a/.github/workflows/architecture-docs-freshness.yml +++ b/.github/workflows/architecture-docs-freshness.yml @@ -24,6 +24,7 @@ jobs: ACTOR: ${{ github.actor }} REPOSITORY: ${{ github.repository }} PR_HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }} + BASE_SHA: ${{ github.event.pull_request.base.sha }} run: | set -euo pipefail @@ -64,11 +65,36 @@ jobs: echo "Pinned: $PINNED" echo "Latest: $REMOTE" + POINTER_CHANGED=false + if [ "$EVENT_NAME" = "pull_request" ]; then + if [ -n "${BASE_SHA:-}" ]; then + if git cat-file -e "$BASE_SHA^{commit}" 2>/dev/null || git fetch --no-tags --depth=1 origin "$BASE_SHA"; then + BASE_PINNED=$(git ls-tree "$BASE_SHA" architecture-docs | awk '{print $3}') + echo "Base: ${BASE_PINNED:-none}" + if [ "$PINNED" != "$BASE_PINNED" ]; then + POINTER_CHANGED=true + fi + else + echo "::warning::Unable to fetch pull request base commit; treating the architecture-docs pointer as changed." + POINTER_CHANGED=true + fi + else + echo "::warning::Unable to determine pull request base SHA; treating the architecture-docs pointer as changed." + POINTER_CHANGED=true + fi + fi + if [ "$PINNED" = "$REMOTE" ]; then echo "architecture-docs submodule is at main HEAD." exit 0 fi + if [ "$EVENT_NAME" = "pull_request" ] && [ "$POINTER_CHANGED" = "false" ]; then + echo "::warning::architecture-docs submodule is stale, but this pull request does not change the pointer." + echo "Freshness is enforced when a pull request changes architecture-docs and on pushes to main." + exit 0 + fi + echo "::error::architecture-docs submodule is stale." echo "" echo "To bump the pointer:" diff --git a/CLAUDE.md b/CLAUDE.md index 79910a2..7dd30c1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,11 +21,11 @@ git submodule update --init architecture-docs ## When to update the docs -When you change a public type, add a new SDK action, change the wire shape between SDK and backend, or change the parity rule between `narada` and `narada-pyodide` — update `architecture-docs/python-sdk.md` (and `api-contracts.md` if a wire shape moved) **in the same PR**. The full trigger list is in `architecture-docs/CLAUDE.md` §3. +When you change a public type, add a new SDK action, change the wire shape between SDK and backend, or change the parity rule between `narada` and `narada-pyodide` — open the relevant docs change in `NaradaAI/architecture-docs` first. Merge that docs PR to `architecture-docs/main`, then bump this repo's `architecture-docs` submodule pointer in the code PR. The full trigger list is in `architecture-docs/CLAUDE.md` §3. ## Updating the submodule pointer -Merge shared documentation changes into `architecture-docs/main` first, then bump this repo's submodule pointer. CI enforces exact equality with `architecture-docs/main`. +Merge shared documentation changes into `architecture-docs/main` first, then bump this repo's submodule pointer. CI fails PRs that change the `architecture-docs` pointer to anything other than `architecture-docs/main`, and it fails pushes to `main` when the pointer is stale. Unrelated PRs whose pointer is unchanged only receive a freshness warning if `architecture-docs/main` has moved. ```bash git submodule update --remote architecture-docs @@ -33,4 +33,4 @@ git add architecture-docs git commit -m "Bump architecture-docs" ``` -CI runs a freshness check (`.github/workflows/architecture-docs-freshness.yml`) that fails when the submodule pointer falls behind `architecture-docs/main`. +CI runs a freshness check (`.github/workflows/architecture-docs-freshness.yml`) that enforces this paired-PR workflow without blocking unrelated PRs when only `architecture-docs/main` changed. From d00ec05d9bb046a08cddce512e7c239005ff12bf Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 16:57:58 -0700 Subject: [PATCH 08/11] fix: make architecture docs freshness warning safe --- .github/workflows/architecture-docs-freshness.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml index 8cc3ebf..2c344f5 100644 --- a/.github/workflows/architecture-docs-freshness.yml +++ b/.github/workflows/architecture-docs-freshness.yml @@ -56,10 +56,11 @@ jobs: exit 1 fi - REMOTE=$(gh api repos/NaradaAI/architecture-docs/git/refs/heads/main --jq '.object.sha') + REMOTE=$(gh api repos/NaradaAI/architecture-docs/git/refs/heads/main --jq '.object.sha' 2>/dev/null || true) if [ -z "$REMOTE" ]; then - echo "::error::Failed to read architecture-docs/main HEAD via gh api. Check the PAT scope." - exit 1 + echo "::warning::Unable to read architecture-docs/main with the available token; continuing without enforcing freshness." + echo "Configure ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN with read access to NaradaAI/architecture-docs to enable enforcement." + exit 0 fi echo "Pinned: $PINNED" From 71fe6ebfade9daaa205e368685f4512eaba5f7d1 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 17:08:25 -0700 Subject: [PATCH 09/11] fix: fail freshness on invalid configured token --- .github/workflows/architecture-docs-freshness.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml index 2c344f5..f2d4e89 100644 --- a/.github/workflows/architecture-docs-freshness.yml +++ b/.github/workflows/architecture-docs-freshness.yml @@ -58,9 +58,9 @@ jobs: REMOTE=$(gh api repos/NaradaAI/architecture-docs/git/refs/heads/main --jq '.object.sha' 2>/dev/null || true) if [ -z "$REMOTE" ]; then - echo "::warning::Unable to read architecture-docs/main with the available token; continuing without enforcing freshness." - echo "Configure ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN with read access to NaradaAI/architecture-docs to enable enforcement." - exit 0 + echo "::error::Failed to read architecture-docs/main with the configured token." + echo "Check that ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN has read access to NaradaAI/architecture-docs." + exit 1 fi echo "Pinned: $PINNED" From 606e597c808e262f97db923fa08dac1cf8c6cac1 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 17:23:25 -0700 Subject: [PATCH 10/11] fix: require docs token for pointer changes --- .../workflows/architecture-docs-freshness.yml | 37 +++++++++++-------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml index f2d4e89..7608783 100644 --- a/.github/workflows/architecture-docs-freshness.yml +++ b/.github/workflows/architecture-docs-freshness.yml @@ -43,28 +43,13 @@ jobs: SKIP_REASON="ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN is not configured for this repository yet" fi - if [ -z "${GH_TOKEN:-}" ]; then - echo "::warning::Skipping architecture-docs freshness check: $SKIP_REASON." - echo "This workflow enforces freshness only in runs that receive ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN." - echo "Configure one of those tokens with read access to NaradaAI/architecture-docs to enable enforcement." - exit 0 - fi - PINNED=$(git ls-tree HEAD architecture-docs | awk '{print $3}') if [ -z "$PINNED" ]; then echo "::error::No architecture-docs submodule pointer found in this commit." exit 1 fi - REMOTE=$(gh api repos/NaradaAI/architecture-docs/git/refs/heads/main --jq '.object.sha' 2>/dev/null || true) - if [ -z "$REMOTE" ]; then - echo "::error::Failed to read architecture-docs/main with the configured token." - echo "Check that ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN has read access to NaradaAI/architecture-docs." - exit 1 - fi - echo "Pinned: $PINNED" - echo "Latest: $REMOTE" POINTER_CHANGED=false if [ "$EVENT_NAME" = "pull_request" ]; then @@ -85,6 +70,28 @@ jobs: fi fi + if [ -z "${GH_TOKEN:-}" ]; then + if [ "$EVENT_NAME" = "pull_request" ] && [ "$POINTER_CHANGED" = "false" ]; then + echo "::warning::Skipping architecture-docs freshness check: $SKIP_REASON." + echo "This pull request does not change the architecture-docs pointer." + echo "Configure ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN with read access to NaradaAI/architecture-docs to enable freshness enforcement." + exit 0 + fi + + echo "::error::Cannot enforce architecture-docs freshness: $SKIP_REASON." + echo "This run changes architecture-docs or is a push to main, so a read token is required." + exit 1 + fi + + REMOTE=$(gh api repos/NaradaAI/architecture-docs/git/refs/heads/main --jq '.object.sha' 2>/dev/null || true) + if [ -z "$REMOTE" ]; then + echo "::error::Failed to read architecture-docs/main with the configured token." + echo "Check that ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN has read access to NaradaAI/architecture-docs." + exit 1 + fi + + echo "Latest: $REMOTE" + if [ "$PINNED" = "$REMOTE" ]; then echo "architecture-docs submodule is at main HEAD." exit 0 From 3459bc98b8bf12c78584214eabe384c93dfff6b7 Mon Sep 17 00:00:00 2001 From: xTRam1 Date: Thu, 30 Apr 2026 17:24:43 -0700 Subject: [PATCH 11/11] Revert "fix: require docs token for pointer changes" This reverts commit 606e597c808e262f97db923fa08dac1cf8c6cac1. --- .../workflows/architecture-docs-freshness.yml | 37 ++++++++----------- 1 file changed, 15 insertions(+), 22 deletions(-) diff --git a/.github/workflows/architecture-docs-freshness.yml b/.github/workflows/architecture-docs-freshness.yml index 7608783..f2d4e89 100644 --- a/.github/workflows/architecture-docs-freshness.yml +++ b/.github/workflows/architecture-docs-freshness.yml @@ -43,13 +43,28 @@ jobs: SKIP_REASON="ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN is not configured for this repository yet" fi + if [ -z "${GH_TOKEN:-}" ]; then + echo "::warning::Skipping architecture-docs freshness check: $SKIP_REASON." + echo "This workflow enforces freshness only in runs that receive ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN." + echo "Configure one of those tokens with read access to NaradaAI/architecture-docs to enable enforcement." + exit 0 + fi + PINNED=$(git ls-tree HEAD architecture-docs | awk '{print $3}') if [ -z "$PINNED" ]; then echo "::error::No architecture-docs submodule pointer found in this commit." exit 1 fi + REMOTE=$(gh api repos/NaradaAI/architecture-docs/git/refs/heads/main --jq '.object.sha' 2>/dev/null || true) + if [ -z "$REMOTE" ]; then + echo "::error::Failed to read architecture-docs/main with the configured token." + echo "Check that ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN has read access to NaradaAI/architecture-docs." + exit 1 + fi + echo "Pinned: $PINNED" + echo "Latest: $REMOTE" POINTER_CHANGED=false if [ "$EVENT_NAME" = "pull_request" ]; then @@ -70,28 +85,6 @@ jobs: fi fi - if [ -z "${GH_TOKEN:-}" ]; then - if [ "$EVENT_NAME" = "pull_request" ] && [ "$POINTER_CHANGED" = "false" ]; then - echo "::warning::Skipping architecture-docs freshness check: $SKIP_REASON." - echo "This pull request does not change the architecture-docs pointer." - echo "Configure ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN with read access to NaradaAI/architecture-docs to enable freshness enforcement." - exit 0 - fi - - echo "::error::Cannot enforce architecture-docs freshness: $SKIP_REASON." - echo "This run changes architecture-docs or is a push to main, so a read token is required." - exit 1 - fi - - REMOTE=$(gh api repos/NaradaAI/architecture-docs/git/refs/heads/main --jq '.object.sha' 2>/dev/null || true) - if [ -z "$REMOTE" ]; then - echo "::error::Failed to read architecture-docs/main with the configured token." - echo "Check that ARCHITECTURE_DOCS_READ_PAT or ALL_REPO_CHECKOUT_TOKEN has read access to NaradaAI/architecture-docs." - exit 1 - fi - - echo "Latest: $REMOTE" - if [ "$PINNED" = "$REMOTE" ]; then echo "architecture-docs submodule is at main HEAD." exit 0