Knowledge Commons

Requirements and Specifications: Difference between revisions

Newer edit →
VisualWikitext
Created page with "This page."
 
No edit summary
Line 1: Line 1:
This page.
# Wiki Farm PARA Mode
## Functional Requirements and Technical Specification
 
**Document purpose:** This specification defines the first implementation of the structured personal knowledge management ("PARA Wiki") mode for a MediaWiki-based wiki farm. It is intended to be sufficiently explicit for use by a software developer or coding AI.
 
**Status:** Draft implementation specification 
**Version:** 1.0 
**Target platform:** MediaWiki with Cargo and custom extension code 
**Primary design principle:** Preserve normal MediaWiki behavior wherever practical, while adding an optional structured PKM mode.
 
---
 
# 1. Product Scope
 
## 1.1 Wiki Modes
 
When a user creates a new wiki, the system shall support a configurable **Wiki Mode**.
 
Initial supported modes:
 
| Mode | Description |
|---|---|
| `standard` | Flexible MediaWiki experience with optional starter content. Structured PARA rules are not enforced. |
| `para` | Structured personal knowledge management mode inspired by PARA and extended with Page Type, Page Status, Areas, Projects, Topics, type-specific metadata, and topic-specific metadata. |
 
The architecture shall allow additional modes to be introduced later without redesigning the page metadata model.
 
The selected Wiki Mode shall be stored at the wiki level, not page level.
 
The user-facing name shall be **PARA Wiki**, but documentation should describe it as "inspired by the PARA method" rather than implying that every feature is part of Tiago Forte's original PARA methodology.
 
---
 
# 2. Core Concepts
 
Every normal content page in PARA Wiki mode shall have:
 
- exactly one `PageType`
- exactly one `PageStatus`
 
A page may also have:
 
- zero or one `ParentArea` when `PageType=Area`
- zero or more `RelatedAreas` when `PageType!=Area`
- zero or more `RelatedProjects`
- zero or more `RelatedTopics`
- zero or more type-specific metadata fields
- zero or more topic-specific metadata fields
 
Conceptual definitions:
 
| Dimension | User-facing question | Meaning |
|---|---|---|
| Type | How will I use this page? | The functional role of the page. |
| Status | Is it currently relevant/active? | The lifecycle state of the page. |
| Area | What ongoing part of my life does it support? | An ongoing responsibility, activity, or intentionally maintained domain. |
| Project | What outcome does it support? | A finite outcome or goal. |
| Topic | What is it about? | A subject used to connect related pages. |
 
---
 
# 3. Page Types
 
The application shall initially support exactly six Page Types. Users shall not be able to create custom Page Types in version 1.
 
| PageType | Description | Guidance |
|---|---|---|
| `Study` | Notes derived from a source or structured learning. | Knowledge being acquired from a particular source, class, book, course, lecture, etc. |
| `Journal` | Chronological experience or reflection. | What happened or what the user experienced. |
| `Idea` | A concept, conclusion, insight, or synthesized thought. | An understanding the user developed rather than merely collected. |
| `Project` | Information supporting an intended finite outcome. | Something the user is trying to complete. |
| `Area` | An ongoing part of life that the user maintains or develops. | An ongoing responsibility, activity, or domain without a defined end. |
| `Resource` | Information collected primarily for future reference. | Information likely to have more use in the future than at the time it is stored. |
 
Recommended stable internal identifiers:
 
```text
study
journal
idea
project
area
resource
```
 
---
 
# 4. Page Statuses
 
The application shall initially support three Page Status values:
 
```text
inception
active
archived
```
 
Users shall not be able to create custom statuses in version 1.
 
| PageType | Inception | Active | Archived |
|---|---:|---:|---:|
| Study | No | Yes | Yes |
| Journal | No | Yes | Yes |
| Idea | No | Yes | Yes |
| Project | Yes | Yes | Yes |
| Area | Yes | Yes | Yes |
| Resource | No | Yes | Yes |
 
Definitions:
 
| Status | Meaning |
|---|---|
| `Inception` | Being considered or developed but not yet committed. |
| `Active` | Currently relevant, maintained, pursued, or available for normal use. |
| `Archived` | Retained but no longer active. |
 
