Sync instruction files with tooling reality; fix strategy-doc drift

.github/copilot-instructions.md

@@ -35,7 +35,7 @@ The universal baseline is in `AGENTS.md`. This file restates the parts that matt
 
 ## Build, test, and dependencies
 
-- This repo currently has no build step, no package manager, and no test runner.
+- This repo has no build step and no package manager. Doc-quality checks run via `./scripts/check.sh` locally and the `doc-quality` workflow in CI.
 - Do not suggest installing or updating packages.
 - If code samples are added later, place them under `examples/` and include a runnable command in the same file.
 

AGENTS.md

@@ -52,7 +52,7 @@ Claude Code does not read this file natively; `CLAUDE.md` cross-references it vi
 
 Before declaring a change done:
 
-- [ ] Markdown lints clean if the project has a linter configured (none yet — add one if it lands).
+- [ ] `./scripts/check.sh` passes (file-length cap, Boundaries sections, markdownlint, offline link check, typos). CI runs the same tiers in `.github/workflows/doc-quality.yml`. In a repo without the runner, lint markdown with whatever linter the project configures.
 - [ ] All cross-references resolve. `grep -RIn '\](\./\|](docs/\|](\.github/' .` and confirm targets exist.
 - [ ] No secrets in the diff. `git diff --cached | grep -iE 'api[_-]?key|secret|token|password'` returns nothing.
 - [ ] Each new or edited rule is imperative and verifiable.
@@ -61,7 +61,7 @@ Before declaring a change done:
 
 ## Dev environment tips
 
-- This repo currently ships only markdown. There is no build step, no package manager, and no test runner.
+- This repo ships markdown plus doc-quality tooling. There is no build step and no package manager; validation runs through `./scripts/check.sh` locally and the `doc-quality` workflow in CI.
 - If code samples are added later, place them under `examples/` and include a runnable command in the same file.
 - Do not add dependencies unless a sample explicitly requires them.
 
@@ -128,6 +128,7 @@ When the user provides repos, guides, articles, or PDFs:
 - `BOOTSTRAP.md` — drop-in install commands and replace-before-use checklist for seeding a new repo.
 - `.github/workflows/*.yml` — repo-specific CI; not part of the bootstrap-template surface.
 - `.markdownlint.json` — tier-2 lint config; consumed by `markdownlint-cli2` locally and in CI.
+- `lychee.toml` — link-check config; excludes intentionally unreachable placeholder URLs (e.g., `<your-username>` in `BOOTSTRAP.md`).
 - `scripts/check.sh` — local runner that mirrors the CI tiers; auto-skips uninstalled tools.
 - `docs/ai-agent-coding-strategy.md` — human-facing strategy, not enforced as rules.
 - `docs/research-log.md` — observations vs. promoted rules.

CLAUDE.md

@@ -11,7 +11,7 @@ The cross-agent baseline lives in [`AGENTS.md`](./AGENTS.md). Read it first; the
 1. **Bootstrap source** for new projects — `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` are designed to drop into a fresh repo. See [`BOOTSTRAP.md`](./BOOTSTRAP.md).
 2. **Personal knowledge base** for AI and software-engineering practice — research observations live under `docs/`, with promoted rules in instruction files and descriptive notes in `docs/knowledge/`.
 
-This repo is not a product application. There is no build, no package manager, and no test runner. Edits are almost always markdown.
+This repo is not a product application. There is no build and no package manager; the doc-quality checks below are its test suite. Edits are almost always markdown.
 
 ## Architecture: layered instruction files
 
