chore: add CI pipeline, linting, and quality infrastructure

[Aliciapet11]

Closes #24

Summary

• Add CI pipeline (GitHub Actions) with lint and test jobs — the repo had 11 test files that were never run in CI
• Add pyproject.toml with project metadata, dependencies, and tool configuration (pytest, ruff, coverage)
• Add ruff linting and formatting with auto-fixed existing violations (import sorting, unused variables, ambiguous names)
• Add pre-commit hooks (ruff for linting/formatting, gitleaks for secret scanning)
• Add Dependabot for automated pip and GitHub Actions dependency updates
• Add SECURITY.md with vulnerability reporting policy
• Add Development section to README with setup, testing, and linting instructions
• Set 60% coverage threshold enforced in CI (tests currently at 62%)
• 108 new tests across 4 test files (jira_integration, comments, github_ops, doc_index)
• Update Dockerfile to install from pyproject.toml (removes duplicate dependency list)
• GH Actions pinned to SHA for supply chain security
• CI workflow scoped to permissions: contents: read

Context

Identified as part of a gap analysis across team repos (Jira: QEMETRICS-2406). code-to-docs had solid test files but no CI pipeline to run them, no linter, no dependency manifest, and no security scanning.

Test plan

• CI pipeline runs successfully on this PR (lint + test jobs)
• All existing + new test files pass (347 total)
• Coverage meets 60% threshold (currently 62%)
• Ruff lint and format checks pass
• Verify Dependabot config is picked up after merge