Status shall affect default inclusion in views, selectors, reports, workflows, and search filters.
 
Status shall **not** determine authorization, sharing, privacy, or security permissions.
 
Archived pages shall remain directly accessible to users who otherwise have permission to view them.
 
---
 
# 5. Area Model
 
## 5.1 Area Definition
 
An Area is an ongoing responsibility, activity, or something the user intentionally maintains or develops over time.
 
Examples include Personal, Family, Household, Learning, Career, Travel & Vacations, Hobbies, Photography, Cooking, and Fitness & Nutrition.
 
## 5.2 Parent Area
 
An Area page may have zero or one `ParentArea`.
 
A page whose `PageType=Area` shall not use `RelatedAreas`.
 
Examples:
 
```text
Hobbies
  ParentArea = NULL
 
Photography
  ParentArea = Hobbies
 
Cooking
  ParentArea = Hobbies
 
Career
  ParentArea = NULL
 
Skills development
  ParentArea = Career
```
 
A top-level Area is defined as:
 
```text
PageType = Area
ParentArea = NULL
```
 
The system shall prevent an Area from being its own parent and shall prevent circular Area relationships.
 
The Area hierarchy shall support an arbitrary practical depth unless implementation limitations require a documented maximum.
 
## 5.3 Related Areas
 
A non-Area page may have zero or more `RelatedAreas`.
 
Each value shall reference an existing page whose `PageType=Area`.
 
When assigning an Area through the UI, the default picker shall show active Area pages. The user may enable an option such as **Include archived Areas**.
 
The Area picker should display hierarchy where practical.
 
The system should recommend no more than three Related Areas per page but shall not enforce a hard maximum.
 
---
 
# 6. Project Model
 
A Project is a page whose `PageType=Project`.
 
A Project shall normally have at least one `RelatedArea`, although this shall be a quality warning rather than a hard validation rule.
 
A page may have zero or more `RelatedProjects`.
 
Each Related Project shall reference an existing page whose `PageType=Project` and is Active by default in selectors. The picker shall allow archived Projects to be included optionally.
 
The system shall prevent a Project page from assigning itself as a Related Project.
 
Project hierarchy / `ParentProject` is explicitly out of scope for version 1, but the schema shall not preclude adding it later.
 
---
 
# 7. Project-to-Area Defaulting
 
When a Project is assigned to a page:
 
1. Read the selected Project's `RelatedAreas`.
2. Add any missing Project Areas to the edited page's `RelatedAreas`.
3. Do not remove any existing Areas.
4. Allow the user to remove any newly added Areas before saving.
5. Once the page is saved, the values are independent.
 
This behavior is **default copying**, not dynamic inheritance.
 
If the Project's Areas change later, existing pages assigned to that Project shall not automatically change.
 
---
 
# 8. Topic Model
 
## 8.1 Topic Is Not a Page Type
 
`Topic` shall not be added as a seventh PageType. PageType answers **How will I use this page?** Topic answers **What is this page about?**
 
## 8.2 Topics as First-Class Classification Objects
 
Topics shall be first-class application objects.
 
Recommended implementation:
 
```text
Topic:<TopicName>
```
 
using a dedicated MediaWiki namespace.
 
Examples:
 
```text
Topic:Python
Topic:Programming
Topic:Freshman Courses
Topic:Rome
```
 
Topic namespace pages are classification/hub objects and are not ordinary PARA knowledge pages. Topic pages shall not require a PageType.
 
A Topic should support at least:
 
| Field | Requirement |
|---|---|
| TopicName | Required, unique within the wiki |
| TopicStatus | Active or Archived |
| Description | Optional |
| RelatedTopics | Optional/future-safe |
| MetadataDefinition | Optional structured definition of topic-specific fields |
| CreatedAt | System managed |
| UpdatedAt | System managed |
 
Version 1 may omit RelatedTopics and MetadataDefinition UI if necessary, but the data model should allow future implementation.
 
## 8.3 Related Topics
 
Normal content pages may have zero or more `RelatedTopics`.
 
Each Related Topic shall reference an existing Topic object. Default picker behavior shall show active Topics, with an option to include archived Topics.
 
