feat(aidd-context): audit the project context architecture and ownership #793

Problem

AIDD gives a project several places to store AI and team context: AGENTS.md, rules, skills, project memory, aidd_docs/GUIDELINES.md, aidd_docs/CONTRIBUTING.md, recipes, ADRs, specifications, and ordinary documentation. Each artifact can be useful on its own while the whole context architecture becomes unclear: the same fact may live in several places, an always-loaded instruction can contain material that should be consulted on demand, a durable decision can lack an owner, or a team-owned template can remain an unfilled placeholder.

The result is context that is harder to maintain, more likely to drift, and unnecessarily expensive to load. There is no current AIDD capability that inventories these artifacts together, identifies the owner and loading role of each piece of information, and reports architectural problems without changing the project.

The question is not whether information is useful in isolation, but whether it has one clear source of truth in the right AIDD artifact and is loaded at the right time.

Scope

• Discover the AIDD and project context artifacts that exist in the current project, including AI instruction files, rules, skills, project memory, aidd_docs guidance, recipes, ADRs, specifications, and documentation.
• Build a read-only inventory that records each artifact's purpose, loading role (always-loaded or on-demand), and likely ownership of the information it contains.
• Detect information duplicated across context mechanisms, and identify the involved sources and a proposed canonical owner.
• Detect information stored in an unsuitable artifact, including always-loaded context that is better represented as a recipe, skill, memory entry, ADR, guideline, or on-demand documentation.
• Detect unclear source-of-truth ownership and context likely to drift because it is maintained in several places.
• Detect expected team-owned context artifacts that are absent, empty, or still contain unfilled placeholders where the project supplies evidence that they should be completed.
• Produce a readable, read-only report with evidence, confidence, and a suggested remediation for each finding.
• Orchestrate local, read-only inspection results from the responsible capabilities for memory, rules, skills, commands, agents, hooks, and learning artifacts.
• Require explicit user approval before moving, deleting, rewriting, or consolidating any project context.
• Keep the cross-artifact audit responsible only for correlation; after approval, route remediation to the owning capability one change at a time.

Local inspection and correlation boundary

• Each responsible capability exposes an inspection result for its own artifact surface.
• Each result identifies the artifact, purpose, scope, loading role, local findings, evidence, and confidence.
• The cross-artifact audit correlates those results for duplicated policy, unclear source of truth, unsuitable loading mode, and missing expected context.
• Local inspections must not call back into the cross-artifact audit, and the default workflow must not write.
• The audit does not define the semantic Project Memory model; it uses the documented contract from docs(aidd-context): document the Project Memory model and lifecycle #801 when auditing placement and ownership.

Acceptance criteria

• The audit inventories the context artifacts actually present in the project and distinguishes always-loaded from on-demand material.
• Each responsible context capability can provide a local read-only inspection result for its own artifact type.
• Each inspection result identifies the artifact, purpose, scope, loading role, local findings, evidence, and confidence.
• The cross-artifact audit correlates local results without reimplementing each artifact contract.
• Local inspections do not call the cross-artifact audit.
• When a convention or decision appears in multiple context artifacts, the report identifies every source and recommends one canonical owner without modifying either source.
• When detailed procedural material is stored in always-loaded context, the audit can recommend an appropriate on-demand artifact while preserving the project-specific decision or constraint.
• A missing, empty, or placeholder-only team-owned artifact is reported only when project evidence makes its expected role clear.
• Every finding identifies its source files, category, confidence, and suggested remediation.
• A project with no finding produces a clear clean result rather than invented recommendations.
• Running the default audit does not modify project context files.
• No suggested migration, deletion, or consolidation is applied without explicit user approval.
• After approval, remediation is routed to the owning capability one change at a time.
• The audit does not redefine the Project Memory model or replace docs(aidd-context): document the Project Memory model and lifecycle #801.

Prior art in this repo

• docs/ARCHITECTURE.md assigns capabilities by concern and places context production in aidd-context.
• 02-project-memory creates and refreshes the memory bank, but does not audit the placement of all project context artifacts.
• 11-explore maps the Context axis but explicitly points without prescribing or auditing.
• memory-destinations.md defines destinations within the memory bank, not ownership across all context mechanisms.
• Issue #560 established ownership and no-duplication principles for project-memory templates; this issue extends neither its implementation nor its scope, but applies that architectural question across the context layer.
• Issue #585 defines ownership for human policy configuration keys, not an audit of project context artifacts.
• Issue #618 addresses verification dates and source-backed facts in per-tool references, not cross-artifact context ownership.
• Issue #791 prevents a new rule from overlapping an existing rule during generation.
• Issue #792 audits an existing rule corpus for semantic consistency and context efficiency.
• Issue #801 documents the Project Memory model and lifecycle; this issue consumes that contract rather than redefining it.

I searched open and closed issues and pull requests for context architecture, context audit, artifact ownership, always-loaded context, source of truth, and wrong artifact. No existing proposal covers this cross-artifact, read-only audit.

Out of scope

• Auditing semantic conflicts, duplication, or context-efficiency inside the rule corpus; that belongs to feat(aidd-context): audit an existing rule corpus for conflicts, duplication and drift #792.
• Preventing overlap while generating a candidate rule; that belongs to feat(aidd-context): check existing rules for overlap or conflicts during rule generation #791.
• Verifying the factual accuracy or date of individual vendor-reference claims; that belongs to fix(aidd-context): source-backed tool references, with dates and unverified cells #618.
• Defining the semantic Project Memory model; that belongs to docs(aidd-context): document the Project Memory model and lifecycle #801.
• Automatically moving, deleting, rewriting, or merging context artifacts.
• Auditing application source-code quality, architecture, security, performance, dependencies, tests, or UI.
• Defining a universal precedence model for every host AI tool.