Project Maintainer

Project Maintainer

Maintain .doc_project_maintainer/ as a compact, agent-readable project map. Use modules for capability boundaries, directories for source evidence, flows for causal behavior across boundaries, and code symbols for executable detail.

Task Intent Router

Classify the task before reading the artifact or running a script.

Maintenance-Aware Fix Mode

Use this mode for a bug fix, feature change, or refactor. Project Maintainer supplies context and preserves affected knowledge; it must not become the primary debugging workflow.

Use the scoped profile by default:

1. Check whether .doc_project_maintainer/ exists without creating files.
2. Read only artifact slices related to the target paths. Prefer scripts/project_context.py when available.
3. Find applicable active failure evidence before trusting lower-level passing tests.
4. Reproduce, diagnose, implement, and verify through the normal development workflow.
5. Synchronize only existing claims directly contradicted or affected by the verified change. Record missing unrelated documentation as pending; do not block the code repair on repository-wide coverage.
6. Keep bugfix synchronization separate from formal symbol health audit. A bugfix may update Actual Role, behavior, tests, verification links, and known risk, but it must not promote agent_audited unless the user requested an audit and the audit workflow was completed.

Load references/scoped-maintenance.md for every code change that uses this skill. Load references/evidence-and-verification.md when evaluating test sufficiency, unresolved failures, or completion claims.

Use the expanded profile when the change affects a public contract, module or process boundary, persistence or recovery, security or permissions, resource ownership, concurrency, shutdown, or multiple externally relied-on flows. Expanded maintenance reads additional relevant slices and risk references; it still does not imply full inventory or coverage closure.

If the artifact or target slice is unavailable, continue source-based debugging. Do not ask the user to analyze the repository first unless analysis is itself required to make the requested code change safely.

Knowledge Base Delivery Mode

Use this mode when .doc_project_maintainer/ is the requested output: initialize, analyze, map, document, summarize, make current, or deliver full repository coverage.

1. Run the delivery preflight in references/repository-delivery.md.
2. Build or refresh only the requested slices unless the user requests complete coverage.
3. For complete or project-wide goals, continue until coverage closure has no actionable pending slices; otherwise report the artifact as partial with the exact next slice.

Load references/artifact-structure.md, references/templates.md, and references/repository-delivery.md before creating or broadly revising an artifact.

Audit Delivery Mode

Use this mode only when the user requests source-symbol coverage, health/risk audit, trusted audit state, integrity verification, or an audit report.

Load references/audit-workflows.md and references/code-symbol-docs.md. Full audit work remains strict: scripts may inventory, queue, validate, or record reviewed results, but they must not bulk-generate health or impersonate an agent/human audit.

Read-Only And Signing Boundary

Keep queries and checks read-only unless the user requested an artifact mutation.

• Do not run audit_integrity.py ensure-key during ordinary preflight.
• Reading, context lookup, inventory without output paths, sync checks, integrity verify, and integrity report must not create a signing key.
• Create or reuse a key only for promote, explicit signing, or an explicit ensure-key request.
• If verification has no environment key and no existing artifact key, report the audit as unverifiable; do not create a key to make verification pass.
• Treat the artifact-local key as workflow integrity, not a tamper-proof security boundary.

Evidence And Completion Gate

Rank evidence by applicability first, then freshness, realism, and directness. For otherwise comparable evidence, use:

live or real-provider
> real integration
> synthetic integration
> mock or unit
> static analysis
> documentation claim

Scenario labels such as subprocess lifecycle, cancellation, replay, or shutdown describe coverage; they are not separate evidence levels.

Do not claim fixed, working, current, or verified while a newer applicable high-level failure remains active and only weaker evidence passes. Close the conflict only with post-fix evidence for the same scenario or stronger, an explicit supersession/invalidity record, or a clearly disclosed accepted limitation. Use the structured record contract in references/evidence-and-verification.md.

Scope And Status

Keep global coverage separate from the current task slice:

global_coverage_status: current | partial | stale | unknown
task_slice_sync_status: current | pending | unavailable

• A scoped run may set the task slice current; it must not promote global coverage.
• A fully synchronized local change does not automatically downgrade an already-current artifact.
• An unsynchronized affected claim makes the task slice pending and may make global coverage stale.
• A pre-existing partial artifact remains globally partial even when the task slice is current.

Bugfix Sync Versus Symbol Health Audit

Bugfix sync updates facts established by the change: affected behavior, Actual Role, contracts, tests, verification evidence, flow consequences, known risk, and a meaningful change record when warranted. Do not require missing historical docs to be created during the fix.

Formal health audit is separate. Use it only when requested. It requires implementation and evidence review, health dimensions and issues, controlled promotion, and integrity verification. scripts/inventory_symbols.py is not an auditor and must not mark a symbol agent_audited.

Agent Symbol Audit Contract

• For a single symbol audit, personally read the implementation, relevant callers/callees, tests or missing-test evidence, and linked flows before recording health.
• For multiple symbol audits, use one audit agent per required symbol by default when independent agents are available.
• An assignment is incomplete until that agent's recent call signature batch promotes the exact symbol to audit.status: agent_audited and verification classifies it as trusted_agent_audit.
• Missing signatures downgrade to script_assessed; the symbol remains pending.
• If independent audit agents are unavailable, keep the requested audit partial. Scripts may only inventory, queue, validate, or record reviewed results and must not bulk-generate health.

Reference Router

• Code change or defect repair: read references/scoped-maintenance.md.
• Evidence comparison or verification record: read references/evidence-and-verification.md.
• Artifact initialization, full analysis, git history, flows, or closure: read references/repository-delivery.md plus references/artifact-structure.md and references/templates.md as applicable.
• Inventory, coverage maps, symbol audit, integrity, or HTML report: read references/audit-workflows.md and references/code-symbol-docs.md.
• Async streams, cancellation, resource ownership, or shutdown: also read references/resource-lifecycle-checklist.md.

Read only references selected by the router. Do not load all references for a scoped task.

Final Response Checklist

For every task using this skill, state:

• whether .doc_project_maintainer/ exists;
• whether the task used scoped, expanded, knowledge-base, or audit delivery;
• whether the task slice is current, pending, or unavailable;
• whether affected flow and code-symbol facts were updated, not applicable, or pending;
• any active higher-level failure that limits the completion claim;
• whether any command created or modified audit integrity artifacts.

For complete delivery or audit work, also state the global coverage/audit status, closure source, pending slices, inventory and audit summaries, and report freshness. Never describe a project-wide goal as complete while actionable requested-scope slices remain.

Validation

• Run tests for every changed script.
• Run scripts/check_doc_sizes.py with --profile scoped for scoped maintenance and --profile full for complete delivery.
• Run the skill-creator quick_validate.py after changing skill metadata or structure.
• Regenerate project/audit-report.html if its source ledgers or integrity report changed after generation.