The system should recommend no more than three Topics per page for simplicity but shall not enforce a hard maximum.
 
## 8.4 Topic Creation
 
The RelatedTopics control should allow selecting an existing Topic and optionally creating a new Topic inline, subject to permissions.
 
The system shall prevent accidental duplicate Topics caused only by case differences or excess whitespace, consistent with MediaWiki title behavior.
 
---
 
# 9. Topic-Specific Metadata
 
The architecture shall support topic-specific metadata.
 
For example, `Topic:Book` could define Author, ISBN, Publisher, and PublicationDate. `Topic:Vehicle` could define Make, Model, ModelYear, and VIN.
 
Topic metadata and entity/schema metadata may eventually become separate concepts. Version 1 should therefore implement topic-specific metadata modularly rather than permanently coupling metadata schemas to Topic processing.
 
Recommended abstraction:
 
```text
MetadataDefinition
MetadataField
MetadataAssignment
MetadataValue
```
 
---
 
# 10. Type-Specific Metadata
 
Each Page Type may expose additional metadata. The following fields are illustrative rather than mandatory for version 1.
 
| PageType | Possible metadata |
|---|---|
| Study | SourceType, SourceTitle, Author, Instructor, Institution, StartDate, EndDate, Progress, URL, ISBN |
| Journal | JournalDate, StartDate, EndDate, Location |
| Idea | IdeaDate, Confidence, SourcePages |
| Project | StartDate, TargetDate, CompletionDate, Outcome, Progress |
| Area | ReviewFrequency, LastReviewed |
| Resource | SourceURL, SourceDate, Author |
 
Potential future Project Outcome values include `completed`, `abandoned`, and `cancelled`. Outcome shall remain separate from PageStatus.
 
The type-specific metadata subsystem shall be extensible without schema redesign.
 
---
 
# 11. Unclassified Page Rule
 
Every non-Area page should normally have at least one of `RelatedAreas`, `RelatedProjects`, or `RelatedTopics`.
 
This shall not be a hard save-time validation rule.
 
If all three are empty, the page shall be classified as **Unclassified** for quality/reporting purposes.
 
The page shall display a non-blocking notification such as:
 
```text
This page is not currently associated with an Area, Project, or Topic.
```
 
The user's Status / Wiki Health page shall include an Unclassified Pages section and count.
 
Area pages are exempt from this rule.
 
---
 
# 12. Wiki Health / Status Page
 
PARA Wiki mode shall include a system-generated or extension-generated **Status** or **Wiki Health** page.
 
Minimum metrics:
 
| Metric | Definition |
|---|---|
| Unclassified Pages | Non-Area pages with no Area, Project, or Topic |
| Active Projects Without Areas | Project pages with no RelatedAreas |
| Top-Level Areas | Active Area pages with ParentArea=NULL |
| Sub-Areas | Active Area pages with ParentArea set |
| Archived Pages | Count grouped by PageType |
| Areas With No Associated Content | Areas with no child Areas and no related pages |
| Active Projects With No Recent Activity | Optional if reliable activity logic is available |
 
All metrics should link to filtered page lists.
 
---
 
# 13. Page Metadata UI
 
Recommended user-facing labels:
 
```text
Type
Status
Parent Area
Related Areas
Related Projects
Topics
```
 
Recommended internal field names:
 
```text
PageType
PageStatus
ParentArea
RelatedAreas
RelatedProjects
RelatedTopics
```
 
Do not use numbered fields such as `Area1`, `Area2`, `Area3`, `Project1`, etc.
 
For an Area page, show Type, Status, Parent Area, Related Projects if applicable, and Topics. Hide/disable Related Areas.
 
For a non-Area page, show Type, Status, Related Areas, Related Projects, and Topics. Hide Parent Area.
 
When PageType changes, the UI shall dynamically re-evaluate valid statuses and applicable fields.
 
---
 
# 14. Cargo Storage Model
 
Cargo shall be used for structured querying unless implementation testing identifies a technical blocker.
 
Recommended main table: `WikiPages`.
 
Illustrative schema:
 
