Workflows: Docs Maintenance (Chain B)

The docs-maintenance workflow (Chain B, Option-C) automates the generation and human-in-the-loop (HIL) approval of documentation updates.

Workflow Structure (v2)

The workflow is defined in workflows/docs-maintenance-optionc.json and follows a linear chain: schedule → transform(instruction) → inai-agent → send-email → custom-hil → chat-output

• schedule: Triggers the workflow.
• transform(instruction): Prepares instructions for the agent.
• inai-agent: Generates the proposed documentation updates based on recent project journals.
• send-email: Delivers the proposed markdown to the approver's email before the approval gate.
• custom-hil: A human-in-the-loop gate where the owner reviews and approves/rejects the proposal.
• chat-output: Carries the email delivery acknowledgment ({sent:true, id, status}).

Email Configuration

• Provider: Resend (configured via apiKey:{{secret.RESEND_KEY}})
• From: onboarding@resend.dev (Resend's shared test sender, delivering to the account owner)
• Subject: "Proposed documentation updates — please review"
• Template: {{input}} (injects the markdown generated by inai-agent)

Design Tradeoffs

• Chat Output: The final chat-output carries the send-email acknowledgment ({sent:true, id, status}) rather than the markdown, as the linear engine replaces the markdown downstream with the email node's output. The human reads the markdown in the email body, and the gate is approve/reject.

Grounding and Surgical Updates

To ensure documentation remains an accurate reflection of the live system, the maintenance workflow utilizes targeted grounding and surgical editing principles:

Guided Grounding

When initiating a documentation update, practitioners can explicitly direct the agent's attention to specific areas of the codebase. By including a structured directive in the instruction, the agent focuses its analysis on the designated files or directories, ensuring high-fidelity updates for complex feature changes.

Surgical Section Preservation

When modifying existing documentation sections, the system prioritizes preservation over recreation. The agent analyzes the current text and surgically integrates new insights or corrections derived from the codebase. This "augment-by-construction" approach prevents the accidental loss of valuable historical context or human-written explanations.

Automated Leak Prevention

Every proposed change is subjected to an automated, multi-layered safety scan before it is presented for human review. If the proposal contains any sensitive system identifiers, internal configuration keys, or database structures, the update is immediately blocked. A dedicated regression guard continuously verifies that no public-facing documentation target can receive content routed from areas whose monorepo copies carry internal details, ensuring such mappings are de-routed before any proposal is generated. This ensures that public-facing documentation remains clean, secure, and focused entirely on user experience. Proposals that would route architecture or schema material to public paths are refused outright so that only user-visible behavior reaches the published site.

Automated Docs Sync

To streamline continuous documentation updates, the system supports an automated synchronization pipeline (Auto-Docs-Sync) that translates codebase changes directly into proposed documentation updates.

Change-Driven Proposals

Rather than requiring manual triggers, the sync pipeline tracks modifications starting from a verified baseline commit. When changes occur, the system:

1. Filters and Groups: Isolates meaningful source modifications from non-source noise (such as lockfiles, dotfiles, and configuration files) and groups them by functional area.
2. Routes via Area Maps: Maps code directories to their corresponding documentation files using a deterministic routing table (for example, mapping a portfolio directory to its respective user guide).
3. Evaluates Doc-Worthiness: Evaluates whether the changes represent user-facing behavior (such as new features or altered workflows) or internal-only updates (such as refactoring or performance optimizations). Internal-only changes are reported in the dropped list with reasons; unmapped source areas and override-dropped mappings are always surfaced loudly in every outcome.
4. Holds at the Gate: For every doc-worthy change, the pipeline initiates a targeted proposal. These proposals never publish automatically; instead, they are routed to a human-in-the-loop gate for review, ensuring complete human governance over what is finalized.

Customizing the Sync Behavior

Practitioners can customize how code changes map to documentation and how instructions are framed:

• Custom Area Mapping: You can define custom routing rules using a simple glob => doc format (for example, routing specific subfolders to dedicated guides).
• Instruction Templates: You can override the default instructions with custom templates, using placeholders like {{doc}} to dynamically inject the target document path. This allows you to enforce specific style guides or grounding rules across all automated proposals.

Strict Validation of Custom Mappings

When you supply a custom area map, every line is validated before any routing occurs. Malformed entries (missing arrows, empty globs or targets) are rejected with an explicit error that names the offending line. This guarantees that a configuration mistake never silently drops coverage; the pipeline either runs with a complete, verified map or stops so the issue can be corrected.

Bounded Grounding for Proposals

Each assembled proposal is deliberately limited by an effective byte budget (256 KB total, with each file truncated at 64 KB) so the agent remains tightly focused on the actual evidence of change. Changed files are ordered by recency via git log before the cap is applied, ensuring the least-recent files are dropped first when the budget is reached. The pipeline always includes the changed files first, then stable context files only as needed to stay within the bound, ensuring proposals stay surgical and fully grounded in verifiable code behavior.

Coverage Warnings

The pipeline always surfaces unmapped source areas, any areaMap overrides that drop code-default mappings, and any mapped targets that are internal-only (present in the monorepo but absent from the public docs repo) in every outcome summary. These warnings appear regardless of whether proposals are generated, ensuring practitioners can see and address coverage gaps while keeping all documentation updates human-gated and scoped to public-facing content.

Per-Document Sync Markers

Each documentation file maintains its own sync marker alongside a single global floor marker. A proposal that is reviewed and rejected keeps its prior marker, so the same area is re-proposed on the next sweep. Only the specific document that reaches a successful publish advances its marker; sibling areas remain eligible for future proposals. Advancing the global floor never disturbs any per-document marker. This design keeps every human-gated decision visible and prevents one approval from silencing other pending updates.