docs(governance): ratify organization policy and patterns

.github/agents/github-actions-expert.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "GitHub Actions Expert"
 description: "GitHub Actions specialist focused on secure CI/CD workflows, action pinning, OIDC authentication, permissions least privilege, and supply-chain security"
-tools: [vscode, execute, read/readFile, agent, 'github/*', 'io.github.upstash/context7/*', 'github-ghas-tools/*', edit/editFiles, search, todo]
+tools: [clarify, execute, read/readFile, agent, 'github/*', 'context7/*', 'github-ghas-tools/*', edit/editFiles, search, todo]
 ---
 
 # GitHub Actions Expert

.github/agents/memory-curator.agent.md

@@ -21,6 +21,23 @@ You manage two storage tiers:
 - Do not create new memory files inside `repos/org/z-shell-dot-github/memory/` — that directory was removed; write to the meta-workspace `memory/` only.
 - After editing any local memory file (except `user-profile.md`), always sync it to the Gist.
 
+## Content Guidelines (What to Memorize)
+Memory must be extremely high-signal, compact, and durable.
+
+- **DO SAVE:**
+  - **Organizational Heuristics:** Hard rules about file placement, AI usage, or repo boundaries (e.g., "Never use zdharma-continuum").
+  - **Architectural Decisions:** Crucial setups that span the workspace (e.g., "Secrets are loaded via env.secrets.sh chmod 600").
+  - **Cross-Repo Conventions:** Preferred frameworks, mandatory linting rules, or standardized paths.
+  - **User Feedback & Corrections:** Explicit negative feedback ("Don't do X again") or preferences.
+
+- **DO NOT SAVE (Transient Data):**
+  - Task progress, completed-work logs, or session outcomes.
+  - Specific PR numbers, issue numbers, or commit SHAs (unless documenting a permanently closed historical chapter).
+  - Temporary TODO state or next steps for a project.
+  - Artifacts that will be stale in a week.
+
+*If an insight is procedural (a sequence of commands to accomplish a task), it belongs in a shared script or skill, not memory. Keep memory declarative.*
+
 ## Approach
 
 ### Saving a new insight

.github/agents/workspace-architect.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Workspace Architect"
 description: "Use when organizing the Z-Shell multi-repo workspace, updating agent instructions, enforcing privacy boundaries (hooks), or curating meta-workspace memory."
-tools: [read, edit, search, execute, vscode_askQuestions]
+tools: [read, edit, search, execute, clarify]
 user-invocable: true
 ---
 You are the **Z-Shell Workspace Architect**, a specialized agent responsible for maintaining the organization's multi-repo meta-workspace layout, privacy constraints, and AI orchestration instructions.

.github/copilot-instructions.md

@@ -0,0 +1 @@
+../AGENTS.md

.github/instructions/context-engineering.instructions.md

@@ -21,7 +21,7 @@ Principles for helping GitHub Copilot understand your codebase and provide bette
 
 ## Working with Copilot
 
-- **Keep relevant files open in tabs**: Copilot uses open tabs as context signals. Working on auth? Open auth-related files.
+- **Provide explicit file context**: If using a CLI agent or non-IDE assistant, provide explicit file paths. If using an IDE assistant, keep relevant files open in tabs. Working on auth? Reference or open auth-related files.
 - **Position cursor intentionally**: Copilot prioritizes code near your cursor. Put cursor where context matters.
 - **Use Copilot Chat for complex tasks**: Inline completions have minimal context. Chat mode sees more files.
 

.github/instructions/documentation.instructions.md