```wikitext
{{#cargo_declare:
_table=WikiPages
|PageType=String
|PageStatus=String
|ParentArea=Page
|RelatedAreas=List (,) of Page
|RelatedProjects=List (,) of Page
|RelatedTopics=List (,) of Page
}}
```
 
Requirements:
 
- Store page names as Cargo `Page` values rather than integer IDs unless testing identifies a strong reason otherwise.
- Use Cargo List fields for RelatedAreas, RelatedProjects, and RelatedTopics.
- Use Cargo-supported list querying such as `HOLDS` rather than manually parsing comma-separated strings.
- Topic references using a dedicated namespace may be stored as full titles such as `Topic:Python`.
- Topic data should use a separate Cargo table such as `Topics`.
- Type-specific metadata may use separate Cargo tables rather than making the main table excessively wide.
 
---
 
# 15. Data Integrity Rules
 
| Rule | Enforcement |
|---|---|
| PageType required | Hard |
| PageStatus required | Hard |
| PageStatus valid for PageType | Hard |
| Area has at most one ParentArea | Hard |
| Area cannot use RelatedAreas | Hard |
| Non-Area cannot use ParentArea | Hard |
| ParentArea references Area page | Hard |
| RelatedAreas reference Area pages | Hard |
| RelatedProjects reference Project pages | Hard |
| RelatedTopics reference Topic objects | Hard |
| Area cannot parent itself | Hard |
| Area hierarchy cannot contain cycles | Hard |
| Project cannot relate to itself | Hard |
| Non-Area should have Area, Project, or Topic | Warning |
| Project should have at least one Area | Warning |
| More than three Areas or Topics | Advisory only |
 
Invalid metadata submitted through APIs or non-UI mechanisms shall be rejected consistently with UI validation.
 
---
 
# 16. Archived Object Behavior
 
Archived pages remain accessible.
 
Default behavior:
 
- exclude archived Areas from Area pickers
- exclude archived Projects from Project pickers
- exclude archived Topics from Topic pickers
- optionally exclude archived pages from default dashboards and views
- allow users to explicitly include archived content
- direct links to archived pages continue to work
 
Archived shall not mean deleted and shall not modify sharing/privacy permissions.
 
---
 
# 17. Search and Browse Behavior
 
PARA Wiki shall support filtering/browsing by PageType, PageStatus, Area, Project, and Topic.
 
Examples:
 
```text
Active Study pages in Learning
Resources related to Plan Italy vacation
Pages about Python
Archived pages in Photography
Unclassified pages
```
 
Area browse pages should be able to derive and display child Areas, directly related pages, active Projects associated with the Area, and optionally descendant-Area content.
 
Project browse pages should display Project metadata, Related Areas, pages assigned to the Project, and status/outcome information when implemented.
 
Topic pages should display the Topic description, pages assigned to the Topic, counts by PageType, and derived related Areas and Projects.
 
---
 
# 18. Onboarding
 
When creating a PARA Wiki, onboarding should explain:
 
```text
Type: How will I use this page?
Status: Is it currently relevant/active?
Area: What ongoing part of my life does it support?
Project: What outcome does it support?
Topic: What is it about?
```
 
The user may optionally import starter pages. Starter pages shall be selectable; users should not be forced to import the entire sample set.
 
All imported starter pages should default to `PageStatus=Active` unless explicitly defined otherwise.
 
---
 
# 19. Starter Page Dataset
 
