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

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: <timestamp>)
+```
+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-<instance-id>/`.
-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

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=
 

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()