@@ -0,0 +1,58 @@
+---
+description: "Where documentation lives across z-shell repos and the wiki content-root boundaries"
+applyTo: "**"
+---
+
+# Documentation Instructions
+
+Where a piece of documentation belongs, and the wiki's content-root rules. This
+operationalizes `decisions/0006-wiki-content-root-boundaries.md` and the
+org-wide documentation policy.
+
+## Default home: the wiki
+
+Durable, long-form documentation belongs in `z-shell/wiki` whenever practical.
+Keep individual repos lean by linking to wiki pages instead of duplicating
+guidance. Repo-local docs are justified only when tightly coupled to that repo's
+source, release process, or contributor workflow.
+
+When a repo-local copy is unavoidable, prefer a generated or synchronized file
+sourced from the wiki so maintenance stays centralized and drift is minimized.
+
+## Wiki content-root boundaries (ADR-0006)
+
+The wiki has three independent content roots. Place content by audience and
+purpose, not by topic:
+
+- **`docs/`** — Zi **end-user** documentation: getting started, usage, guides for
+  people *using* the tools.
+- **`community/`** — community-facing material: standards, contribution norms,
+  ecosystem-wide conventions.
+- **`ecosystem/`** — ecosystem catalog: plugins, annexes, and related projects.
+
+Maintainer/operational guides are **not** end-user docs — do not place them under
+`docs/` just because they concern the tools.
+
+### Hard rules
+
+- Do not create a duplicate of the same page across two content roots. A page has
+  one canonical home; link to it from elsewhere.
+- When "moving" a page between roots, reconcile content rather than copying
+  verbatim — the ADR-0006 failure was a literal move that would have shipped
+  stale secret-key naming. Verify the moved copy matches current code/config.
+- Never commit secret values or stale secret-key names in docs; reference the
+  current canonical names only.
+
+## LLM/agent files
+
+Per the workspace LLM file-placement policy, keep generic agent instructions
+centralized in the meta-workspace root or `z-shell/.github`. Child repos keep
+`AGENTS.md` / `.github/instructions/` only for repo-specific workflows that
+cannot be expressed centrally, and those should link back rather than repeat
+shared policy.
+
+## See also
+
+- `decisions/0006-wiki-content-root-boundaries.md`
+- `repos/docs/wiki/.github/copilot-instructions.md` (wiki-local authoring rules)
+- `repos/docs/wiki/.github/instructions/docs-authoring.instructions.md`

.github/instructions/mcp-plugins.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: "When and how to use the project MCP plugins (Context7, Cloudflare, Greptile) and Claude Code toolkits (pr-review-toolkit, hookify, security-guidance) across the Z-Shell workspace."
+description: "When and how to use the project MCP plugins (Context7, Cloudflare, Greptile) and CLI Agent toolkits (pr-review-toolkit, hookify, security-guidance) across the Z-Shell workspace."
 applyTo: "**"
 ---
 
@@ -44,9 +44,9 @@ maintainer workspace. Prefer these over guesswork or generic web search.
 - **When NOT to use:** single-file lookups where local grep or Read is faster.
 - **Auth required:** yes (OAuth). Read-only.
 
-## Claude Code toolkits
+## CLI Agent toolkits
 
 - **pr-review-toolkit:** reviewer, silent-failure, type-design, test, and
   comment subagents. Run on a diff before requesting human review.
-- **hookify:** generate Claude Code hooks from recurring conversation mistakes.
+- **hookify:** generate CLI hooks/heuristics from recurring conversation mistakes.
 - **security-guidance:** security review of pending changes before merge.

.github/instructions/testing.instructions.md

@@ -0,0 +1,65 @@
+---
+description: "Testing and CI expectations for z-shell repositories, by repository class"
+applyTo: "**"
+---
+
+# Testing Instructions
+
+How much to test, and what CI to require, depends on the repository's class.
+This operationalizes `decisions/0009-testing-ci-strategy.md`; the class
+definitions come from `decisions/0007-release-publication-flow.md`.
+
+## Identify the class first
+
+| Class | Repos                                   | What it is                       |
+| ----- | --------------------------------------- | -------------------------------- |
+| 1     | `wiki`, `src`, `zd`                     | Continuously deployed artifact   |
+| 2     | `zunit`, `zsh-lint`, packaged `zsh`     | Versioned tool/package           |
+| 3     | `zi`, most plugins/annexes              | Git-consumed source              |
+| 4     | `.github`                               | Meta/infrastructure              |
+
+## Baseline (every repo)
+
+- Workflows follow org conventions: SHA-pinned actions, top-level
+  least-privilege `permissions:`, `concurrency:` on push/PR, no-emoji workflow/
+  job `name:` (ADR-0005), kebab-case filenames.
+- Zsh sources pass `zsh -n` and `zcompile`.
+- Conventional Commits (ADR-0003) and the disallowed-trailer check are enforced.
+
+## By class
+
+- **Class 1 — deployed:** the build must pass on the development branch before
+  deploy. Wiki: ESLint + Stylelint + production build. `zd`: Docker build matrix.
+  `src`: installer/loader validation. Add CodeQL where a supported language exists.
+- **Class 2 — versioned tools:** a **full functional suite is required and gates
+  release tags**. ZUnit for Zsh tools; `go test` for the `zsh-lint` Go CLI. Never
+  cut a `vX.Y.Z` tag from a red commit.
+- **Class 3 — git-consumed:** **validation-only.** Baseline checks plus ZUnit
+  where the plugin ships tests. No release automation, no coverage gate. The bar
+  is "loads and parses cleanly."
+- **Class 4 — meta:** baseline plus workflow/markdown linting.
+
+## Coverage
+
+Coverage is **observed, not gated**, unless a class-2 tool sets its own threshold.
+Do not add an org-wide coverage number.
+
+## Writing Zsh tests
+
+- Use ZUnit; keep one behavior per test.
+- Test by sourcing the plugin in a clean Zsh session — there is no build step.
+- For annex/handler functions, assert side effects are reversed by the unload
+  function (`<plugin>_plugin_unload`).
+
+## Required checks
+
+Mark the class-appropriate checks as required for merge to the publication branch
+(`main`, or `next`→`main` per ADR-0008). Class-3 repos require the baseline;
+class-2 repos additionally require the functional suite before a release tag.
+
+## See also
+
+- `decisions/0009-testing-ci-strategy.md`
+- `decisions/0007-release-publication-flow.md`
+- `.github/instructions/github-actions-ci-cd-best-practices.instructions.md`
+- `.github/instructions/shell.instructions.md`

