← Back to directory

documentation.md

governance/documentation.md · 12.9 KB · 2026-11-02 12:48

Documentation Governance

Status: current documentation policy, 2026-09-11. Owns documentation authority, maintenance and terminology routing, not business architecture definitions.

Authority and Scope

Start at the index and authority map. Each concept has one canonical owner. The core object model and authority owns the cross-cutting invariant map while the existing architecture owners retain detailed meanings. A summary, example, index entry, implementation note or historical source must explicitly defer to its owner rather than establish another definition.

The product and architecture documents express the current Idiosyncrasy specification, incorporating the four supplied sources and subsequent human clarifications. The earlier marketing application is reusable UI/implementation material only. There is no data migration, historical-data retention or backward-compatibility obligation to the earlier system. Compatible security/isolation lessons remain valuable; old domain models and product boundaries are superseded.

Implementation guidance must conform to the architecture. Observed code can establish what exists, not what the product must become. Implementation status distinguishes evidence of the new architecture from reusable earlier work.

Explicit human decisions may change the specification. Record such a decision, update the affected canonical owner and its dependents, and update the index when ownership changes. Never leave a decision record, old agent instruction and new canonical prose simultaneously prescribing different behavior. Applicable task instructions still govern the scope of an agent's work; an architectural document is not authorization to implement or deploy.

Final D01-D10 are settled. Precedence is explicit final transcript decisions and subsequent project-owner corrections, then consistent canonical documentation, then repository decisions not superseded, then necessary implementation specification. The earlier open register cannot downgrade final approval. Do not create additional architecture decision numbers. A physical mechanism implements the logical model; missing code or a schema detail does not reopen its semantics.

Document Contract

Every subject document should identify:

An example address, state list, configuration shape or numbered walkthrough is not an approved physical schema or transaction algorithm unless explicitly designated as such. Source material that only established a requirement must not be rewritten as a settled implementation choice.

Three Independent Status Axes

| Axis | Meaning | |---|---| | Documentation authority | Current direction; proposed decision; superseded; reference only. | | Product scope | Foundational requirement; candidate MVP depth; later capability; excluded initially. The roadmap owns release scope. | | Implementation evidence | Not verified, partial or verified for a specified requirement and check, with date and limitations. |

A settled architectural requirement is not proof of a working feature. A future capability can depend on a settled foundational invariant. The original rewrite verification is historical; final D01-D10 supersede its open-decision classifications. Implementation documents use separate settled semantic contract, chosen implementation mechanism and current implementation status fields. Do not equate SPECIFIED with BUILT or VERIFIED.

Canonical Terminology Routes

This is a lookup index, not a second glossary of definitions.

| Terms | Canonical definition | |---|---| | Object, id, type, value, durable authority, addressability, Type, controlled genesis | Objects and types | | Cross-cutting object, definition, derived State, history, workflow-boundary and authority invariants | Core object model and authority | | Engine, Capability, Capability Definition, capability instance/configuration, Application, extension levels, new-engine test | Composition and extensibility | | Business Graph, Relationship, Assertion, contextual applicability, Business DNA | Business model | | Business identity, creation provenance, administration and authority lifecycle | Identity and governance and Business model | | Subscription state, entitlement, commercial model (Licensed and Guest counting), unsubscribed Business, activation and lapse, suspension retention and operational gate (intended future architecture; not implemented) | Subscriptions and entitlements | | Rule, Policy, Constraint, Goal, Decision | Semantics | | Operation, Operation Contract, Operation Invocation and their boundary to Command, Policy and evidence | Operation Contract | | Event, version, state-transition occurrence, coherent history, effective/recorded time, audit | Time and events | | Knowledge, provenance, authority, confidence, institutional memory | Knowledge | | Structured retrieval, context assembly, derived index | Retrieval | | Workflow, Command, Action Execution, Attempt, Outcome, commit, retry/recovery | Workflows and automation | | User (authenticated account and platform identity), Person (Business-scoped individual profile), User account versus Person profile, Licensed User, Guest User, Business-scoped isolation, membership, permission, approval, delegation (including delegated authority for automation), autonomy. "Principal" is superseded terminology for User. | Identity and governance | | View, Projection, form, content, media, variant, holistic and attention-first presentation | Views and content | | Communication, notification, integration, adapter, normalized tool | Communication and integrations | | Metric, observation, optimisation proposal, improvement loop | Analytics and evolution | | AI invocation, provider boundary, generated proposal, materialised validation determination | AI |

