track: ignore-vendored-docs-20260408

[amondnet]

---

product_spec_domain: cli/ignore-management

Vendored Docs Ignore Management

Track: ignore-vendored-docs-20260408

Overview

The ask docs add command marks .ask/docs/ as vendored third-party documentation, achieving two goals simultaneously:

1. AI agents must still be able to read it (ASK's core value — docs are for reference)
2. Excluded from lint / format / code review / modification (because it's vendored)

To accomplish this, ASK (A) creates self-contained config files inside .ask/docs/, (B) injects an intent notice into ASK marker blocks in AGENTS.md/CLAUDE.md, and (C) patches root files only for tools that do not support nested ignore.

Requirements

Functional Requirements

A. Self-contained local config (created inside .ask/docs/)

• FR-A1: Create .ask/docs/.gitattributes — * linguist-vendored=true + * linguist-generated=true (collapses GitHub PR diffs + excludes from language statistics).
• FR-A2: Create .ask/docs/eslint.config.mjs — export default [{ ignores: ['**/*'] }] (ESLint flat config auto-discovers nested configs).
• FR-A3: Create .ask/docs/biome.json — exclude all files from processing (Biome auto-discovers nested configs).
• FR-A4: Create .ask/docs/.markdownlint-cli2.jsonc — { "ignores": ["**/*"] } (markdownlint-cli2 supports nested config).

B. Intent notice (inside ASK marker block in AGENTS.md / CLAUDE.md)

• FR-B1: Auto-inject the following notice inside an ASK-managed marker block (<!-- ask:start --> ... <!-- ask:end -->):

  .ask/docs/ contains vendored third-party documentation downloaded by ASK. Treat it as read-only: AI context should reference these files, but they are NOT subject to modification, lint, format, or code review. Updates are performed via ask docs sync.

• FR-B2: If AGENTS.md exists, inject into AGENTS.md. If CLAUDE.md exists, inject into CLAUDE.md. If both exist, inject into both. If neither exists, create AGENTS.md (standard preference).
• FR-B3: This single notice transitively affects the following AI tools (verified): CodeRabbit, cubic, Claude Code, Codex, Cursor (rules), GitHub Copilot, Continue, Aider, etc.

C. Root file patching (only for tools without nested support, only if detected)

• FR-C1: If root .prettierignore exists, add .ask/docs/ exclusion patterns inside a marker block. (Prettier does not support nested ignore.)
• FR-C2: If root sonar-project.properties exists, append .ask/docs/** to sonar.exclusions inside a marker block.
• FR-C3: If root legacy .markdownlintignore (markdownlint-cli legacy) exists, add .ask/docs/ inside a marker block. Also emit a recommendation to migrate to markdownlint-cli2.
• FR-C4: Do not create these files if absent — patch only when detected.

D. Marker block management

• FR-D1: Injection format follows each file's comment syntax. Properties/ignore files: # <!-- ask:start --> ... # <!-- ask:end -->. Markdown: <!-- ask:start --> ... <!-- ask:end -->. Properties (FR-C2): # ask:start ... # ask:end.
• FR-D2: Idempotent: running add repeatedly does not duplicate marker blocks; only the contents inside are refreshed.
• FR-D3: ask docs sync refreshes marker blocks. When ask docs remove removes the last docs entry, ASK deletes the local config files in (A) and removes the marker blocks in (B) and (C). Empty blocks are not left behind.
• FR-D4: ASK never modifies user content outside marker blocks.

E. Configuration and logging

[amondnet]

Implementation Complete

PR #26 — Ready for Review

Summary

Marks .ask/docs/ as vendored third-party documentation so lint/format/code-review tools skip it while keeping the directory readable as AI context.

• (A) Self-contained nested configs inside .ask/docs/ — .gitattributes, eslint.config.mjs, biome.json, .markdownlint-cli2.jsonc
• (B) Vendored notice in AGENTS.md auto-generated block (covers CodeRabbit, cubic, Claude Code, Cursor, etc.)
• (C) Marker-block patches for .prettierignore and sonar-project.properties (only when present)

ConfigSchema gains optional manageIgnores flag (default true).

199 tests pass, 0 fail; lint clean.