From 317bb3b4ea72cbb797f69a4b7cf075eb2ce12fb1 Mon Sep 17 00:00:00 2001
From: Gergo Magyar <gergomagyar@icloud.com>
Date: Sun, 14 Jun 2026 09:05:42 +0000
Subject: [PATCH] fix(ci-setup): correct false GITNEXUS.md / workflow claims
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two generated-doc claims were false:
- "stale-index PRs are blocked at CI" — the step only checks that
  .gitnexus/meta.json exists, which the preceding analyze just
  regenerated, so it never detects staleness and blocks nothing. Reword
  to say it only fails when analyze produced no output, and rename the
  step from "Check index staleness" to "Verify index was produced" in
  both the GitHub Actions and Azure pipeline templates.
- "skill files are written into the repository by the CI workflow" — the
  workflow runs with `permissions: contents: read` and has no commit
  step, so the files are discarded with the runner. State plainly they
  are not auto-committed and that persisting them needs a commit step
  plus `contents: write`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 gitnexus/src/cli/ci-setup/templates.ts        | 11 ++++----
 gitnexus/test/unit/ci-setup-templates.test.ts | 28 +++++++++++++++++++
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/gitnexus/src/cli/ci-setup/templates.ts b/gitnexus/src/cli/ci-setup/templates.ts
index 94072f944..382f88368 100644
--- a/gitnexus/src/cli/ci-setup/templates.ts
+++ b/gitnexus/src/cli/ci-setup/templates.ts
@@ -67,7 +67,7 @@ jobs:
           path: .gitnexus/
           retention-days: 30
 
-      - name: Check index staleness
+      - name: Verify index was produced
         run: |
           if [ -f .gitnexus/meta.json ]; then
             echo "✓ GitNexus index updated at $(date -u +%Y-%m-%dT%H:%M:%SZ)"
@@ -129,7 +129,7 @@ steps:
       else
         echo "✗ GitNexus index not found" && exit 1
       fi
-    displayName: 'Check index staleness'
+    displayName: 'Verify index was produced'
 `;
 }
 
@@ -495,7 +495,7 @@ When the CI workflow runs \`analyze --skills\`, GitNexus generates repo-specific
 - \`.claude/skills/gitnexus/\` — standard GitNexus MCP skills (query, impact, context, detect-changes)
 - \`.claude/skills/generated/\` — community-detected area skills (one file per functional cluster)
 
-These are written into the repository by the CI workflow. To share them with your team, add a \`git add .claude/skills/ && git commit\` step after \`analyze --skills\` in your workflow, or commit them manually after the first run.
+The CI workflow generates these on the runner but does **not** commit them — it runs with \`permissions: contents: read\`. To share them with your team, commit them manually after a run, or add a \`git add .claude/skills/ && git commit && git push\` step to the workflow (which also requires granting it \`permissions: contents: write\`).
 
 ---
 
@@ -503,8 +503,9 @@ These are written into the repository by the CI workflow. To share them with you
 
 The CI workflow uploads the \`.gitnexus/\` directory as a workflow artifact (30-day retention) on every run.
 If the index is stale (CI hasn't run since the last push), Claude Code will still function but may operate
-on a slightly outdated graph. The staleness check step in the workflow fails the run if indexing produced
-no output, so stale-index PRs are blocked at CI.
+on a slightly outdated graph. The "Verify index was produced" step fails the run only if \`analyze\`
+produced no output — it does not compare the index against the current commit, so it does not detect
+or block stale-index PRs.
 
 > **The wizard does not automate index delivery to the shared server.** CI uploads \`.gitnexus/\` as a
 > workflow artifact; the running server reads its own persistent volume, and nothing connects the two
diff --git a/gitnexus/test/unit/ci-setup-templates.test.ts b/gitnexus/test/unit/ci-setup-templates.test.ts
index 94d4dbe07..c95ea84de 100644
--- a/gitnexus/test/unit/ci-setup-templates.test.ts
+++ b/gitnexus/test/unit/ci-setup-templates.test.ts
@@ -57,6 +57,34 @@ describe('GITNEXUS.md index delivery (U7)', () => {
   });
 });
 
+describe('GITNEXUS.md / workflow accuracy (U8)', () => {
+  function workflow(overrides?: Partial<CiSetupOptions>): string {
+    const files = generateFiles(makeOpts(overrides), DEFAULT_DETECT);
+    const wf = files.find((f) => f.relativePath === '.github/workflows/gitnexus-ci.yml');
+    if (!wf) throw new Error('workflow not generated');
+    return wf.content;
+  }
+
+  it('drops the false "stale-index PRs are blocked at CI" claim', () => {
+    const content = gitnexusMd();
+    expect(content).not.toContain('stale-index PRs are blocked at CI');
+    expect(content).toContain('does not detect');
+  });
+
+  it('renames the misleading "Check index staleness" workflow step', () => {
+    const content = workflow();
+    expect(content).not.toContain('Check index staleness');
+    expect(content).toContain('Verify index was produced');
+  });
+
+  it('is honest that skills are not auto-committed (contents: read)', () => {
+    const content = gitnexusMd();
+    expect(content).not.toContain('written into the repository by the CI workflow');
+    expect(content).toContain('does **not** commit them');
+    expect(content).toContain('contents: write');
+  });
+});
+
 describe('generateFiles', () => {
   describe('GitHub Actions workflow', () => {
     it('generates with correct port in healthcheck', () => {