Use the same engine names as the responsibility map. Do not use "module", "table", "service" or a PHP class name as a synonym for Engine. Avoid using "automation" for unrelated saved editor work or a workspace merely because the previous interface did so. Conceptual layers and engine responsibilities are complementary maps, not competing counts of software components.

Maintenance and Approval

1. Identify the canonical owner and inspect its dependencies before editing. 2. Classify the change: clarification of an agreed invariant, new architectural decision, implementation observation or historical correction. 3. Preserve final D01-D10. Specify ordinary physical details in implementation owners, not as new architecture decisions; any proposed change to settled semantics requires explicit project-owner direction rather than an implicit implementation shortcut. 4. Edit the owner; change dependent summaries to links or faithful summaries, not independent restatements. 5. Update source traceability, implementation evidence and decision status where affected. 6. Validate relative links and heading anchors, document statuses, source coverage and the absence of conflicting active definitions.

The project owner maintains approval of architecture and scope changes. Named specialist reviewers and review scheduling are administrative assignments, not numbered architecture decisions. Final D10 concerns Knowledge, not documentation maintenance. Preserve explicit approval evidence and never invent absent transcript titles or deliberation.

Granularity and Archive Policy

The current governed active set is 35 documents: the 34 measured on 2026-09-23 (entrypoints, governance, architecture, product and implementation guidance, including the additional core object model and authority document, which owns a meaningful cross-cutting conceptual contract that should not be duplicated across one detailed owner) plus the readiness register. The readiness register was added as the 35th active document on the explicit 2026-10-28 instruction to maintain one authoritative record of temporary and deferred items; it owns that concept and no other document may. Verified against the filesystem on 2026-11-02, 46 Markdown files exist under docs/ outside archive/ and reference/: the 35 governed documents; four dependent implementation records added later (the Stage 3D owner decision request and production evidence request, which the index lists as external handoffs, plus the data-defined semantics audit and the Products & Services semantic proposal, which the index does not list), each of which records evidence, a request or a proposal and owns no architectural concept; and seven historical or stale documents outside the structure and authority map (docs/Phase-8-Completion-Summary.md, docs/Phase-8-Validation-Checklist.md, implementation/Phase-8-Implementation-Status.md, implementation/PHASE-7-COMPLETION.md, implementation/UI-CAPABILITY-PROJECTION-FIX.md, implementation/PRESENTATION-DRIVEN-OBJECT-EXPLORER.md and implementation/PRESENTATION-GRID-ARCHITECTURE-BASELINE.md, recorded as PRR-048). Dependent records and historical documents are not canonical owners and do not count towards the 35. Do not create one document per engine or per old screen. Before proposing another split ask: "Does this document own a meaningful architectural concept that another document should not own?" Otherwise consolidate. Further expansion requires a justified human decision and a corresponding authority-map update.

The four original architecture sources are preserved byte-for-byte under the archive. They are valuable architectural lineage, not obsolete marketing architecture. Their useful decisions live in active successors; discrepancies are resolved by current specification and human clarification, not by treating archival text as a second current definition.

Other old documents are removed from the active set after compatible content is accounted for in the source ledger. Preserve selective implementation lessons in reference notes; do not archive every redundant old document or silently leave obsolete prescriptions discoverable as current.

Reading and Validation Routes

Product readers: definition -> capabilities -> roadmap. Architecture readers: overview -> objects/types -> business model, semantics, time and governance -> knowledge/retrieval -> execution/presentation/integrations -> analytics/evolution and AI. Read cross-cutting prerequisites where an individual task needs them; this is not a requirement to load the whole repository.

Builders then read implementation architecture, relevant UI/operations/WordPress guidance, development checks and status. Archive/reference documents are excluded from the default agent route and never substitute for a canonical prerequisite.

For documentation-only work, validate links, anchors, source preservation, scope and contract/mechanism/evidence separation. Do not run application setup, change schemas, start workers or claim runtime verification as part of prose validation. The development guide owns application checks when implementation is separately authorized.