Quality audit remediation: fleet project tracking

[rysweet]

Quality Audit Remediation — Fleet Project Tracking

Tracks the quality audit fixes applied to the fleet project tracking feature (_projects.py, _cli_commands.py, _session_gather.py, and related modules) as part of PR #2727.

Parent Issue

Related to #2841 (Quality Audit: 139 findings across fleet PR #2727).

Commits (on feat/fleet-orchestration)

1. a2c9ed7 fix(fleet): replace hand-rolled TOML serializer with tomli_w, add project name validation

   • Replaced fragile custom TOML serializer with tomli_w library
   • Added project name validation (rejects names with TOML special characters)

2. 69d20b5 fix(fleet): validate repo_url before gh calls, add gh auth switch for identity

   • Validates repo_url format before passing to gh CLI calls
   • Adds gh auth switch for identity management

3. b90d521 fix(fleet): narrow exception catches, validate remote objective data

   • Replaced broad except Exception with specific exception types
   • Added validation for remote objective data from GitHub API

4. cfe3e9b refactor(fleet): move paths to _constants.py, remove unused import, extract duplication

   • Centralized path constants in _constants.py
   • Removed unused imports
   • Extracted duplicated logic into shared helpers

5. c881018 test(fleet): add TOML special characters roundtrip and validation tests

   • Added roundtrip tests for TOML serialization with special characters
   • Added validation tests for project name edge cases

6. e123c50 docs(fleet): add project tracking to TUTORIAL, ARCHITECTURE, ADMIRAL_REASONING, SKILL

   • Updated TUTORIAL.md with project tracking usage examples
   • Updated ARCHITECTURE.md with _projects.py module details
   • Updated ADMIRAL_REASONING.md and SKILL.md feature lists

Files Changed (11 files, +215 / -33)

• src/amplihack/fleet/_projects.py — Core fixes (tomli_w, validation, narrow exceptions)
• src/amplihack/fleet/_cli_commands.py — CLI validation for repo URLs and project names
• src/amplihack/fleet/_session_gather.py — Validation for remote objective data
• src/amplihack/fleet/_cli_scout_advance.py — Updated for constants refactor
• src/amplihack/fleet/_constants.py — New path constants
• src/amplihack/fleet/tests/test_projects.py — 65 new lines of tests
• pyproject.toml — Added tomli_w dependency
• docs/fleet-orchestration/TUTORIAL.md — Project tracking section
• docs/fleet-orchestration/ARCHITECTURE.md — Module documentation
• docs/fleet-orchestration/ADMIRAL_REASONING.md — Updated reasoning docs
• .claude/skills/fleet/SKILL.md — Updated feature list

Audit Categories Addressed

• Reliability: Replaced hand-rolled TOML serializer with battle-tested tomli_w
• Security: Input validation for project names and repo URLs before shell/API calls
• Error handling: Narrowed exception catches from broad except Exception to specific types
• Code quality: Extracted constants, removed duplication, removed dead imports
• Test coverage: Added roundtrip and validation edge-case tests
• Documentation: All 4 fleet docs updated for project tracking feature

Verification

• Full fleet test suite passes (953/953)
• Docs reviewed for accuracy (commit e123c50)

Refs: PR #2727, Issue #2841