From c76433f75669e9fa69174e95f37c1fde54a7a23b Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 05:27:30 +0000 Subject: [PATCH] docs(tracking): document automation-tracking-manager centralization --- CHANGELOG.md | 31 +++- docs/development/automation-tracking.md | 215 ++++++++++++++---------- docs/development/docs-writer.md | 131 +++++++++++++++ mkdocs.yml | 1 + 4 files changed, 291 insertions(+), 87 deletions(-) create mode 100644 docs/development/docs-writer.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7a76a7292..81a54b269 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -75,6 +75,25 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - **Container Resource Stop Support**: `agents resource stop` now correctly stops `container-instance` and `devcontainer-instance` resource types. +- **Centralized Automation Tracking Manager** (`automation-tracking-manager`): The manager + is now the single interface for all tracking issue operations (`CREATE_TRACKING_ISSUE`, + `UPDATE_TRACKING_ISSUE`, `CLOSE_TRACKING_ISSUE`, `READ_TRACKING_STATE`, + `GET_NEXT_CYCLE_NUMBER`). Agents delegate to the manager rather than calling the Forgejo + API directly, ensuring sequential cycle numbers across restarts and preventing + duplicate issues. Migrated agents include `system-watchdog`, + `implementation-pool-supervisor`, `timeline-update-pool-supervisor`, + `project-owner-pool-supervisor`, `product-builder`, and + `backlog-grooming-pool-supervisor`. The legacy `shared/automation_tracking.md` module + was removed. + +- **Documentation Writer Tracking** (`docs-writer`): The documentation writer now + participates in the automation tracking system by creating individual + `[AUTO-DOCS] Documentation Report (Cycle N)` issues every 10 cycles (~3.3 hours). + The manager applies the mandatory `Automation Tracking` label automatically, while + teams may add additional workflow labels as needed. See + `docs/development/automation-tracking.md` and the new + `docs/development/docs-writer.md` reference. + ### Changed - **Decision Tree Full ULID Display** (#5825): The `agents plan tree` command now @@ -94,7 +113,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - **Label Delegation Enforcement**: `automation-tracking-manager` now enforces delegation to `forgejo-label-manager` for all label operations, preventing "invalid label ID" errors - and ensuring all tracking issues receive proper labels via name-to-ID mapping. + and ensuring label application uses correct name-to-ID mapping. + +- **Automation Tracking Label Guidance**: Documentation now clarifies that the manager + automatically applies the `Automation Tracking` label and that additional labels such as + `Type/Automation`, `State/In Progress`, or `Priority/Medium` remain optional workflow + choices rather than mandatory. + +- **Automation Tracking Agent Prefix Registry**: Expanded from 5 agents to 18 agents. + New prefixes include `AUTO-DOCS`, `AUTO-REV-POOL`, `AUTO-UAT-POOL`, `AUTO-BUG-POOL`, + `AUTO-INF-POOL`, `AUTO-ARCH`, `AUTO-EPIC`, `AUTO-EVLV`, `AUTO-GUARD`, `AUTO-SPEC`, + `AUTO-TIME`, `AUTO-PROJ-OWN`, and `AUTO-PROD-BLDR`. - **ACMS Context Hydration**: Fixed ACMS indexing pipeline not wired into CLI — `ContextTierService` started empty on every CLI invocation so LLM received zero file diff --git a/docs/development/automation-tracking.md b/docs/development/automation-tracking.md index e5e12d101..2cd7e25f2 100644 --- a/docs/development/automation-tracking.md +++ b/docs/development/automation-tracking.md @@ -4,6 +4,8 @@ The CleverAgents automation tracking system provides structured, searchable tracking for all autonomous agent activities. This system replaced the previous approach of using a single shared session state issue with individual tracking issues for each agent. +All tracking operations are centralized through the **`automation-tracking-manager`** subagent — the single source of truth for cycle numbers, issue creation, cleanup, and state reads. Agents MUST NOT create or close tracking issues directly; they invoke the manager subagent instead. + ## Benefits - **Reduced Noise**: Each agent has its own tracking issues instead of all posting to one shared issue @@ -11,6 +13,8 @@ The CleverAgents automation tracking system provides structured, searchable trac - **Cleaner History**: Individual issues provide focused tracking without cross-agent interference - **Easier Debugging**: Agent-specific issues make it easier to trace problems - **Automatic Cleanup**: Stale tracking issues are automatically cleaned up +- **Cycle Continuity**: Sequential cycle numbers persist across agent restarts via the centralized manager +- **No Duplicate Issues**: The manager ensures exactly one tracking issue per cycle per agent ## Issue Format Standards @@ -37,6 +41,8 @@ For emergency announcements or important messages: ### Agent Prefixes +All prefixes are registered in the `automation-tracking-manager` subagent, which is the single source of truth for the prefix registry: + | Agent | Prefix | Example Title | |-------|--------|---------------| | session-persister | `AUTO-SESSION` | `[AUTO-SESSION] Checkpoint (Cycle 15)` | @@ -47,7 +53,7 @@ For emergency announcements or important messages: | product-builder | `AUTO-PROD-BLDR` | `[AUTO-PROD-BLDR] Build Session (Cycle 5)` | | architecture-pool-supervisor | `AUTO-ARCH` | `[AUTO-ARCH] Architecture Report (Cycle 3)` | | timeline-update-pool-supervisor | `AUTO-TIME` | `[AUTO-TIME] Timeline Update (Cycle 12)` | -| documentation-pool-supervisor | `AUTO-DOCS` | `[AUTO-DOCS] Documentation Report (Cycle 7)` | +| documentation-pool-supervisor, docs-writer | `AUTO-DOCS` | `[AUTO-DOCS] Documentation Report (Cycle 7)` | | architecture-guard-pool-supervisor | `AUTO-GUARD` | `[AUTO-GUARD] Guard Report (Cycle 9)` | | pr-review-pool-supervisor | `AUTO-REV-POOL` | `[AUTO-REV-POOL] Review Status (Cycle 4)` | | pr-fix-pool-supervisor | `AUTO-FIX-POOL` | `[AUTO-FIX-POOL] PR Fix Status (Cycle 5)` | @@ -58,45 +64,70 @@ For emergency announcements or important messages: | bug-hunt-pool-supervisor | `AUTO-BUG-POOL` | `[AUTO-BUG-POOL] Bug Detection Pool Status (Cycle 60)` | | spec-update-pool-supervisor | `AUTO-SPEC` | `[AUTO-SPEC] Specification Update Report (Cycle 1)` | | test-infra-pool-supervisor | `AUTO-INF-POOL` | `[AUTO-INF-POOL] Infrastructure Analysis Report (Cycle 2)` | +| epic-planner | `AUTO-EPIC` | `[AUTO-EPIC] Epic Planning Update (Cycle 9)` | -## Required Labels +## Default Labels -All automation tracking issues MUST include: -- **`Automation Tracking`** - Primary label for filtering -- **`Type/Automation`** - Type label for automation issues -- **`State/In Progress`** - State label while agent is active -- **`Priority/Medium`** - Default priority (adjust as needed) +The `automation-tracking-manager` automatically applies the **`Automation Tracking`** +label to every tracking issue so that system-watchdog health checks and global searches +remain reliable. Teams may add additional labels such as `Type/Automation`, +`State/In Progress`, or `Priority/Medium` to reflect their workflow, but those labels are +optional and are not applied automatically today. Agents MUST NOT attempt to add labels +directly — the manager delegates to `forgejo-label-manager` and handles all label +application on their behalf. ## Centralized Tracking Manager -The **`automation-tracking-manager`** subagent is the single source of truth for all -automation tracking operations. It was introduced to prevent cycle reuse issues where -agents would incorrectly comment on old tracking issues instead of creating new ones. +All tracking operations are handled by the **`automation-tracking-manager`** subagent +(`.opencode/agents/automation-tracking-manager.md`). The manager is the single source of +truth for cycle numbers, issue creation, cleanup, and state reads. It was introduced to +eliminate cycle reuse, duplicate issues, and inconsistent cleanup that occurred when +agents managed tracking issues individually. -### Why Centralized? +### Why Centralization Matters -Without centralization, agents experienced: -- **Cycle reuse**: Agents posting future cycle reports as comments on old issues -- **Duplicate issues**: Multiple tracking issues created for the same cycle -- **Missing cycles**: Agents skipping cycle numbers due to stale issue references -- **Inconsistent cleanup**: Previous cycle issues not always deleted before creating new ones +- **Cycle reuse prevention**: agents never post future reports to stale issues. +- **Duplicate avoidance**: exactly one tracking issue exists per cycle per prefix. +- **Sequential numbering**: cycle counters persist across crashes and restarts. +- **Consistent cleanup**: previous cycles close automatically before new ones open. -### How It Works +### Operations -The `automation-tracking-manager` subagent: -1. Maintains a persistent cycle counter per agent prefix -2. Searches for and closes the previous cycle's tracking issue -3. Creates a new tracking issue with the correct sequential cycle number -4. Applies all required labels atomically -5. Returns the new issue number to the calling agent +| Operation | Description | +|-----------|-------------| +| `CREATE_TRACKING_ISSUE` | Closes the previous cycle, determines the next cycle number, and creates the new issue | +| `UPDATE_TRACKING_ISSUE` | Adds a comment to the current open tracking issue | +| `CLOSE_TRACKING_ISSUE` | Closes the current tracking issue with a closure comment | +| `READ_TRACKING_STATE` | Reads the latest tracking issue and extracts cycle metadata | +| `GET_NEXT_CYCLE_NUMBER` | Scans open and closed issues to determine the next sequential cycle number | -### Usage +### Cycle Number Continuity -Agents that use the centralized manager delegate all tracking operations to it: +The manager inspects both open and closed tracking issues to determine the highest cycle +number for each prefix, then increments by one. This guarantees sequential numbering even +when agents restart or experience failures. + +### Rules Enforced by the Manager + +1. **One issue per cycle** — the previous cycle is closed before a new one opens. +2. **Sequential cycle numbers** — cycle counters persist across restarts. +3. **Label enforcement** — the `Automation Tracking` label is applied to every issue. +4. **Cleanup before creation** — stale tracking issues are never left behind. +5. **Comment validation** — updates only target the current, open tracking issue. + +### Integration Requirements + +Agents MUST NOT: + +- Create tracking issues directly via the Forgejo API +- Manually manage or increment cycle numbers +- Close tracking issues without going through the manager +- Comment on tracking issues directly + +Instead, every agent invokes the `automation-tracking-manager` subagent for tracking +operations. Example pseudocode: ```bash -# Example: implementation-pool-supervisor delegating to tracking manager -# (Inside agent definition — pseudocode) TRACKING_RESULT=$(call_subagent automation-tracking-manager \ --prefix "AUTO-IMP-POOL" \ --type "Health Report" \ @@ -104,15 +135,10 @@ TRACKING_RESULT=$(call_subagent automation-tracking-manager \ NEW_ISSUE_NUMBER=$(echo "$TRACKING_RESULT" | jq -r '.issue_number') ``` -### Migrated Agents - -The following agents have been migrated to use the centralized tracking manager: -- `system-watchdog-pool-supervisor` (most critical — was skipping cycles) -- `implementation-pool-supervisor` (was creating duplicate issues) -- `timeline-update-pool-supervisor` -- `project-owner-pool-supervisor` -- `product-builder` -- `backlog-grooming-pool-supervisor` +The initial migration covered `system-watchdog-pool-supervisor`, +`implementation-pool-supervisor`, `timeline-update-pool-supervisor`, +`project-owner-pool-supervisor`, `product-builder`, and +`backlog-grooming-pool-supervisor`, with subsequent agents added as the registry expanded. ## Interval Reporting and Health Monitoring @@ -136,18 +162,19 @@ This enables automated health monitoring by the system-watchdog to detect stalle | backlog-grooming-pool-supervisor | Health Report | Every 50 minutes (10 cycles) | Grooming health status | | human-liaison-pool-supervisor | Status Update | Every 20 minutes (10 cycles) | Human activity monitoring | | system-watchdog-pool-supervisor | Health Report | Every 30 minutes (6 cycles) | System-wide health check | -| session-persister | Checkpoint | Event-driven (variable) | After significant state changes | +| session-persister | Session State Tracking | Event-driven (variable) | After significant state changes | +| documentation-pool-supervisor / docs-writer | Documentation Report | Every 10 cycles (~3.3 hours) | Documentation monitoring cycle | | product-builder | Build Session | Every 10 cycles (~variable timing) | Full build session status | | architecture-pool-supervisor | Architecture Report | Every 10 cycles (~variable timing) | Architecture supervision status | -| timeline-update-pool-supervisor | Timeline Update | Every 10 cycles (~variable timing) | Timeline maintenance status | -| documentation-pool-supervisor | Documentation Report | Every 10 cycles (~3.3 hours) | Documentation update status | | architecture-guard-pool-supervisor | Guard Report | Every 10 cycles (~variable timing) | Codebase coherence check | +| timeline-update-pool-supervisor | Timeline Update | Per-commit (variable) | After timeline-worthy events | | pr-review-pool-supervisor | Review Status | Every 10 cycles (~variable timing) | PR review pool status | | pr-fix-pool-supervisor | PR Fix Status | Every 10 cycles (~variable timing) | PR CI fix pool status | | pr-merge-pool-supervisor | PR Merge Status | Every 10 cycles (~variable timing) | Automated PR merge status | | uat-test-pool-supervisor | UAT Status | Every 10 cycles (~variable timing) | UAT testing progress | -| project-owner-pool-supervisor | Project Status | Every 10 cycles (~variable timing) | Project ownership decisions | +| project-owner-pool-supervisor | Project Status | Per-triage-cycle (variable) | After issue triage passes | | agent-evolution-pool-supervisor | Evolution Report | Every 10 cycles (~variable timing) | Agent improvement proposals | +| epic-planner | Epic Planning Update | Every 10 cycles (~variable timing) | Workstream planning summary | | bug-hunt-pool-supervisor | Bug Detection Status | Every 10 cycles (~variable timing) | Bug detection pool health | | spec-update-pool-supervisor | Specification Update | Every 10 cycles (~variable timing) | Spec evolution status | | test-infra-pool-supervisor | Infrastructure Report | Every 10 cycles (~variable timing) | Test infrastructure analysis | @@ -271,62 +298,67 @@ Supervisor: | Agent: Every agent that creates tracking issues must implement: -1. **Cleanup Function**: Delete previous cycle tracking issues before creating new ones -2. **Standardized Titles**: Use the exact format specified above -3. **Proper Labels**: Always include "Automation Tracking", "Type/Automation", "State/In Progress", and "Priority/Medium" labels -4. **Structured Content**: Use consistent formatting for issue bodies - -### Standard Tracking Functions - -Each agent should implement these functions: - -```markdown -## Automation Tracking Functions - -### Delete Previous Tracking Issues -1. Search for issues with title pattern `[AUTO-] (Cycle *)` -2. Filter for issues created by this agent -3. Close and delete previous cycle issues -4. Preserve announcement issues (different title pattern) - -### Create New Tracking Issue -1. Generate title with current cycle number -2. Include "Automation Tracking", "Type/Automation", "State/In Progress", "Priority/Medium" labels -3. Add structured content with timestamp and status -4. Link to relevant repositories/PRs as needed -``` +1. **Call the manager** for every create, update, or close operation — no direct Forgejo API usage. +2. **Provide standardized metadata** (prefix, issue type, reporting interval) when invoking the manager so titles remain consistent. +3. **Populate the body using the template**, including summary, details, health indicators, and next actions. +4. **Capture meaningful health signals** (queues, failure counts, outstanding actions) that supervisors can act on. +5. **Persist the returned issue number** for subsequent updates during the same cycle. ### Agent-Specific Implementation Details #### session-persister - **Cycle Frequency**: Every checkpoint (variable timing) -- **Issue Type**: Checkpoint +- **Issue Type**: Session State Tracking - **Content**: Session state, active agents, configuration -- **Cleanup**: Deletes previous checkpoint issue +- **Cleanup**: Handled by automation-tracking-manager #### implementation-pool-supervisor -- **Cycle Frequency**: Health reports every 10 cycles, status every 5 cycles -- **Issue Types**: Health Report, Status Update +- **Cycle Frequency**: Status updates every 5 cycles; comprehensive health reports every 10 cycles +- **Issue Types**: Status Update, Health Report - **Content**: Worker status, queue health, completion metrics -- **Cleanup**: Deletes previous health/status issues separately +- **Cleanup**: Handled by automation-tracking-manager #### system-watchdog-pool-supervisor - **Cycle Frequency**: Every monitoring cycle (variable timing) -- **Issue Types**: System Health, Alert +- **Issue Type**: System Health Report - **Content**: Quality gates, system violations, corrective actions -- **Cleanup**: Deletes previous system health issues +- **Cleanup**: Handled by automation-tracking-manager #### backlog-grooming-pool-supervisor -- **Cycle Frequency**: Every grooming cycle (~30 minutes) +- **Cycle Frequency**: Grooming report every 5 minutes; scope alerts every 50 minutes (10 cycles) - **Issue Types**: Grooming Report, Scope Alert - **Content**: Issues processed, duplicates found, orphans discovered -- **Cleanup**: Deletes previous grooming reports, acts as backup cleanup agent +- **Cleanup**: Handled by automation-tracking-manager #### human-liaison-pool-supervisor - **Cycle Frequency**: Status every 10 cycles -- **Issue Types**: Status Update, Human Activity Summary +- **Issue Type**: Human Activity Report - **Content**: Human interactions, triage decisions, outstanding items -- **Cleanup**: Deletes previous status updates +- **Cleanup**: Handled by automation-tracking-manager + +#### docs-writer +- **Cycle Frequency**: Documentation reports every 10 cycles (~3.3 hours) +- **Issue Type**: Documentation Report +- **Content**: Docs created/updated/skipped, commit hash, milestone coverage +- **Cleanup**: Handled by automation-tracking-manager + +#### timeline-updater +- **Cycle Frequency**: Per-commit (variable timing) +- **Issue Type**: Timeline Update +- **Content**: Timeline changes, schedule adherence entries +- **Cleanup**: Handled by automation-tracking-manager + +#### project-owner +- **Cycle Frequency**: Per-triage-cycle (variable timing) +- **Issue Type**: Project Triage Report +- **Content**: Issues triaged, MoSCoW assignments, priority decisions +- **Cleanup**: Handled by automation-tracking-manager + +#### product-builder +- **Cycle Frequency**: Per-build-cycle (variable timing) +- **Issue Type**: Product Builder Status +- **Content**: Build orchestration status, worker pool health +- **Cleanup**: Handled by automation-tracking-manager ## Searching and Filtering @@ -355,6 +387,7 @@ label:"Automation Tracking" [AUTO-MERGE] in:title label:"Automation Tracking" [AUTO-UAT-POOL] in:title label:"Automation Tracking" [AUTO-PROJ-OWN] in:title label:"Automation Tracking" [AUTO-EVLV] in:title +label:"Automation Tracking" [AUTO-EPIC] in:title label:"Automation Tracking" [AUTO-BUG-POOL] in:title label:"Automation Tracking" [AUTO-SPEC] in:title label:"Automation Tracking" [AUTO-INF-POOL] in:title @@ -408,15 +441,16 @@ Example: `[AUTO-WATCHDOG] Announce: CRITICAL: CI pipeline down — all merges bl ## Cleanup Protocol -### Primary Cleanup (Each Agent) -- Each agent deletes its own previous cycle tracking issues before creating new ones -- Preserves announcement issues which use different title format -- Runs cleanup before every new tracking issue creation +### Primary Cleanup (automation-tracking-manager) +The `automation-tracking-manager` subagent handles all primary cleanup: +- Closes the previous cycle's tracking issue before creating a new one +- Preserves announcement issues (different title format — no `(Cycle N)` suffix) +- Runs cleanup atomically as part of every `CREATE_TRACKING_ISSUE` operation ### Secondary Cleanup (backlog-groomer) The backlog-groomer acts as a backup cleanup agent: - Scans for stale automation tracking issues older than 7 days -- Deletes abandoned tracking issues from agents that may have crashed +- Closes abandoned tracking issues from agents that may have crashed - Preserves announcement issues and recently created tracking issues - Reports cleanup activity in its own tracking issues @@ -466,17 +500,25 @@ If tracking issues accumulate excessively: ## Migration Notes -This system replaced the previous shared session state issue approach. Key differences: +### Phase 1 — Individual Tracking Issues (completed) + +Replaced the previous shared session state issue approach: - **Before**: All agents posted comments to single issue #[session-state-issue-number] - **After**: Each agent creates individual tracking issues with standardized titles - **Benefit**: Eliminates noise, improves searchability, enables targeted cleanup -The migration was completed by updating agent definitions in `.opencode/agents/` directory to: -- Remove session state issue posting -- Add tracking issue creation functions -- Implement cleanup protocols -- Apply standardized formatting +### Phase 2 — Centralized Tracking Manager (completed) + +Replaced direct Forgejo API calls in each agent with the `automation-tracking-manager` subagent: + +- **Before**: Each agent implemented its own tracking issue creation, cleanup, and cycle management +- **After**: All agents delegate to `automation-tracking-manager` as the single source of truth +- **Benefit**: Eliminates duplicate issues, ensures cycle continuity across restarts, prevents agents from commenting on stale issues +- **Breaking change**: `shared/automation_tracking.md` was removed; agents now use the subagent pattern + +The migration updated these agents: `system-watchdog`, `implementation-orchestrator`, +`timeline-updater`, `project-owner`, `product-builder`, `backlog-groomer`. A second migration introduced the centralized `automation-tracking-manager` subagent to prevent cycle reuse issues where agents were commenting on old tracking issues @@ -485,5 +527,6 @@ instead of creating new ones. ## Related Documentation - [System Watchdog](system-watchdog.md) - Specific documentation for watchdog agent +- [Documentation Writer](docs-writer.md) - Documentation writer agent reference - [Quality Automation](quality-automation.md) - Quality gate automation details - [Ops Runbook](ops-runbook.md) - General operational procedures diff --git a/docs/development/docs-writer.md b/docs/development/docs-writer.md new file mode 100644 index 000000000..31c64c23e --- /dev/null +++ b/docs/development/docs-writer.md @@ -0,0 +1,131 @@ +# Documentation Writer Agent + +**Agent**: `docs-writer` +**Tracking Prefix**: `AUTO-DOCS` +**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 +and milestone completions, and keeps project documentation current without human +intervention. + +--- + +## Responsibilities + +| Task | Output | +|------|--------| +| README updates | `README.md` — new features appended to Highlights | +| API documentation | `docs/api/` — one file per module | +| Architecture overview | `docs/architecture.md` — component map, data flow | +| Changelog entries | `CHANGELOG.md` — Keep-a-Changelog format | +| Module documentation | `docs/modules/` — per-module usage guides | + +The agent **extends** existing documentation; it never overwrites content that +is already accurate. + +--- + +## Monitoring Loop + +``` +last_sha = master HEAD +cycle = 0 + +LOOP: + cycle += 1 + + # Create tracking issue every 10 cycles + if cycle % 10 == 0: + automation-tracking-manager: CREATE_TRACKING_ISSUE + agent_prefix: AUTO-DOCS + tracking_type: Documentation Report + + # Pull latest code + git fetch && git reset --hard origin/master + current_sha = HEAD + + if current_sha == last_sha and cycle > 1: + sleep 20 minutes + continue + + last_sha = current_sha + + # Check for documentation-worthy changes + query recently merged PRs + check milestone completions + run_docs_update() if changes found + + sleep 20 minutes +``` + +The agent uses `sleep 1200` (20-minute intervals) between cycles and never +voluntarily exits. + +--- + +## Automation Tracking + +The `docs-writer` participates in the [Automation Tracking System](automation-tracking.md) +via the `automation-tracking-manager` subagent. + +### Tracking Issue Format + +``` +Title: [AUTO-DOCS] Documentation Report (Cycle N) +``` + +**Default label** (applied automatically by the manager): + +| Label | Purpose | +|-------|---------| +| `Automation Tracking` | Enables system-watchdog health monitoring | + +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. + +### Cleanup Protocol + +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 + +Announcement issues (`[AUTO-DOCS] Announce: …`) are **never** deleted. + +--- + +## Documentation Standards + +All documentation produced by this agent follows the project's +[CONTRIBUTING.md](../../CONTRIBUTING.md) documentation standards: + +- **Continuous documentation** — updated alongside code, not after the fact +- **Single documentation surface** — one canonical location per doc type +- **Traceability** — logical references, not line numbers +- **MkDocs-compatible** — all files are valid MkDocs Markdown + +--- + +## 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). + +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. + +Since `master` is a protected branch, all documentation changes are submitted +as pull requests from a feature branch. + +--- + +## Related Documentation + +- [Automation Tracking System](automation-tracking.md) — full tracking system reference +- [System Watchdog](system-watchdog.md) — health monitoring that watches this agent +- [Quality Automation](quality-automation.md) — quality gate context diff --git a/mkdocs.yml b/mkdocs.yml index f7c707117..2bb05974c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,6 +38,7 @@ nav: - System Watchdog: development/system-watchdog.md - Automation Tracking: development/automation-tracking.md - Custom Sandbox Strategy: development/custom_sandbox_strategy.md + - Documentation Writer: development/docs-writer.md - Implementation Timeline: timeline.md - FAQ: faq.md - Reference: reference/