| PageName | PageType | ParentArea | RelatedAreas | RelatedProjects | RelatedTopics |
|---|---|---|---|---|---|
| Personal | Area | | | | |
| Long-term goals | Resource | | Personal | | |
| Weekly tasks | Resource | | Personal | | |
| Gift ideas | Resource | | Personal | | |
| Daily Journal | Journal | | Personal | | |
| Fitness & Nutrition | Area | | | | |
| Tips for healthy eating | Resource | | Fitness & Nutrition | | |
| Yoga | Area | Fitness & Nutrition | | | |
| Why yoga helps me | Idea | | Fitness & Nutrition | | |
| Household | Area | | | | |
| Products | Resource | | Household | | |
| Household Technology | Resource | | Household | | |
| Subscriptions | Resource | | Household | | |
| Family | Area | | | | |
| Family traditions | Resource | | Family | | |
| Family tree | Resource | | Family | | |
| Friends & Social Activities | Area | | | | |
| Poker night planning | Resource | | Friends & Social Activities | | |
| Why Small Gatherings Are More Enjoyable | Idea | | Friends & Social Activities | | |
| Volunteering | Area | | | | |
| Past volunteering | Resource | | Volunteering | | |
| Volunteering opportunities | Resource | | Volunteering | | |
| Vehicles | Area | | | | |
| Honda Accord 2025 | Resource | | Vehicles | | |
| Vehicles being considered for purchase | Resource | | Vehicles | | |
| Learning | Area | | | | |
| List of schools & courses attended | Resource | | Learning | | |
| List of books I have read | Resource | | Learning | | |
| Intro to Python | Study | | Learning, Career | Complete course on Python | Programming, Python |
| Psychology 103 | Study | | Learning | University Degree | Freshman Courses |
| Music Theory 202 | Study | | Learning | University Degree | Freshman Courses |
| Travel & Vacations | Area | | | | |
| Bucket list | Resource | | Travel & Vacations | | |
| Past vacations | Resource | | Travel & Vacations | | |
| Spain Vacation Journal | Journal | | Travel & Vacations | | |
| Travel loyalty programs | Resource | | Travel & Vacations | | |
| Entertainment | Area | | | | |
| Concerts I might want to see | Resource | | Entertainment | | |
| Concert Journal | Journal | | Entertainment | | |
| Movies to rewatch | Resource | | Entertainment | | |
| Hobbies | Area | | | | |
| Photography | Area | Hobbies | | | |
| Canon EOS R10 | Resource | | Photography | | |
| Understanding Exposure by Bryan Peterson | Study | | Photography | | |
| Tips for Low Light Photography | Resource | | Photography | | |
| Cooking | Area | Hobbies | | | |
| Career | Area | | | | |
| Skills development | Area | Career | | | |
| Potential employers | Resource | | Career | | |
| Create family vacation photo book | Project | | Family, Photography | | |
| Replace kitchen floor | Project | | Household | | |
| Plan Italy vacation | Project | | Travel & Vacations, Family | | |
| Hotels in Rome | Resource | | Travel & Vacations, Family | Plan Italy vacation | |
| Complete course on Python | Project | | Career, Learning | | |
| University Degree | Project | | Learning | | |
 
Required starter Topics if the corresponding starter pages are imported:
 
```text
Programming
Python
Freshman Courses
```
 
Starter Project and Topic dependencies shall be handled automatically. No imported starter page may contain a dangling reference.
 
---
 
# 20. Page Creation Workflow
 
1. User enters page title.
2. User selects PageType.
3. System presents valid PageStatus values.
4. Default status should normally be Active.
5. If PageType=Area, show ParentArea and hide RelatedAreas.
6. Otherwise show RelatedAreas and hide ParentArea.
7. Show RelatedProjects.
8. Show RelatedTopics.
9. Load type-specific metadata fields.
10. Load topic-specific metadata fields as Topics are selected.
11. Validate hard rules.
12. Display advisory warnings separately.
13. Save page and structured metadata atomically where practical.
 
The system should minimize clicks and avoid repeated confirmation screens.
 
---
 
# 21. Editing Workflow
 
Existing metadata shall load into the editor.
 
Changing PageType shall re-evaluate valid statuses, update visible fields, warn before discarding invalid metadata, and never silently destroy user metadata.
 
Example: changing Area to Resource may safely offer to convert ParentArea to RelatedAreas. Changing Resource to Area with multiple RelatedAreas shall require the user to choose zero or one ParentArea.
 
---
 
# 22. Page Rename / Move Behavior
 
Because Page-valued metadata references page titles, page moves must preserve referential integrity.
 
The extension shall test MediaWiki/Cargo behavior for page moves. If Cargo does not automatically update references reliably, custom extension logic shall update ParentArea, RelatedAreas, RelatedProjects, and RelatedTopics as appropriate.
 
Topic page moves shall similarly update RelatedTopics references.
 