@@ -73,15 +73,15 @@ for f in AGENTS.md CLAUDE.md BOOTSTRAP.md \
 done
 ```
 
-The secrets, file-length, and Boundaries checks should print nothing. The cross-ref grep is informational — each line should point at an existing file; manually verify any new ones.
+The file-length and Boundaries checks should print nothing. The secrets and cross-ref greps are informational — instruction files legitimately contain words like "secret" in rules, so review hits rather than treating any output as failure.
 
 ### Tier 2 — markdown lint
 
 ```bash
 npx markdownlint-cli2 "**/*.md" "#node_modules"
 ```
 
-Configure via `.markdownlint.json` at the repo root. Suggested baseline:
+Configured via `.markdownlint.json` at the repo root:
 
 ```json
 {
@@ -101,7 +101,7 @@ lychee --offline '**/*.md'    # relative links only, fast
 lychee '**/*.md'              # adds external URL probes, network-bound
 ```
 
-Add `lychee.toml` to allowlist intentionally unreachable URLs (e.g., the `<your-username>` placeholder in `BOOTSTRAP.md`).
+`lychee.toml` at the repo root allowlists intentionally unreachable URLs (e.g., the `<your-username>` placeholder in `BOOTSTRAP.md`) so the weekly online run does not file false-positive issues.
 
 ### Tier 4 — spell check
 

README.md

@@ -33,13 +33,15 @@ Operating model for adding to the knowledge base:
 
 ## Current research sources
 
-The live, authoritative list lives in [`docs/source-repos.md`](./docs/source-repos.md) — 12 sources tracked at last count, each with status (`pending` / `extracted` / `promoted` / `rejected`), the practices we use them for, and a URL.
+The live, authoritative list lives in [`docs/source-repos.md`](./docs/source-repos.md) — every source carries a status (`pending` / `extracted` / `promoted` / `rejected`), the practices we use it for, and a URL.
 
 Highlights so far:
 
 - **Skill conventions** — Anthropic Agent Skills, `google/skills`, `bytedance/deer-flow`, `forrestchang/andrej-karpathy-skills`.
 - **Cross-agent baselines** — the `AGENTS.md` spec, `openai/codex` AGENTS.md, `alchaincyf/huashu-design`, `garrytan/gstack`, `SuperClaude-Org/SuperClaude_Framework`.
 - **Per-host instruction formats** — Anthropic Claude Code memory docs, GitHub Copilot custom instructions, `github/awesome-copilot`.
+- **Engineering methods** — Thoughtworks Structured-Prompt-Driven Development, Martin Fowler's Fragments on verification and harness engineering.
+- **Integration patterns** — `chenhg5/cc-connect` bridge-daemon and adapter conventions.
 
 Add new sources by following the [research handling workflow](./AGENTS.md#research-handling): row in `source-repos.md`, observation in `docs/research-log.md`, then promote stable practices.
 

docs/ai-agent-coding-strategy.md

@@ -25,19 +25,28 @@ Agents pick up different files. Place each rule at the narrowest layer that stil
 | Layer | File(s) | Loaded when | Use for |
 |---|---|---|---|
 | Universal baseline | `AGENTS.md` | Codex, Cursor, Aider, Jules, OpenHands sessions | Rules every agent should follow |
-| Claude project memory | `CLAUDE.md` | Every Claude Code session | Claude-specific addenda + `@AGENTS.md` import |
+| Claude project memory | `CLAUDE.md` | Every Claude Code session | Claude-specific addenda + cross-reference to `AGENTS.md` |
 | Claude path rules | `.claude/rules/*.md` with `paths:` frontmatter | When matching files are edited | Topic- or path-scoped Claude rules |
 | Copilot repo-wide | `.github/copilot-instructions.md` | Every Copilot interaction | Build, test, and PR rules for Copilot |
 | Copilot path rules | `.github/instructions/*.instructions.md` with `applyTo:` | When matching files are referenced | Tech- or path-scoped Copilot rules |
 | Skills | `SKILL.md` directories | On-demand when triggered | Reusable capability packages |
-| Human strategy | `docs/*.md` | Read by humans and on request by agents | Background, rationale, research |
+| Human strategy | `docs/*.md` (incl. `docs/knowledge/`) | Read by humans and on request by agents | Background, rationale, research, descriptive notes |
+
+## Single source, multi-host
+
+When the same content needs to reach multiple agents, keep one canonical source and emit several delivery files rather than maintaining parallel copies.
+
+- Pick one canonical file per topic. Examples: `AGENTS.md` for the cross-agent baseline; a `SKILL.md` body for a capability bundle.
+- Emit per-host delivery files that wrap or link to the canonical: `CLAUDE.md` cross-references `AGENTS.md`; `.github/copilot-instructions.md` restates the parts Copilot needs; `.cursor/rules/*.mdc` carries the same content for Cursor; a plugin manifest packages it for installable distribution.
+- Document two install paths for users: a structured install (plugin marketplace, package manager) and an append-mode file-drop (`curl -o CLAUDE.md <url>` for new repos, `curl <url> >> CLAUDE.md` for existing ones). See `BOOTSTRAP.md` for this repo's implementation.
+- When the canonical content changes, list the per-host files that must be updated alongside it. A pre-commit checklist or a CI grep for drift is the safety net.
 
 ## Minimum viable workflow
 
 For a new repo:
 
 1. Add `AGENTS.md` at the root.
-2. Add `CLAUDE.md` with `@AGENTS.md` at the top, plus Claude-specific addenda.
+2. Add `CLAUDE.md` that cross-references `AGENTS.md` at the top, plus Claude-specific addenda. A markdown link keeps the baseline out of always-loaded context; `@AGENTS.md` import embeds it — choose per context budget. This repo uses the link.
 3. Add `.github/copilot-instructions.md` with the same baseline restated for Copilot.
 4. Add `docs/source-repos.md` and `docs/research-log.md` if the project will study external sources.
 5. Validate by running each agent on a small task and reviewing whether the rules were honored.
@@ -81,20 +90,11 @@ See [`docs/knowledge/structured-prompt-driven-development.md`](./knowledge/struc
 ## Anti-patterns
 
 - Burying critical constraints inside long prose. Agents will skim past them.
-- Duplicating the same rule into every agent file. Use `@AGENTS.md` import or restate only what differs.
+- Duplicating the same rule into every agent file. Cross-reference the canonical file (link or `@AGENTS.md` import) and restate only what differs.
 - Treating exploratory research notes as mandatory rules. Keep `docs/research-log.md` separate.
 - Mixing project-specific examples into general agent rules.
 - Adding marketing language unless the file is explicitly a sales artifact.
 
-## Single source, multi-host
-
-When the same content needs to reach multiple agents, keep one canonical source and emit several delivery files rather than maintaining parallel copies.
-
-- Pick one canonical file per topic. Examples: `AGENTS.md` for the cross-agent baseline; a `SKILL.md` body for a capability bundle.
-- Emit per-host delivery files that wrap or link to the canonical: `CLAUDE.md` cross-references `AGENTS.md`; `.github/copilot-instructions.md` restates the parts Copilot needs; `.cursor/rules/*.mdc` carries the same content for Cursor; a plugin manifest packages it for installable distribution.
-- Document two install paths for users: a structured install (plugin marketplace, package manager) and an append-mode file-drop (`curl -o CLAUDE.md <url>` for new repos, `curl <url> >> CLAUDE.md` for existing ones).
-- When the canonical content changes, list the per-host files that must be updated alongside it. A pre-commit checklist or a CI grep for drift is the safety net.
-
 ## How rules graduate
 
 ```text
@@ -116,5 +116,7 @@ Source row in source-repos.md updated to Status = promoted
 - `CLAUDE.md` — Claude Code project memory.
 - `.github/copilot-instructions.md` — repo-wide Copilot rules.
 - `.github/instructions/azure-ai.instructions.md` — Azure-specific Copilot rules.
+- `BOOTSTRAP.md` — drop-in install for new repos.
 - `docs/source-repos.md` — tracked sources.
 - `docs/research-log.md` — observations and promoted rules.
+- `docs/knowledge/` — descriptive notes the practical examples link to.

lychee.toml

@@ -0,0 +1,9 @@
+# Link-check config for lychee (tier 3 locally, doc-quality + weekly online runs in CI).
+# Exclude intentionally unreachable URLs so the weekly online run does not file
+# false-positive "Link Checker Report" issues.
+
+exclude = [
+  # Placeholder install URL in BOOTSTRAP.md; users substitute their own account.
+  'raw\.githubusercontent\.com/<your-username>',
+  '<your-username>',
+]

scripts/check.sh

@@ -28,6 +28,14 @@ if [ -n "$missing" ]; then
   fail=1
 fi
 
+# Secrets scan over the staged diff. Informational, not a hard fail: rule files
+# legitimately contain words like "secret" — review hits, don't auto-block.
+# Cross-reference resolution is tier 3's job (lychee --offline).
+hits=$(git diff --cached | grep -iE 'api[_-]?key|secret|token|password' || true)
+if [ -n "$hits" ]; then
+  printf 'i  Secret-pattern matches in staged diff (review, not necessarily a failure):\n%s\n' "$hits"
+fi
+
 printf '\n** Tier 2 — markdownlint\n'
 if command -v npx >/dev/null 2>&1; then
   npx --yes markdownlint-cli2 "**/*.md" "#node_modules" || fail=1