docs(#8): add repo-specific conventions to AGENTS.md

[fullsend-ai-coder]

Summary

• Add repo-specific sections to AGENTS.md (sections 6–10) covering architecture decisions, repository structure, testing conventions, data model patterns, and known architecture exceptions
• Add CLAUDE.md pointing to AGENTS.md as the single source of truth for agent-facing guidance
• Explicitly document the Python exception for complex collectors, clarify that scripts/ is application code (not CI infrastructure), and list known deviations from the original design.md so review agents do not re-flag them

Context

PR #7 was flagged 3 times by the review agent for an architecture deviation (Python usage) that is intentional and documented in design.md. The review agent also flagged scripts/ modifications as protected-path changes because the default config treats scripts/ as CI infrastructure. This AGENTS.md gives agents the repo-specific context they need to avoid false-positive findings.

Test plan

• Verify AGENTS.md exists at repo root and is tracked by git
• Verify CLAUDE.md exists at repo root and references AGENTS.md
• Verify AGENTS.md contains architecture decisions section mentioning Python exception
• Verify AGENTS.md contains repository structure section clarifying scripts/ role
• Verify AGENTS.md contains testing conventions section referencing test_*.py pattern
• Verify AGENTS.md contains data model section (append-only CSV, idempotent writes)
• Verify AGENTS.md contains known architecture exceptions section
• Existing Python tests pass (python -m unittest scripts/test_collect_pr_type.py)

---

Closes #8

Post-script verification

• Branch is not main/master (agent/8-add-agents-md-conventions)
• Secret scan passed (gitleaks — 3c3488d88a505beb68f9af8dd21d2500a687988f..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:41 PM UTC · Completed 1:56 PM UTC

Commit: 6c6ee94 · View workflow run →

[fullsend-ai-review]

Review

Findings

High

• [factual-accuracy] AGENTS.md:91 — Repository structure diagram shows data/metrics.csv as the source of truth, but the data/ directory does not exist. The actual path is docs/metrics.csv (defined in scripts/lib.sh:5). An agent following this documentation would look for a directory and file that do not exist.
  Remediation: Remove the data/ directory entry from the structure diagram and clarify that docs/metrics.csv is the source of truth for SDLC metrics.

• [factual-accuracy] AGENTS.md:172 — Section 10, item 3 states: "The original data/metrics.csv still exists as the source of truth for SDLC metrics." This is factually incorrect — data/metrics.csv does not exist. The workflow commits only docs/, and scripts/lib.sh:5 defines DATA_FILE="docs/metrics.csv".
  Remediation: Rewrite item 3 to clarify that the original design specified data/metrics.csv but the implemented architecture writes directly to docs/metrics.csv. Remove the false claim that data/metrics.csv still exists.

Medium

• [incomplete-architecture-exception-documentation] AGENTS.md:170 — Section 10 documents "Multiple CSV files" as an architecture exception but does not document the more significant deviation: elimination of the data/ directory. The original design specified data/metrics.csv as the source file with a copy step to docs/. The implemented pattern writes directly to docs/ with no separate data layer.
  Remediation: Expand the Known Architecture Exceptions section to explicitly note the elimination of the data/ directory and the write-once-to-docs pattern.

• [protected-path] AGENTS.md, CLAUDE.md — This PR modifies files under protected paths (AGENTS.md, CLAUDE.md). The PR links to issue Add AGENTS.md with repo-specific conventions and architecture decisions #8 and explains the rationale. Human approval is always required for protected-path changes, regardless of context.

Low

• [documentation-completeness] AGENTS.md:100 — The docs/ listing in Section 7 includes dashboard.js but omits details.js and delivered-pr-types.js (page-specific JS for the listed HTML pages), plus design.md, rework-config.json, and holidays.yaml.
  Remediation: Add the omitted files to the docs/ tree, or expand the existing wildcard comment to cover JS files.

• [broken-reference] AGENTS.md:46 — Section 4 references CONTRIBUTING.md which does not exist. The "or CLAUDE.md" fallback limits practical impact.
  Remediation: Remove the reference to CONTRIBUTING.md, or list allowed commit types directly in section 4.

---

Labels: PR adds documentation files (AGENTS.md, CLAUDE.md) and modifies protected paths requiring manual review

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[high] factual-accuracy

Repository structure diagram shows data/metrics.csv as the source of truth, but the data/ directory does not exist. The actual path is docs/metrics.csv (defined in scripts/lib.sh:5). An agent following this documentation would look for a directory and file that do not exist.

Suggested fix: Remove the data/ directory entry from the structure diagram and clarify that docs/metrics.csv is the source of truth for SDLC metrics.

[fullsend-ai-review]

[high] factual-accuracy

Section 10, item 3 states: 'The original data/metrics.csv still exists as the source of truth for SDLC metrics.' This is factually incorrect — data/metrics.csv does not exist. The workflow commits only docs/, and scripts/lib.sh:5 defines DATA_FILE="docs/metrics.csv".

Suggested fix: Rewrite item 3 to clarify that the original design specified data/metrics.csv but the implemented architecture writes directly to docs/metrics.csv. Remove the false claim that data/metrics.csv still exists.

[fullsend-ai-review]

[medium] incomplete-architecture-exception-documentation

Section 10 documents 'Multiple CSV files' as an architecture exception but does not document the more significant deviation: elimination of the data/ directory. The original design specified data/metrics.csv as the source file with a copy step to docs/. The implemented pattern writes directly to docs/ with no separate data layer.

Suggested fix: Expand the Known Architecture Exceptions section to explicitly note the elimination of the data/ directory and the write-once-to-docs pattern.

[fullsend-ai-review]

[low] documentation-completeness

The docs/ listing in Section 7 includes dashboard.js but omits details.js and delivered-pr-types.js (page-specific JS for the listed HTML pages), plus design.md, rework-config.json, and holidays.yaml.

Suggested fix: Add the omitted files to the docs/ tree, or expand the existing wildcard comment to cover JS files.

[fullsend-ai-review]

[low] broken-reference

Section 4 references CONTRIBUTING.md which does not exist. The 'or CLAUDE.md' fallback limits practical impact.

Suggested fix: Remove the reference to CONTRIBUTING.md, or list allowed commit types directly in section 4.