diff --git a/docs/development/automation-tracking.md b/docs/development/automation-tracking.md index 2cd7e25f2..d8b6248cc 100644 --- a/docs/development/automation-tracking.md +++ b/docs/development/automation-tracking.md @@ -360,6 +360,12 @@ Every agent that creates tracking issues must implement: - **Content**: Build orchestration status, worker pool health - **Cleanup**: Handled by automation-tracking-manager +#### docs-writer +- **Cycle Frequency**: Documentation reports every 10 cycles (~3.3 hours) +- **Issue Types**: Documentation Report +- **Content**: Docs created/updated/skipped, commit hash, milestone coverage +- **Cleanup**: Deletes previous documentation report issues + ## Searching and Filtering ### Finding Tracking Issues diff --git a/docs/development/docs-writer.md b/docs/development/docs-writer.md index 31c64c23e..c17cc919f 100644 --- a/docs/development/docs-writer.md +++ b/docs/development/docs-writer.md @@ -5,7 +5,7 @@ **Reporting Interval**: Every 10 cycles (~3.3 hours) The `docs-writer` agent is a continuous documentation monitoring and generation -service. It runs in an isolated clone of the repository, polls for merged code +service. It runs in an isolated clone of the repository, polls for merged code and milestone completions, and keeps project documentation current without human intervention. @@ -35,8 +35,8 @@ cycle = 0 LOOP: cycle += 1 - # Create tracking issue every 10 cycles - if cycle % 10 == 0: + # Create tracking issue on first cycle and then every 10 cycles + if cycle == 1 or cycle % 10 == 0: automation-tracking-manager: CREATE_TRACKING_ISSUE agent_prefix: AUTO-DOCS tracking_type: Documentation Report @@ -75,15 +75,23 @@ via the `automation-tracking-manager` subagent. Title: [AUTO-DOCS] Documentation Report (Cycle N) ``` -**Default label** (applied automatically by the manager): +**Required labels** (all four must be applied): | Label | Purpose | |-------|---------| | `Automation Tracking` | Enables system-watchdog health monitoring | +| `Type/Automation` | Marks as automation-related | +| `State/In Progress` | Indicates agent is actively running | +| `Priority/Medium` | Default priority | -Additional labels (for example `Type/Automation`, `State/In Progress`, or -`Priority/Medium`) can be added manually when teams need extra filtering, but -they are optional and not applied by the manager today. +Tracking issue bodies MUST include the standard automation tracking header with +the reporting interval declaration, for example: + +``` +**Reporting Interval**: Every 10 cycles (~3.3 hours) (Next report expected: ) +``` +See [Automation Tracking System](automation-tracking.md#common-header-format) for +the complete required structure. ### Cleanup Protocol @@ -92,7 +100,7 @@ The `automation-tracking-manager` handles all cleanup: 1. Finds the previous open `[AUTO-DOCS] Documentation Report (Cycle N)` issue 2. Posts a closure comment 3. Closes the issue -4. Creates the new tracking issue with the `Automation Tracking` label +4. Creates the new tracking issue with the four required labels Announcement issues (`[AUTO-DOCS] Announce: …`) are **never** deleted. @@ -113,8 +121,10 @@ All documentation produced by this agent follows the project's ## Clone Isolation The agent always works in an isolated clone at `/tmp/docs-writer-/`. -It never modifies files in `/app` or any shared directory. The clone is -deleted on exit (including on error). +The instance identifier MUST be generated with a cryptographically strong +mechanism such as `uuid.uuid4()` or `secrets.token_hex(8)` to avoid collisions +or predictable directory names. It never modifies files in `/app` or any shared +directory. The clone is deleted on exit (including on error). Push conflicts are resolved with `git pull --rebase origin master && git push`. After five consecutive push failures the clone is deleted and re-cloned fresh. @@ -122,6 +132,15 @@ After five consecutive push failures the clone is deleted and re-cloned fresh. Since `master` is a protected branch, all documentation changes are submitted as pull requests from a feature branch. +All Git authentication must rely on credential helpers or `GIT_ASKPASS`. The +agent must not embed personal access tokens in remote URLs, because git will +echo failing URLs (including credentials) to stderr when operations fail. + +When interacting with the Forgejo API, the agent MUST handle `HTTP 429` rate +limit responses by backing off exponentially (starting at 60 seconds, capped at +the 20 minute cycle delay) before retrying the request. This prevents tight +retry loops during temporary throttling events. + --- ## Related Documentation diff --git a/robot/coverage_threshold.robot b/robot/coverage_threshold.robot index b7d6d5ce4..fcc7f2c88 100644 --- a/robot/coverage_threshold.robot +++ b/robot/coverage_threshold.robot @@ -34,8 +34,7 @@ Pyproject Coverage Source Includes Src Coverage Threshold Is 97 In Noxfile [Documentation] Verify noxfile enforces 97% threshold via fail-under - [Tags] tdd_issue tdd_issue_4227 tdd_expected_fail - [Tags] coverage config + [Tags] coverage config tdd_issue tdd_issue_4227 ${content}= Get File ${WORKSPACE}/noxfile.py Should Contain ${content} --fail-under= diff --git a/scripts/validate_automation_tracking.py b/scripts/validate_automation_tracking.py index ff4783de8..5f4cdd6e1 100755 --- a/scripts/validate_automation_tracking.py +++ b/scripts/validate_automation_tracking.py @@ -24,6 +24,7 @@ AGENT_PREFIXES: dict[str, list[str]] = { "WATCHDOG": ["System Health", "Alert"], "GROOMER": ["Grooming Report", "Scope Alert"], "LIAISON": ["Status Update", "Human Activity Summary"], + "DOCS": ["Documentation Report"], } # Title format patterns @@ -117,8 +118,16 @@ def validate_automation_tracking_issue( for label in labels ] - if "Automation Tracking" not in label_names: - errors.append("Missing required 'Automation Tracking' label") + required_labels = [ + "Automation Tracking", + "Type/Automation", + "State/In Progress", + "Priority/Medium", + ] + + for required_label in required_labels: + if required_label not in label_names: + errors.append(f"Missing required '{required_label}' label") # Validate body content (basic checks) body = issue_data.get("body", "") @@ -139,9 +148,14 @@ def get_tracking_issues_from_repo( """Fetch automation tracking issues from repository. Note: This is a stub — in real usage, integrate with the Forgejo API. + Real implementations must paginate results because Forgejo limits + responses to 50 items per page by default. """ print(f"Note: Repository validation for {owner}/{repo} requires API integration") - print("This is a demonstration of the validation logic.") + print( + "This is a demonstration of the validation logic. Real integrations must " + "paginate Forgejo API responses (commonly limited to 50 items per page)." + ) return [] @@ -157,6 +171,7 @@ def _run_validate_all() -> int: ("[AUTO-WATCHDOG] System Health (Cycle 8)", True), ("[AUTO-GROOMER] Grooming Report (Cycle 23)", True), ("[AUTO-LIAISON] Status Update (Cycle 67)", True), + ("[AUTO-DOCS] Documentation Report (Cycle 1)", True), ( "[AUTO-SESSION] Announce: Emergency system restart required", True, @@ -222,7 +237,7 @@ def main() -> int: print(f"Message: {message}") return 0 if is_valid else 1 - if args.repo: + elif args.repo: try: owner, repo_name = args.repo.split("/", 1) get_tracking_issues_from_repo(owner, repo_name) @@ -232,7 +247,7 @@ def main() -> int: print("Error: Repository must be in format 'owner/repo'") return 1 - if args.validate_all: + elif args.validate_all: return _run_validate_all() parser.print_help()