A maintenance script shall detect dangling references.
 
---
 
# 23. Page Delete Behavior
 
Deleting a referenced Area, Project, or Topic requires explicit handling.
 
Preferred behavior:
 
1. Display dependency count before deletion.
2. Provide links to referencing pages.
3. Do not silently remove relationship values.
4. Allow administrative forced deletion if MediaWiki permissions permit.
5. After deletion, Wiki Health shall identify dangling references until repaired.
 
Future enhancement: reassignment during deletion.
 
---
 
# 24. Permissions and Privacy
 
PARA classification is independent of access control.
 
Do not use PageStatus, PageType, Area, Project, or Topic as security boundaries.
 
All extension-generated lists and Cargo queries must respect MediaWiki read permissions and must not leak page titles or metadata for pages the viewer cannot access.
 
This applies to Area pages, Project pages, Topic pages, dashboards, autocomplete, selectors, API endpoints, counts, and search results.
 
---
 
# 25. API Requirements
 
The extension should expose structured operations through MediaWiki's API or a clearly defined REST interface.
 
Minimum operations:
 
```text
Get page classification metadata
Set page classification metadata
List valid PageTypes
List valid statuses for a PageType
Search/select Areas
Search/select Projects
Search/select Topics
Create Topic
Get Wiki Health counts
List Unclassified pages
```
 
API validation rules shall match UI validation rules.
 
Example payload:
 
```json
{
  "pageType": "study",
  "pageStatus": "active",
  "relatedAreas": ["Learning", "Career"],
  "relatedProjects": ["Complete course on Python"],
  "relatedTopics": ["Topic:Programming", "Topic:Python"]
}
```
 
---
 
# 26. Extension Architecture
 
Recommended implementation: one custom MediaWiki extension responsible for structured PKM behavior.
 
Working placeholder name: `WikiFarmPKM`.
 
Responsibilities:
 
- Wiki Mode configuration
- metadata validation
- metadata UI integration
- PageType/PageStatus rules
- Area hierarchy logic
- Project default-Area behavior
- Topic namespace behavior
- Cargo integration
- Wiki Health dashboard
- API endpoints
- maintenance scripts
- onboarding support hooks
- page move/delete consistency logic
 
Avoid scattering core business rules across templates, JavaScript snippets, and wiki pages. Templates may render data, but the extension should be the validation source of truth.
 
---
 
# 27. Configuration
 
Recommended wiki-level configuration:
 
```php
$wgWikiFarmMode = 'para';
```
 
or an equivalent per-wiki application configuration.
 
Recommended configurable constants:
 
```text
AllowedPageTypes
AllowedStatuses
StatusesByPageType
DefaultPageStatus
TopicNamespaceId
RecommendMaxAreas
RecommendMaxTopics
EnableProjectAreaDefaults
EnableWikiHealth
```
 
Do not hard-code numeric namespace IDs without a configuration constant.
 
---
 
# 28. Namespace Recommendation
 
Use a dedicated namespace:
 
```text
Topic:
```
 
Do not place Topic hub pages in the main namespace.
 
Topic namespace pages should remain normal MediaWiki pages where practical so they retain revisions, watchability, linking, discussion, search, and history.
 
---
 
# 29. Query Examples
 
Conceptual Cargo queries:
 
```text
RelatedAreas HOLDS 'Photography'
```
 
```text
PageType='Project'
AND PageStatus='Active'
AND RelatedAreas HOLDS 'Family'
```
 
```text
RelatedTopics HOLDS 'Topic:Python'
```
 
Unclassified conceptually means PageType is not Area and RelatedAreas, RelatedProjects, and RelatedTopics are all empty.
 
Implementation shall use exact Cargo syntax appropriate to the installed Cargo version.
 
---
 
# 30. Performance Requirements
 
Design for at least:
 
```text
100,000 normal pages
10,000 Topics
10,000 Areas/Projects combined
```
 
without schema redesign.
 
Selectors/autocomplete must not load all matching objects into the browser. Use server-side search/autocomplete for large lists.
 
Wiki Health calculations should avoid expensive full scans on every page view. Acceptable approaches include cached counts, scheduled refresh, incremental updates on edit hooks, or indexed Cargo queries. The chosen approach shall be documented.
 