🤖 Generated with Claude Code

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:24 AM UTC · Completed 10:39 AM UTC
Commit: ba8f26f · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [string-quote-convention] pyproject.toml — Ruff format enforces double quotes by default, but the pre-existing codebase consistently used single quotes across all src/*.py files. The PR converts all string literals to double quotes as part of ruff adoption without configuring [tool.ruff.format] quote-style = "single" to preserve the original convention. Consider adding the config option or documenting the migration as intentional.

• [protected-path] .github/dependabot.yml, .github/workflows/ci.yaml, .pre-commit-config.yaml, Dockerfile — This PR modifies files under protected paths. The changes are well-justified by the linked issue Add CI pipeline, linting, and quality infrastructure #24 (CI/quality infrastructure), but human approval is always required for protected-path changes.

Low

• [runtime mechanism] pyproject.toml — The pyproject.toml lacks package discovery configuration ([tool.setuptools.packages.find]) and src/__init__.py is absent. pip install /app in the Dockerfile installs dependencies but does not make src/ importable as a package. The runtime works correctly because the entrypoint invokes python /app/src/suggest_docs.py directly, but the pip install line is misleading.

• [scope-creep] Dockerfile — The Dockerfile restructuring (individual file copies → COPY pyproject.toml + COPY src/) is a packaging architecture change that goes slightly beyond the stated CI infrastructure scope. The entrypoint path change (/app/suggest_docs.py → /app/src/suggest_docs.py) is a necessary consequence.

Previous run

Review

Findings

Critical

• [Runtime breakage] Dockerfile — The Dockerfile changes the source file layout from flat (/app/config.py, /app/suggest_docs.py, etc.) to nested (/app/src/config.py, /app/src/suggest_docs.py), but entrypoint.sh (not modified in this PR) runs python /app/suggest_docs.py on line 110. After this change, suggest_docs.py will be at /app/src/suggest_docs.py, so the entrypoint will fail with FileNotFoundError at container startup.
  Remediation: Either (a) update entrypoint.sh to run python /app/src/suggest_docs.py, or (b) add a [project.scripts] entry to pyproject.toml and call the console-script by name in entrypoint.sh, or (c) keep the flat copy layout in the Dockerfile.

High

• [Missing build configuration] pyproject.toml — pyproject.toml has no [build-system] table. Without it, pip install /app falls back to legacy setuptools behavior. Combined with src/ having no __init__.py, setuptools auto-discovery may not find any packages to install as a proper Python package. The pip install will install declared dependencies but may not make source modules importable as installed packages.
  Remediation: Add a [build-system] table (e.g., requires = ["setuptools"] / build-backend = "setuptools.build_meta") and consider adding src/__init__.py or configuring [tool.setuptools.packages.find].

Medium

• [Dependency pinning — supply-chain risk] pyproject.toml:8 — Production dependencies (openai, mcp, mcp-atlassian, markdown, docutils) are declared without any version constraints. This could introduce breaking changes or, in a supply-chain attack scenario, a compromised release. The old Dockerfile was equally unpinned, but this PR replaces it with pyproject.toml, making this the right time to address it.
  Remediation: Add lower-bound version pins for production dependencies (e.g., openai>=1.0). For stronger reproducibility, generate and commit a lockfile.

Low

• [scope-expansion] .pre-commit-config.yaml — The gitleaks hook addition goes slightly beyond issue Add CI pipeline, linting, and quality infrastructure #24's explicit scope (which lists ruff + pre-commit hooks but not gitleaks). While a reasonable security measure, consider documenting the authorization.

Previous run (2)

Review

Findings

High

• [protected-path] .github/dependabot.yml, .github/workflows/ci.yaml, Dockerfile, .pre-commit-config.yaml — This PR modifies files under protected paths (.github/, Dockerfile, .pre-commit-config.yaml). These are governance and infrastructure files that require human approval. The PR has no linked GitHub issue — while the PR body explains the rationale (gap analysis, QEMETRICS-2406), a linked issue is expected to establish authorization for protected-path changes.
  Remediation: Link a GitHub issue authorizing these infrastructure changes and ensure human maintainer review before merging.

Low

• [missing-authorization] — The PR references Jira ticket QEMETRICS-2406 but has no linked GitHub issue. For a change of this scope (33 files, 2139 additions), explicit authorization via a linked GitHub issue provides traceability.

Previous run (3)

Review

Findings

High

• [stale-metadata] README.md:4 — The README badge declares the license as MIT (License: MIT badge linking to opensource.org/licenses/MIT), but the newly added pyproject.toml declares license = {text = "Apache-2.0"}. The existing LICENSE file is MIT. This creates a three-way inconsistency in license metadata that can cause legal ambiguity.
  Remediation: Align the license across all files. If MIT is correct (matching the LICENSE file), update pyproject.toml line 6. If Apache-2.0 is intended, update the README badge and the LICENSE file.

• [protected-path] .github/dependabot.yml, .github/workflows/ci.yml, .pre-commit-config.yaml — This PR modifies files under protected paths (.github/, .pre-commit-config.yaml) that require human approval. No linked GitHub issue provides authorization for these changes. The Jira reference (QEMETRICS-2406) in the PR body cannot be verified through GitHub's issue-linking mechanisms.
  Remediation: Link a GitHub issue authorizing the changes to these governance/infrastructure files, or obtain explicit human approval.

Medium

• [missing-authorization] — This PR has no linked GitHub issue. It references Jira ticket QEMETRICS-2406 but this cannot be verified through GitHub. With 31 changed files and ~2,700 changed lines, this is a non-trivial change that should have explicit, verifiable authorization. See also: [protected-path] finding above.

Low

• [pattern-inconsistency] pyproject.toml:37 — The per-file-ignores suppress E501 (line-too-long) and E402 (module-level-import-not-at-top) for both src/** and tests/**. Suppressing E501 for production code effectively nullifies the line-length = 100 setting for ruff check (though ruff format still enforces it). This is overly broad for production code.

• [dependency-pinning] .github/workflows/ci.yml — The CI workflow uses mutable major-version tags (actions/checkout@v4, astral-sh/setup-uv@v6). Using full SHA pins would prevent supply-chain tag-rewrite attacks. Dependabot (already configured) can keep SHA pins updated.

• [scope-mismatch] — The PR title uses the feat: conventional commit prefix, but the changes are developer infrastructure (CI pipeline, linting, dependency manifest, pre-commit hooks, Dependabot, SECURITY.md). No user-facing feature is introduced. chore: or ci: would be more accurate.

Previous run (4)

Review

Findings

High

• [protected-path] .github/workflows/ci.yml, .github/dependabot.yml, .pre-commit-config.yaml — This PR adds files under protected paths (.github/, .pre-commit-config.yaml) that require human approval. No linked GitHub issue exists. While the PR description references JIRA QEMETRICS-2406 and explains the rationale, protected-path changes require a linked issue for traceability.
  Remediation: Create a GitHub issue describing the CI infrastructure changes and link it to this PR.

Medium

• [missing-doc] README.md — README.md does not document the new development setup, testing, or code quality requirements introduced by this PR. Developers need guidance on: Python 3.12+ requirement, dependency installation with uv, running tests (pytest), running linters (ruff), pre-commit hooks setup, and the 60% coverage threshold.
  Remediation: Add a Development/Contributing section to README.md.

• [architecture] pyproject.toml — Dependencies are now duplicated: pyproject.toml lists openai, mcp, mcp-atlassian, markdown, docutils — the exact same set installed via pip install in Dockerfile line 23. There is no mechanism to keep them in sync, creating a maintenance risk where one list drifts from the other.
  Remediation: Update the Dockerfile to install from pyproject.toml (e.g., pip install .) or document the coexistence strategy.

Low

• [GHA-workflow-permissions] .github/workflows/ci.yml — CI workflow does not declare a permissions block. It inherits repository default token permissions, which may include write access. For a lint/test-only pipeline, contents: read is sufficient.
  Remediation: Add permissions: contents: read at the workflow level.

• [scope] pyproject.toml — Version set to 1.0.0 but RELEASING.md shows the project is released via GitHub Action version tags, not PyPI. The pyproject.toml version is disconnected from the actual release process.
  Remediation: Verify version aligns with release strategy or set to 0.0.0.

• [naming-convention] .github/workflows/ci.yml — Uses .yml extension while existing .github/workflows/fullsend.yaml uses .yaml. Mixing extensions reduces consistency.
  Remediation: Rename to ci.yaml.

---

Labels: PR adds CI/quality infrastructure and modifies protected paths requiring manual review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:45 AM UTC · Completed 11:00 AM UTC
Commit: 639684d · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:10 AM UTC · Completed 11:24 AM UTC
Commit: 01556b4 · View workflow run →

[Aliciapet11]

@csoceanu, hey please review

[csoceanu]

Thanks for the contribution! LGTM — nice infrastructure uplift.

One thing to track: Dependabot won't update pre-commit hook versions (.pre-commit-config.yaml), so the pinned ruff version will drift from what CI installs via pyproject.toml over time. I'll set up periodic pre-commit autoupdate or pre-commit.ci as a follow-up.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:29 AM UTC · Completed 7:42 AM UTC
Commit: cc6d5a2 · View workflow run →

[csoceanu]

Verified all src/ changes are formatting-only (import ordering, line wrapping, quote style, f-prefix removal). Zero end-user impact — action.yml and entrypoint.sh untouched, same dependencies, same behavior.

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 7:50 AM UTC · Completed 7:51 AM UTC
Commit: 15ed4d1 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:56 AM UTC · Completed 8:12 AM UTC
Commit: 15ed4d1 · View workflow run →

Superseded by updated review

[csoceanu]

Re-approving after entrypoint path fix (cc6d5a2 → 15ed4d1). Deep verification confirmed: action.yml untouched, import chain resolves correctly with new /app/src/ layout, same dependencies, all src/ changes are formatting-only (AST-verified). No end-user impact.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 8:35 AM UTC · Completed 8:47 AM UTC
Commit: 15ed4d1 · View workflow run →

[fullsend-ai-retro]

Retro: PR #23 — CI pipeline, linting, and quality infrastructure

Workflow quality: Good. The review agent delivered high-value feedback across 5 review iterations, including a critical runtime breakage catch (Dockerfile layout change broke entrypoint.sh path) that the human reviewer initially missed. The human reviewer (csoceanu) had already approved the PR before the review agent flagged the critical issue; the human then fixed it and re-approved. This is a strong example of the review agent adding genuine safety value.

Timeline

1. Jul 29 10:23 — PR opened by Aliciapet11 (human author, Claude Code assisted). 34 files, 2140 additions.
2. Jul 29 10:39 — Review 1: flagged missing README docs, dependency duplication in Dockerfile, missing GHA permissions, version mismatch.
3. Jul 29 10:44 — Author pushed 108 new tests (coverage 52% → 62%).
4. Jul 29 11:01 — Review 2: caught license inconsistency (MIT vs Apache-2.0).
5. Jul 29 11:09 — Author addressed all feedback (license fix, SHA-pinned actions, permissions, README section, Dockerfile update). Issue Add CI pipeline, linting, and quality infrastructure #24 created.
6. Jul 29 11:24 — Review 3: reduced findings, protected-path deferred to human.
7. Jul 30 07:17 — Human reviewer (csoceanu) commented LGTM, noted pre-commit/Dependabot version drift risk.
8. Jul 30 07:26 — csoceanu pushed SECURITY.md fix.
9. Jul 30 07:35 — csoceanu approved.
10. Jul 30 07:43 — Review 4: caught CRITICAL entrypoint breakage — Dockerfile moved files to /app/src/ but entrypoint.sh still referenced /app/suggest_docs.py.
11. Jul 30 07:49 — csoceanu fixed entrypoint path.
12. Jul 30 08:13 — Review 5: no critical/high findings remaining. Two inline comments on pyproject.toml (E501 suppression breadth, unpinned dependencies).
13. Jul 30 08:34 — PR merged.

What went well

• The review agent's correctness sub-agent identified a genuine runtime breakage that the human reviewer missed, preventing a broken container from being deployed.
• The challenger sub-agent validated the critical finding, preventing false positives.
• Review feedback improved iteratively — the agent appropriately reduced/removed findings as the author addressed them.
• The triage agent correctly identified that PR chore: add CI pipeline, linting, and quality infrastructure #23 already implements issue Add CI pipeline, linting, and quality infrastructure #24's scope.

Evidence for existing open issues

• Prior review pre-fetch fails to find existing review in per-repo install mode when REVIEW_APP_CLIENT_ID is empty fullsend-ai/agents#203 / Fix empty expected app client_id in pre-fetch-prior-review for per-repo install mode fullsend-ai/fullsend#5388 (prior review pre-fetch failure in per-repo install mode): Review run 5 (commit 15ed4d1) was treated as a first review (PRIOR_REVIEW_PROVENANCE=none) despite 4 prior successful reviews on the same PR. This caused a full re-review costing $8.94 instead of an estimated $3-4 incremental review. The per-repo install mode empty REVIEW_APP_CLIENT_ID bug is the root cause. This PR provides another data point: 5 reviews total, with the last review doing redundant full analysis.
• Review agent should recommend automated enforcement for drift/consistency risks fullsend-ai/agents#435 (review agent should recommend automated enforcement for drift/consistency risks): The human reviewer caught a maintenance concern the agent missed across all 5 reviews — pre-commit hook versions (.pre-commit-config.yaml) will drift from CI-installed versions (pyproject.toml) because Dependabot doesn't update pre-commit configs. This is a concrete instance of the drift-detection gap described in #435.
• Review agent should apply scaffold-aware review profile for initialization PRs fullsend-ai/agents#470 (scaffold-aware review profile for initialization PRs): This PR bootstrapped CI infrastructure from scratch (34 files, 2140 additions). All 5 reviews applied the standard review profile rather than a lighter scaffold profile, contributing to higher total cost.
• Add per-PR review budget to cap runaway review dispatches fullsend-ai/fullsend#2599 (per-PR review budget): 5 reviews at ~$7-9 each totaled ~$40+ for a single PR. A budget cap would have limited this.

New proposal filed

1 new proposal: review agent's PR metadata jq query uses a cross-product formula that inflates line counts ~33x, wasting a self-correction turn on every review run.

Proposals filed

• Review agent jq line-count formula cross-products additions and deletions, inflating PR size ~33x (in fullsend-ai/agents)