feat(docs): design doc + implementation plan convention (closes #67 phase-1)

[Wolfvin]

Closes #67 (Phase 1 only)

Summary

Adds Phase 1 of issue #67: a docs convention that requires feature-class PRs to include a design doc and an implementation plan, enforced by CI.

Phase 2 (VitePress homepage at codelens.dev) and Phase 3 (live demo with interactive dashboard) remain open — they are multi-week content projects tracked in #67.

What's new

Templates + guides

• docs/design/template.md — Problem / Goal / Changes / Trade-offs / Open Questions / Findings sections.
• docs/plans/template.md — phase-based implementation checklist with acceptance criteria, test strategy, rollout, risks.
• docs/design/README.md, docs/plans/README.md — usage guides for both directories.

Backfilled design docs (4 — exceeds the 3+ acceptance criterion)

• docs/design/taint-engine.md — AST taint analysis (issue [FEATURE] Taint analysis depth — unified cross-file engine + persistence + library approximation + debug trace #49 / PR feat(taint): consolidate cross-file engine into ast_taint_engine + deprecate semantic_engine (closes #49 phase-1) #140)
• docs/design/mcp-server.md — MCP server architecture (61 tools, JSON-RPC over stdio)
• docs/design/plugin-system.md — Plugin system (4 plugin types, 3-tier discovery)
• docs/design/graph-model.md — SQLite graph model (v8.2: graph_nodes + graph_edges)

These are backfills for features that shipped before this convention existed. Each follows the template structure (Problem, Goal, Changes, Trade-offs, Open Questions, Findings) and is grounded in the actual source code.

CI check

• scripts/check_design_doc.py — the actual check logic. Pure functions + a thin CLI entry point. A PR adding any new file matching:

  • scripts/commands/<name>.py (new CLI command)
  • scripts/parsers/<name>_parser.py (new tree-sitter parser)
  • scripts/<name>_engine.py (new top-level engine)
  • scripts/mcp_hooks/<name>.py (new MCP hook)

  MUST also add at least one new .md under docs/design/ AND one under docs/plans/. template.md and README.md do NOT count.

• .github/workflows/require-design-doc.yml — runs the check on PR opened / synchronize / reopened / labeled / unlabeled. Posts a comment on failure explaining how to fix.

Exemptions

PRs labeled skip-design-doc, bug, chore, dependencies, refactor, documentation, or test are exempt. PRs that do not add any feature-class file are also exempt (no-op).

Docs update

• CONTRIBUTING.md — new 'Design Documents & Implementation Plans' section under 'How Can I Contribute?'. The 'Adding New Parsers or Engines' checklist now includes a step 3: 'Write a design doc'.
• CHANGELOG.md — entry under [8.2.0] — Unreleased.

Tests

• tests/test_check_design_doc.py — 37 tests:
  • TestIsFeatureClass — 12 tests covering the feature-class file regex (commands, parsers, engines, mcp_hooks; __init__.py exemptions; fallback parsers; subpackage files).
  • TestIsDesignOrPlanDoc — 8 tests covering doc detection (correct dir, wrong dir, non-md, template/README exclusion).
  • TestEvaluate — 10 tests covering the policy logic (no-feature pass, both-docs pass, missing-design fail, missing-plan fail, missing-both, exemption labels, case-insensitive labels, template-only does not satisfy).
  • TestEndToEndWithGit — 4 tests creating a real temp git repo, committing files on a branch, and invoking the script as a subprocess.

Acceptance criteria check

From issue #67 Phase 1:

• docs/design/ and docs/plans/ directories exist with templates
• CI check fails PR without design doc for new feature
• 3+ existing features backfilled with design docs (4 backfilled: taint-engine, mcp-server, plugin-system, graph-model)

(Phase 2 and Phase 3 acceptance criteria are out of scope for this PR.)

Tests

• tests/test_check_design_doc.py: 37 passed, 0 failed
• Baseline (tests that don't require tree-sitter / LSP): 167 passed, 0 failed
  • test_check_design_doc.py, test_command_count.py, test_cli.py, test_formatters.py, test_doctor.py, test_version_consistency.py
• Pre-existing collection errors in test_rule_engine.py, test_rule_matcher.py, test_lsp_server.py are environment-driven (missing tree-sitter / LSP in sandbox), NOT regressions — see CONTEXT.md.

Self-check

The new CI check correctly identifies THIS PR as compliant:

$ python3 scripts/check_design_doc.py --base origin/main --head HEAD
[check_design_doc] No feature-class files added — pass.

(scripts/check_design_doc.py does not match any feature-class pattern — it's a CI helper, not a new command/parser/engine/mcp_hook. So this PR is correctly exempt.)

Findings (per pre-flight SKILL.md)

• Issue [FEATURE] Homepage + design doc process — VitePress site + docs/design/ + docs/plans/ convention #67 had one spam comment from raranosonu58 linking to a malicious .apk file (vitepress_patch_v2.apk hosted at github.com/keracocobe/123/releases/download/update/module.apk). This is NOT a taking comment. Suggest BOS delete the spam comment and block the user.
• The issue acceptance criteria mention 'CI check via GitHub Action: PR adding new feature (detected by file pattern) must include design + plan'. I implemented this with a file-pattern check (not a label check) because labels are applied after PR creation and could be missed. The skip-design-doc label is the only override.
• Phase 2 mentions deploying via GitHub Pages or Cloudflare Pages — both would require a homepage/ directory that does not exist yet. This is out of scope for Phase 1.

Related

• Issue: [FEATURE] Homepage + design doc process — VitePress site + docs/design/ + docs/plans/ convention #67
• Skill files consulted: _skills/pre-flight/SKILL.md, _skills/issue-workflow/SKILL.md, _skills/context-snapshot/CodeLens/CONTEXT.md
• Follow-up: Phase 2 (VitePress homepage) and Phase 3 (live demo) remain open in [FEATURE] Homepage + design doc process — VitePress site + docs/design/ + docs/plans/ convention #67
• A separate PR to Wolfvin/worker-skills will update context-snapshot/CodeLens/CONTEXT.md with the new convention (per CONTEXT.md's own instructions).

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[Wolfvin]

Closing as duplicate — #155 has more complete implementation. Merge #155 instead.