---
 
# 31. Accessibility and UX
 
All classification controls shall be keyboard accessible. Do not rely on color alone for status.
 
Multi-select fields should support typeahead search, keyboard selection, removal of values, and visible Area hierarchy where practical.
 
Warnings shall be clearly distinguishable from hard errors.
 
---
 
# 32. Logging and Auditability
 
Metadata changes should be visible in page revision history where practical.
 
At minimum, administrators should be able to determine who changed PageType, PageStatus, Area/Project/Topic relationships, and when.
 
Avoid storing critical classification changes only in mutable Cargo rows without corresponding revision/audit context.
 
---
 
# 33. Maintenance Scripts
 
Provide maintenance scripts for:
 
```text
Rebuild Cargo PKM tables
Validate all PARA metadata
Detect invalid status/type combinations
Detect dangling Area references
Detect dangling Project references
Detect dangling Topic references
Detect Area hierarchy cycles
Rebuild Wiki Health data
Repair/reconcile metadata after page moves
```
 
Scripts should support dry-run mode where corrective behavior is possible.
 
---
 
# 34. Migration and Backward Compatibility
 
Standard Wiki pages shall not be forced into PARA metadata rules.
 
If a wiki changes from Standard to PARA mode, provide a migration/onboarding process rather than immediately invalidating all existing pages.
 
A migration condition such as **Needs Classification** should be a workflow/report state rather than necessarily a new PageStatus.
 
If a PARA Wiki changes to Standard mode, preserve existing structured metadata unless an administrator explicitly removes it.
 
---
 
# 35. Explicit Non-Goals for Version 1
 
Unless separately approved, version 1 does not include:
 
```text
Custom user-defined PageTypes
Custom user-defined PageStatuses
ParentProject hierarchy
Automatic dynamic Area inheritance from Projects
AI-based automatic classification
Automatic Topic ontology generation
Security/ACL implementation based on PARA properties
Complex Topic-to-Topic ontology
Goal as a seventh PageType
Capture inbox implementation
Gamification beyond Wiki Health warnings/counts
```
 
The architecture should not unnecessarily prevent these future capabilities.
 
---
 
# 36. Acceptance Criteria
 
## Scenario A: Create top-level Area
 
Create Hobbies with PageType=Area, PageStatus=Active, ParentArea=NULL.
 
Expected: save succeeds, Hobbies appears in Area selectors, and Hobbies appears under Top-Level Areas.
 
## Scenario B: Create child Area
 
Create Photography with PageType=Area, PageStatus=Active, ParentArea=Hobbies.
 
Expected: save succeeds; hierarchy shows Hobbies -> Photography; Photography appears in RelatedAreas selectors; Photography has no RelatedAreas value.
 
## Scenario C: Prevent invalid Area metadata
 
Attempt to save Photography as Area with RelatedAreas=Hobbies.
 
Expected: save rejected and user instructed to use ParentArea.
 
## Scenario D: Study with multiple relationships
 
Create Intro to Python as Study/Active with Areas Learning and Career, Project Complete course on Python, and Topics Programming and Python.
 
Expected: all relationships persist and query correctly.
 
## Scenario E: Project Area defaulting
 
Plan Italy vacation has Areas Travel & Vacations and Family. Assign it to Hotels in Rome.
 
Expected: both Areas are initially added. User may remove Family before saving. Later changes to Project Areas do not modify Hotels in Rome automatically.
 
## Scenario F: Archive Area
 
Archive Photography.
 
Expected: existing references remain; it disappears from default picker; Include archived Areas reveals it; direct access still works.
 
## Scenario G: Unclassified page
 
Create Resource with no Area, Project, or Topic.
 
Expected: save succeeds; warning appears; Wiki Health count increases; page appears in Unclassified list.
 
## Scenario H: Invalid status
 
Attempt Resource + Inception.
 
Expected: save rejected.
 
## Scenario I: Area cycle
 
Attempt Hobbies.ParentArea=Photography while Photography.ParentArea=Hobbies.
 
Expected: save rejected with clear cycle error.
 