.github/workflows/activity_metrics.yml

@@ -11,15 +11,16 @@ on:
 
 permissions: {}
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   metrics-activity:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
       contents: write
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.ref }}
-      cancel-in-progress: true
     env:
       projects_svg: metrics/plugin/projects/projects.svg
       org-people_svg: metrics/plugin/people/org-people.svg

.github/workflows/dependency-review.yml

@@ -1,6 +1,10 @@
 ---
 name: Dependency Review
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   workflow_call: {}
 

.github/workflows/gh-deploy-assets.yml

@@ -9,15 +9,16 @@ on:
 
 permissions: {}
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
     environment: github-pages
     permissions:
       contents: write
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
-      cancel-in-progress: true
     steps:
       - name: "⤵️ Check out code from GitHub"
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

.github/workflows/lychee.yml

@@ -22,15 +22,16 @@ on:
 
 permissions: {}
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   links-check:
     runs-on: ubuntu-latest
     permissions:
       contents: read
       issues: write
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.ref }}
-      cancel-in-progress: true
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: "📤 Restore cache"

.github/workflows/metrics.yml

@@ -11,16 +11,17 @@ on:
 
 permissions: {}
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   metrics:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     environment: metrics
     permissions:
       contents: write
-    concurrency:
-      group: ci-${{ github.workflow }}-${{ github.ref }}
-      cancel-in-progress: true
     env:
       metrics_svg: metrics/plugin/metrics.svg
       repositories_metrics_svg: metrics/plugin/repositories_metrics.svg

.github/workflows/pages-deployment.yml

@@ -8,6 +8,10 @@ on:
 
 permissions: {}
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   deploy:
     name: Deploying
@@ -17,9 +21,6 @@ jobs:
     permissions:
       contents: read
       deployments: write
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
-      cancel-in-progress: true
     steps:
       - name: "⤵️  Check out code from GitHub"
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

.github/workflows/pagespeed.yml

@@ -10,15 +10,16 @@ on:
 
 permissions: {}
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   pagespeed:
     runs-on: ubuntu-latest
     permissions:
       contents: write
     timeout-minutes: 30
-    concurrency:
-      group: pagespeed-${{ github.ref }}
-      cancel-in-progress: true
     env:
       pagespeed_svg: metrics/plugin/pagespeed/detailed.svg
       pagespeed_url: ${{ secrets.PAGESPEED_TEST_URL }}

.github/workflows/reader.yml

@@ -11,15 +11,16 @@ on:
 
 permissions: {}
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   content-metrics:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     permissions:
       contents: write
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.ref }}
-      cancel-in-progress: true
     env:
       zsh_activity_svg: metrics/plugin/rss/zsh/activity.svg
       zsh_activity_url: https://sourceforge.net/p/zsh/activity/feed

.github/workflows/trunk.yml

@@ -1,6 +1,10 @@
 ---
 name: Trunk Code Quality
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   workflow_call:
     secrets:

.github/workflows/zsh-ci.yml

@@ -32,7 +32,7 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Zsh
-        uses: z-shell/.github/actions/setup-zsh@main
+        uses: z-shell/.github/actions/setup-zsh@48e314c59d04b54ae7f05d57570845f1a11a286a # main
         with:
           version: ${{ inputs.zsh-version }}
 

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

GEMINI.md

@@ -0,0 +1 @@
+AGENTS.md