## Scenario J: Topic behavior
 
Create Topic:Python, assign it to several pages, then archive it.
 
Expected: Topic hub lists associated pages; active selector includes it before archive; default selector excludes it after archive; existing references remain intact.
 
---
 
# 37. Open Design Questions
 
The developer/coding AI shall not invent final behavior for these items without product approval:
 
1. Exact type-specific metadata fields for each PageType.
2. Exact topic-specific metadata definition format.
3. Whether Topic pages may themselves be assigned RelatedTopics.
4. Whether Area pages may have Topics and/or RelatedProjects. Current recommendation: yes.
5. Whether Project pages may have RelatedTopics. Current recommendation: yes.
6. Exact VisualEditor integration approach.
7. Whether classification metadata is stored in wikitext templates, a revision-backed slot/content model, or another revision-backed mechanism in addition to Cargo.
8. Whether Wiki Mode is fixed at creation or can later be changed by an administrator.
9. Whether a separate EntityType/schema-classification mechanism should eventually exist alongside Topics.
10. Whether starter content is installed by extension code, Page Exchange packages, XML import, or another mechanism.
 
---
 
# 38. Recommended Implementation Order
 
Phase 1: Wiki Mode, PageType, PageStatus, Cargo table, basic metadata UI, validation.
 
Phase 2: Areas, ParentArea, RelatedAreas, hierarchy.
 
Phase 3: Projects, RelatedProjects, Project-to-Area default copying.
 
Phase 4: Topic namespace, Topic table, RelatedTopics, Topic hub pages.
 
Phase 5: Wiki Health dashboard, unclassified warnings, archive filtering.
 
Phase 6: starter-page onboarding, type-specific metadata framework, topic-specific metadata framework, API, and maintenance tools.
 
Each phase should include automated tests before proceeding.
 
---
 
# 39. Testing Requirements
 
Automated tests shall cover at least:
 
```text
PageType validation
PageStatus validation
status/type compatibility
ParentArea validation
Area cycle detection
Area selector filtering
Project selector filtering
Topic selector filtering
RelatedAreas list persistence
RelatedProjects list persistence
RelatedTopics list persistence
Project Area default copying
archived object behavior
unclassified detection
permissions-aware query output
page rename handling
page deletion/dangling-reference detection
API validation
```
 
Use MediaWiki-supported unit/integration test frameworks appropriate to the installed version.
 
---
 
# 40. Coding Standards
 
The implementation shall follow MediaWiki extension conventions, use namespaced PHP classes, avoid deprecated APIs, use dependency injection where supported, validate on the server, escape user output, respect CSRF protection, respect MediaWiki permissions, document configuration/schema, provide upgrade logic for schema changes, and include automated tests for core business rules.
 
Avoid duplicating business rules independently in PHP and JavaScript where a server-side source of truth is practical.
 
---
 
# 41. Naming Standard
 
Canonical internal names:
 
```text
WikiMode
PageType
PageStatus
ParentArea
RelatedAreas
RelatedProjects
RelatedTopics
TopicName
TopicStatus
```
 
Recommended user-facing labels:
 
```text
Wiki Mode
Type
Status
Parent Area
Related Areas
Related Projects
Topics
```
 
Avoid underscores such as `Page_Type` unless required by a specific external convention. Avoid numbered relationship properties.
 
---
 
# 42. Summary of Core Business Rules
 
```text
Every PARA knowledge page:
    exactly one PageType
    exactly one valid PageStatus
 
If PageType = Area:
    zero or one ParentArea
    no RelatedAreas
 
If PageType != Area:
    no ParentArea
    zero or more RelatedAreas
 
Any normal page:
    zero or more RelatedProjects
    zero or more RelatedTopics
 
Topics:
    first-class classification objects
    not PageTypes
    recommended dedicated namespace
 
Archived:
    lifecycle state
    not security state
 
Project Area behavior:
    defaults copied at assignment time
    not permanently inherited
 
Unclassified:
    warning/report condition
    not a save-blocking error
```
 
This model shall be treated as the implementation source of truth unless superseded by a later approved specification.
Retrieved from "https://wiki.goalstriving.org/Requirements_and_Specifications"