Knowledge Commons

Requirements and Specifications: Difference between revisions

← Older edit
VisualWikitext
No edit summary
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
# Wiki Farm PARA Mode
== Wiki Farm PARA Mode ==
## Functional Requirements and Technical Specification
=== 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.
'''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   
'''Status:''' Draft implementation specification   
**Version:** 1.0   
'''Version:''' 1.0   
**Target platform:** MediaWiki with Cargo and custom extension code   
'''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.
'''Primary design principle:''' Preserve normal MediaWiki behavior wherever practical, while adding an optional structured PKM mode.


---
---


# 1. Product Scope
== 1. Product Scope ==


## 1.1 Wiki Modes
=== 1.1 Wiki Modes ===


When a user creates a new wiki, the system shall support a configurable **Wiki Mode**.
When a user creates a new wiki, the system shall support a configurable '''Wiki Mode'''.


Initial supported modes:
Initial supported modes:


| Mode | Description |
{| class="wikitable"
|---|---|
! 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. |
| `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 architecture shall allow additional modes to be introduced later without redesigning the page metadata model.
Line 28: Line 31:
The selected Wiki Mode shall be stored at the wiki level, not page level.
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.
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
== 2. Core Concepts ==


Every normal content page in PARA Wiki mode shall have:
Every normal content page in PARA Wiki mode shall have:


- exactly one `PageType`
* exactly one <code>PageType</code>
- exactly one `PageStatus`
* exactly one <code>PageStatus</code>


A page may also have:
A page may also have:


- zero or one `ParentArea` when `PageType=Area`
* zero or one <code>ParentArea</code> when <code>PageType=Area</code>
- zero or more `RelatedAreas` when `PageType!=Area`
* zero or more <code>RelatedAreas</code> when <code>PageType!=Area</code>
- zero or more `RelatedProjects`
* zero or more <code>RelatedProjects</code>
- zero or more `RelatedTopics`
* zero or more <code>RelatedTopics</code>
- zero or more type-specific metadata fields
* zero or more type-specific metadata fields
- zero or more topic-specific metadata fields
* zero or more topic-specific metadata fields


Conceptual definitions:
Conceptual definitions:


| Dimension | User-facing question | Meaning |
{| class="wikitable"
|---|---|---|
! 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. |
| Type || How will I use this page? || The functional role 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. |
| Status || Is it currently relevant/active? || The lifecycle state of the page.
| Topic | What is it about? | A subject used to connect related pages. |
|-
| 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
== 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.
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 |
{| class="wikitable"
|---|---|---|
! 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. |
| `Study` || Notes derived from a source or structured learning. || Knowledge being acquired from a particular source, class, book, course, lecture, etc.
| `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. |
| `Journal` || Chronological experience or reflection. || What happened or what the user experienced.
| `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. |
| `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:
Recommended stable internal identifiers:


```text
<pre>
study
study
journal
journal
Line 82: Line 98:
area
area
resource
resource
```
</pre>


---
---


# 4. Page Statuses
== 4. Page Statuses ==


The application shall initially support three Page Status values:
The application shall initially support three Page Status values:


```text
<pre>
inception
inception
active
active
archived
archived
```
</pre>


Users shall not be able to create custom statuses in version 1.
Users shall not be able to create custom statuses in version 1.


| PageType | Inception | Active | Archived |
{| class="wikitable"
|---|---:|---:|---:|
! PageType !! Inception !! Active !! Archived
| Study | No | Yes | Yes |
|-
| Journal | No | Yes | Yes |
| Study || No || Yes || Yes
| Idea | No | Yes | Yes |
|-
| Project | Yes | Yes | Yes |
| Journal || No || Yes || Yes
| Area | Yes | Yes | Yes |
|-
| Resource | No | Yes | Yes |
| Idea || No || Yes || Yes
|-
| Project || Yes || Yes || Yes
|-
| Area || Yes || Yes || Yes
|-
| Resource || No || Yes || Yes
|}


Definitions:
Definitions:


| Status | Meaning |
{| class="wikitable"
|---|---|
! Status !! Meaning
| `Inception` | Being considered or developed but not yet committed. |
|-
| `Active` | Currently relevant, maintained, pursued, or available for normal use. |
| `Inception` || Being considered or developed but not yet committed.
| `Archived` | Retained but no longer active. |
|-
| `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 affect default inclusion in views, selectors, reports, workflows, and search filters.


Status shall **not** determine authorization, sharing, privacy, or security permissions.
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.
Archived pages shall remain directly accessible to users who otherwise have permission to view them.
Line 123: Line 150:
---
---


# 5. Area Model
== 5. Area Model ==


## 5.1 Area Definition
=== 5.1 Area Definition ===


An Area is an ongoing responsibility, activity, or something the user intentionally maintains or develops over time.
An Area is an ongoing responsibility, activity, or something the user intentionally maintains or develops over time.
Line 131: Line 158:
Examples include Personal, Family, Household, Learning, Career, Travel & Vacations, Hobbies, Photography, Cooking, and Fitness & Nutrition.
Examples include Personal, Family, Household, Learning, Career, Travel & Vacations, Hobbies, Photography, Cooking, and Fitness & Nutrition.


## 5.2 Parent Area
=== 5.2 Parent Area ===


An Area page may have zero or one `ParentArea`.
An Area page may have zero or one <code>ParentArea</code>.


A page whose `PageType=Area` shall not use `RelatedAreas`.
A page whose <code>PageType=Area</code> shall not use <code>RelatedAreas</code>.


Examples:
Examples:


```text
<pre>
Hobbies
Hobbies
   ParentArea = NULL
   ParentArea = NULL
Line 154: Line 181:
Skills development
Skills development
   ParentArea = Career
   ParentArea = Career
```
</pre>


A top-level Area is defined as:
A top-level Area is defined as:


```text
<pre>
PageType = Area
PageType = Area
ParentArea = NULL
ParentArea = NULL
```
</pre>


The system shall prevent an Area from being its own parent and shall prevent circular Area relationships.
The system shall prevent an Area from being its own parent and shall prevent circular Area relationships.
Line 167: Line 194:
The Area hierarchy shall support an arbitrary practical depth unless implementation limitations require a documented maximum.
The Area hierarchy shall support an arbitrary practical depth unless implementation limitations require a documented maximum.


## 5.3 Related Areas
=== 5.3 Related Areas ===


A non-Area page may have zero or more `RelatedAreas`.
A non-Area page may have zero or more <code>RelatedAreas</code>.


Each value shall reference an existing page whose `PageType=Area`.
Each value shall reference an existing page whose <code>PageType=Area</code>.


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**.
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 Area picker should display hierarchy where practical.
Line 181: Line 208:
---
---


# 6. Project Model
== 6. Project Model ==


A Project is a page whose `PageType=Project`.
A Project is a page whose <code>PageType=Project</code>.


A Project shall normally have at least one `RelatedArea`, although this shall be a quality warning rather than a hard validation rule.
A Project shall normally have at least one <code>RelatedArea</code>, although this shall be a quality warning rather than a hard validation rule.


A page may have zero or more `RelatedProjects`.
A page may have zero or more <code>RelatedProjects</code>.


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.
Each Related Project shall reference an existing page whose <code>PageType=Project</code> 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.
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.
Project hierarchy / <code>ParentProject</code> is explicitly out of scope for version 1, but the schema shall not preclude adding it later.


---
---


# 7. Project-to-Area Defaulting
== 7. Project-to-Area Defaulting ==


When a Project is assigned to a page:
When a Project is assigned to a page:


1. Read the selected Project's `RelatedAreas`.
# Read the selected Project's <code>RelatedAreas</code>.
2. Add any missing Project Areas to the edited page's `RelatedAreas`.
# Add any missing Project Areas to the edited page's <code>RelatedAreas</code>.
3. Do not remove any existing Areas.
# Do not remove any existing Areas.
4. Allow the user to remove any newly added Areas before saving.
# Allow the user to remove any newly added Areas before saving.
5. Once the page is saved, the values are independent.
# Once the page is saved, the values are independent.


This behavior is **default copying**, not dynamic inheritance.
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.
If the Project's Areas change later, existing pages assigned to that Project shall not automatically change.
Line 213: Line 240:
---
---


# 8. Topic Model
== 8. Topic Model ==


## 8.1 Topic Is Not a Page Type
=== 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?**
<code>Topic</code> 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
=== 8.2 Topics as First-Class Classification Objects ===


Topics shall be first-class application objects.
Topics shall be first-class application objects.
Line 225: Line 252:
Recommended implementation:
Recommended implementation:


```text
<pre>
Topic:<TopicName>
Topic:<TopicName>
```
</pre>


using a dedicated MediaWiki namespace.
using a dedicated MediaWiki namespace.
Line 233: Line 260:
Examples:
Examples:


```text
<pre>
Topic:Python
Topic:Python
Topic:Programming
Topic:Programming
Topic:Freshman Courses
Topic:Freshman Courses
Topic:Rome
Topic:Rome
```
</pre>


Topic namespace pages are classification/hub objects and are not ordinary PARA knowledge pages. Topic pages shall not require a PageType.
Topic namespace pages are classification/hub objects and are not ordinary PARA knowledge pages. Topic pages shall not require a PageType.
Line 244: Line 271:
A Topic should support at least:
A Topic should support at least:


| Field | Requirement |
{| class="wikitable"
|---|---|
! Field !! Requirement
| TopicName | Required, unique within the wiki |
|-
| TopicStatus | Active or Archived |
| TopicName || Required, unique within the wiki
| Description | Optional |
|-
| RelatedTopics | Optional/future-safe |
| TopicStatus || Active or Archived
| MetadataDefinition | Optional structured definition of topic-specific fields |
|-
| CreatedAt | System managed |
| Description || Optional
| UpdatedAt | System managed |
|-
| 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.
Version 1 may omit RelatedTopics and MetadataDefinition UI if necessary, but the data model should allow future implementation.


## 8.3 Related Topics
=== 8.3 Related Topics ===


Normal content pages may have zero or more `RelatedTopics`.
Normal content pages may have zero or more <code>RelatedTopics</code>.


Each Related Topic shall reference an existing Topic object. Default picker behavior shall show active Topics, with an option to include archived Topics.
Each Related Topic shall reference an existing Topic object. Default picker behavior shall show active Topics, with an option to include archived Topics.
Line 264: Line 299:
The system should recommend no more than three Topics per page for simplicity but shall not enforce a hard maximum.
The system should recommend no more than three Topics per page for simplicity but shall not enforce a hard maximum.


## 8.4 Topic Creation
=== 8.4 Topic Creation ===


The RelatedTopics control should allow selecting an existing Topic and optionally creating a new Topic inline, subject to permissions.
The RelatedTopics control should allow selecting an existing Topic and optionally creating a new Topic inline, subject to permissions.
Line 272: Line 307:
---
---


# 9. Topic-Specific Metadata
== 9. Topic-Specific Metadata ==


The architecture shall support 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.
For example, <code>Topic:Book</code> could define Author, ISBN, Publisher, and PublicationDate. <code>Topic:Vehicle</code> 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.
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.
Line 282: Line 317:
Recommended abstraction:
Recommended abstraction:


```text
<pre>
MetadataDefinition
MetadataDefinition
MetadataField
MetadataField
MetadataAssignment
MetadataAssignment
MetadataValue
MetadataValue
```
</pre>


---
---


# 10. Type-Specific Metadata
== 10. Type-Specific Metadata ==


Each Page Type may expose additional metadata. The following fields are illustrative rather than mandatory for version 1.
Each Page Type may expose additional metadata. The following fields are illustrative rather than mandatory for version 1.


| PageType | Possible metadata |
{| class="wikitable"
|---|---|
! PageType !! Possible metadata
| Study | SourceType, SourceTitle, Author, Instructor, Institution, StartDate, EndDate, Progress, URL, ISBN |
|-
| Journal | JournalDate, StartDate, EndDate, Location |
| Study || SourceType, SourceTitle, Author, Instructor, Institution, StartDate, EndDate, Progress, URL, ISBN
| Idea | IdeaDate, Confidence, SourcePages |
|-
| Project | StartDate, TargetDate, CompletionDate, Outcome, Progress |
| Journal || JournalDate, StartDate, EndDate, Location
| Area | ReviewFrequency, LastReviewed |
|-
| Resource | SourceURL, SourceDate, Author |
| 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.
Potential future Project Outcome values include <code>completed</code>, <code>abandoned</code>, and <code>cancelled</code>. Outcome shall remain separate from PageStatus.


The type-specific metadata subsystem shall be extensible without schema redesign.
The type-specific metadata subsystem shall be extensible without schema redesign.
Line 310: Line 352:
---
---


# 11. Unclassified Page Rule
== 11. Unclassified Page Rule ==


Every non-Area page should normally have at least one of `RelatedAreas`, `RelatedProjects`, or `RelatedTopics`.
Every non-Area page should normally have at least one of <code>RelatedAreas</code>, <code>RelatedProjects</code>, or <code>RelatedTopics</code>.


This shall not be a hard save-time validation rule.
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.
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:
The page shall display a non-blocking notification such as:


```text
<pre>
This page is not currently associated with an Area, Project, or Topic.
This page is not currently associated with an Area, Project, or Topic.
```
</pre>


The user's Status / Wiki Health page shall include an Unclassified Pages section and count.
The user's Status / Wiki Health page shall include an Unclassified Pages section and count.
Line 330: Line 372:
---
---


# 12. Wiki Health / Status Page
== 12. Wiki Health / Status Page ==


PARA Wiki mode shall include a system-generated or extension-generated **Status** or **Wiki Health** page.
PARA Wiki mode shall include a system-generated or extension-generated '''Status''' or '''Wiki Health''' page.


Minimum metrics:
Minimum metrics:


| Metric | Definition |
{| class="wikitable"
|---|---|
! Metric !! Definition
| Unclassified Pages | Non-Area pages with no Area, Project, or Topic |
|-
| Active Projects Without Areas | Project pages with no RelatedAreas |
| Unclassified Pages || Non-Area pages with no Area, Project, or Topic
| Top-Level Areas | Active Area pages with ParentArea=NULL |
|-
| Sub-Areas | Active Area pages with ParentArea set |
| Active Projects Without Areas || Project pages with no RelatedAreas
| Archived Pages | Count grouped by PageType |
|-
| Areas With No Associated Content | Areas with no child Areas and no related pages |
| Top-Level Areas || Active Area pages with ParentArea=NULL
| Active Projects With No Recent Activity | Optional if reliable activity logic is available |
|-
| 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.
All metrics should link to filtered page lists.
Line 350: Line 400:
---
---


# 13. Page Metadata UI
== 13. Page Metadata UI ==


Recommended user-facing labels:
Recommended user-facing labels:


```text
<pre>
Type
Type
Status
Status
Line 361: Line 411:
Related Projects
Related Projects
Topics
Topics
```
</pre>


Recommended internal field names:
Recommended internal field names:


```text
<pre>
PageType
PageType
PageStatus
PageStatus
Line 372: Line 422:
RelatedProjects
RelatedProjects
RelatedTopics
RelatedTopics
```
</pre>


Do not use numbered fields such as `Area1`, `Area2`, `Area3`, `Project1`, etc.
Do not use numbered fields such as <code>Area1</code>, <code>Area2</code>, <code>Area3</code>, <code>Project1</code>, etc.


For an Area page, show Type, Status, Parent Area, Related Projects if applicable, and Topics. Hide/disable Related Areas.
For an Area page, show Type, Status, Parent Area, Related Projects if applicable, and Topics. Hide/disable Related Areas.
Line 384: Line 434:
---
---


# 14. Cargo Storage Model
== 14. Cargo Storage Model ==


Cargo shall be used for structured querying unless implementation testing identifies a technical blocker.
Cargo shall be used for structured querying unless implementation testing identifies a technical blocker.


Recommended main table: `WikiPages`.
Recommended main table: <code>WikiPages</code>.


Illustrative schema:
Illustrative schema:


```wikitext
<pre>
{{#cargo_declare:
{{#cargo_declare:
_table=WikiPages
_table=WikiPages
Line 402: Line 452:
|RelatedTopics=List (,) of Page
|RelatedTopics=List (,) of Page
}}
}}
```
</pre>


Requirements:
Requirements:


- Store page names as Cargo `Page` values rather than integer IDs unless testing identifies a strong reason otherwise.
* Store page names as Cargo <code>Page</code> values rather than integer IDs unless testing identifies a strong reason otherwise.
- Use Cargo List fields for RelatedAreas, RelatedProjects, and RelatedTopics.
* Use Cargo List fields for RelatedAreas, RelatedProjects, and RelatedTopics.
- Use Cargo-supported list querying such as `HOLDS` rather than manually parsing comma-separated strings.
* Use Cargo-supported list querying such as <code>HOLDS</code> rather than manually parsing comma-separated strings.
- Topic references using a dedicated namespace may be stored as full titles such as `Topic:Python`.
* Topic references using a dedicated namespace may be stored as full titles such as <code>Topic:Python</code>.
- Topic data should use a separate Cargo table such as `Topics`.
* Topic data should use a separate Cargo table such as <code>Topics</code>.
- Type-specific metadata may use separate Cargo tables rather than making the main table excessively wide.
* Type-specific metadata may use separate Cargo tables rather than making the main table excessively wide.


---
---


# 15. Data Integrity Rules
== 15. Data Integrity Rules ==


| Rule | Enforcement |
{| class="wikitable"
|---|---|
! Rule !! Enforcement
| PageType required | Hard |
|-
| PageStatus required | Hard |
| PageType required || Hard
| PageStatus valid for PageType | Hard |
|-
| Area has at most one ParentArea | Hard |
| PageStatus required || Hard
| Area cannot use RelatedAreas | Hard |
|-
| Non-Area cannot use ParentArea | Hard |
| PageStatus valid for PageType || Hard
| ParentArea references Area page | Hard |
|-
| RelatedAreas reference Area pages | Hard |
| Area has at most one ParentArea || Hard
| RelatedProjects reference Project pages | Hard |
|-
| RelatedTopics reference Topic objects | Hard |
| Area cannot use RelatedAreas || Hard
| Area cannot parent itself | Hard |
|-
| Area hierarchy cannot contain cycles | Hard |
| Non-Area cannot use ParentArea || Hard
| Project cannot relate to itself | Hard |
|-
| Non-Area should have Area, Project, or Topic | Warning |
| ParentArea references Area page || Hard
| Project should have at least one Area | Warning |
|-
| More than three Areas or Topics | Advisory only |
| 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.
Invalid metadata submitted through APIs or non-UI mechanisms shall be rejected consistently with UI validation.
Line 440: Line 507:
---
---


# 16. Archived Object Behavior
== 16. Archived Object Behavior ==


Archived pages remain accessible.
Archived pages remain accessible.
Line 446: Line 513:
Default behavior:
Default behavior:


- exclude archived Areas from Area pickers
* exclude archived Areas from Area pickers
- exclude archived Projects from Project pickers
* exclude archived Projects from Project pickers
- exclude archived Topics from Topic pickers
* exclude archived Topics from Topic pickers
- optionally exclude archived pages from default dashboards and views
* optionally exclude archived pages from default dashboards and views
- allow users to explicitly include archived content
* allow users to explicitly include archived content
- direct links to archived pages continue to work
* direct links to archived pages continue to work


Archived shall not mean deleted and shall not modify sharing/privacy permissions.
Archived shall not mean deleted and shall not modify sharing/privacy permissions.
Line 457: Line 524:
---
---


# 17. Search and Browse Behavior
== 17. Search and Browse Behavior ==


PARA Wiki shall support filtering/browsing by PageType, PageStatus, Area, Project, and Topic.
PARA Wiki shall support filtering/browsing by PageType, PageStatus, Area, Project, and Topic.
Line 463: Line 530:
Examples:
Examples:


```text
<pre>
Active Study pages in Learning
Active Study pages in Learning
Resources related to Plan Italy vacation
Resources related to Plan Italy vacation
Line 469: Line 536:
Archived pages in Photography
Archived pages in Photography
Unclassified pages
Unclassified pages
```
</pre>


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.
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.
Line 479: Line 546:
---
---


# 18. Onboarding
== 18. Onboarding ==


When creating a PARA Wiki, onboarding should explain:
When creating a PARA Wiki, onboarding should explain:


```text
<pre>
Type: How will I use this page?
Type: How will I use this page?
Status: Is it currently relevant/active?
Status: Is it currently relevant/active?
Line 489: Line 556:
Project: What outcome does it support?
Project: What outcome does it support?
Topic: What is it about?
Topic: What is it about?
```
</pre>


The user may optionally import starter pages. Starter pages shall be selectable; users should not be forced to import the entire sample set.
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.
All imported starter pages should default to <code>PageStatus=Active</code> unless explicitly defined otherwise.


---
---


# 19. Starter Page Dataset
== 19. Starter Page Dataset ==


| PageName | PageType | ParentArea | RelatedAreas | RelatedProjects | RelatedTopics |
{| class="wikitable"
|---|---|---|---|---|---|
! PageName !! PageType !! ParentArea !! RelatedAreas !! RelatedProjects !! RelatedTopics
| Personal | Area | | | | |
|-
| Long-term goals | Resource | | Personal | | |
| Personal || Area || || || ||  
| Weekly tasks | Resource | | Personal | | |
|-
| Gift ideas | Resource | | Personal | | |
| Long-term goals || Resource ||  || Personal || ||
| Daily Journal | Journal | | Personal | | |
|-
| Fitness & Nutrition | Area | | | | |
| Weekly tasks || Resource ||  || Personal ||  ||  
| Tips for healthy eating | Resource | | Fitness & Nutrition | | |
|-
| Yoga | Area | Fitness & Nutrition | | | |
| Gift ideas || Resource ||  || Personal ||  ||  
| Why yoga helps me | Idea | | Fitness & Nutrition | | |
|-
| Household | Area | | | | |
| Daily Journal || Journal ||  || Personal ||  ||  
| Products | Resource | | Household | | |
|-
| Household Technology | Resource | | Household | | |
| Fitness & Nutrition || Area || ||  ||  ||  
| Subscriptions | Resource | | Household | | |
|-
| Family | Area | | | | |
| Tips for healthy eating || Resource ||  || Fitness & Nutrition ||  ||  
| Family traditions | Resource | | Family | | |
|-
| Family tree | Resource | | Family | | |
| Yoga || Area || Fitness & Nutrition || || ||
| Friends & Social Activities | Area | | | | |
|-
| Poker night planning | Resource | | Friends & Social Activities | | |
| Why yoga helps me || Idea ||  || Fitness & Nutrition || ||
| Why Small Gatherings Are More Enjoyable | Idea | | Friends & Social Activities | | |
|-
| Volunteering | Area | | | | |
| Household || Area || || ||  ||
| Past volunteering | Resource | | Volunteering | | |
|-
| Volunteering opportunities | Resource | | Volunteering | | |
| Products || Resource ||  || Household ||  ||  
| Vehicles | Area | | | | |
|-
| Honda Accord 2025 | Resource | | Vehicles | | |
| Household Technology || Resource ||  || Household ||  ||  
| Vehicles being considered for purchase | Resource | | Vehicles | | |
|-
| Learning | Area | | | | |
| Subscriptions || Resource ||  || Household || ||
| List of schools & courses attended | Resource | | Learning | | |
|-
| List of books I have read | Resource | | Learning | | |
| Family || Area ||  || ||  ||  
| Intro to Python | Study | | Learning, Career | Complete course on Python | Programming, Python |
|-
| Psychology 103 | Study | | Learning | University Degree | Freshman Courses |
| Family traditions || Resource ||  || Family ||  ||  
| Music Theory 202 | Study | | Learning | University Degree | Freshman Courses |
|-
| Travel & Vacations | Area | | | | |
| Family tree || Resource ||  || Family ||  ||  
| Bucket list | Resource | | Travel & Vacations | | |
|-
| Past vacations | Resource | | Travel & Vacations | | |
| Friends & Social Activities || Area ||  || ||  ||  
| Spain Vacation Journal | Journal | | Travel & Vacations | | |
|-
| Travel loyalty programs | Resource | | Travel & Vacations | | |
| Poker night planning || Resource ||  || Friends & Social Activities || ||
| Entertainment | Area | | | | |
|-
| Concerts I might want to see | Resource | | Entertainment | | |
| Why Small Gatherings Are More Enjoyable || Idea ||  || Friends & Social Activities ||  ||  
| Concert Journal | Journal | | Entertainment | | |
|-
| Movies to rewatch | Resource | | Entertainment | | |
| Volunteering || Area || || ||  ||
| Hobbies | Area | | | | |
|-
| Photography | Area | Hobbies | | | |
| Past volunteering || Resource ||  || Volunteering ||  ||  
| Canon EOS R10 | Resource | | Photography | | |
|-
| Understanding Exposure by Bryan Peterson | Study | | Photography | | |
| Volunteering opportunities || Resource ||  || Volunteering ||  ||  
| Tips for Low Light Photography | Resource | | Photography | | |
|-
| Cooking | Area | Hobbies | | | |
| Vehicles || Area || ||  ||  ||  
| Career | Area | | | | |
|-
| Skills development | Area | Career | | | |
| Honda Accord 2025 || Resource ||  || Vehicles ||  ||  
| Potential employers | Resource | | Career | | |
|-
| Create family vacation photo book | Project | | Family, Photography | | |
| Vehicles being considered for purchase || Resource ||  || Vehicles || ||
| Replace kitchen floor | Project | | Household | | |
|-
| Plan Italy vacation | Project | | Travel & Vacations, Family | | |
| Learning || Area || ||  ||  ||  
| Hotels in Rome | Resource | | Travel & Vacations, Family | Plan Italy vacation | |
|-
| Complete course on Python | Project | | Career, Learning | | |
| List of schools & courses attended || Resource ||  || Learning ||  ||  
| University Degree | Project | | 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:
Required starter Topics if the corresponding starter pages are imported:


```text
<pre>
Programming
Programming
Python
Python
Freshman Courses
Freshman Courses
```
</pre>


Starter Project and Topic dependencies shall be handled automatically. No imported starter page may contain a dangling reference.
Starter Project and Topic dependencies shall be handled automatically. No imported starter page may contain a dangling reference.
Line 569: Line 692:
---
---


# 20. Page Creation Workflow
== 20. Page Creation Workflow ==


1. User enters page title.
# User enters page title.
2. User selects PageType.
# User selects PageType.
3. System presents valid PageStatus values.
# System presents valid PageStatus values.
4. Default status should normally be Active.
# Default status should normally be Active.
5. If PageType=Area, show ParentArea and hide RelatedAreas.
# If PageType=Area, show ParentArea and hide RelatedAreas.
6. Otherwise show RelatedAreas and hide ParentArea.
# Otherwise show RelatedAreas and hide ParentArea.
7. Show RelatedProjects.
# Show RelatedProjects.
8. Show RelatedTopics.
# Show RelatedTopics.
9. Load type-specific metadata fields.
# Load type-specific metadata fields.
10. Load topic-specific metadata fields as Topics are selected.
# Load topic-specific metadata fields as Topics are selected.
11. Validate hard rules.
# Validate hard rules.
12. Display advisory warnings separately.
# Display advisory warnings separately.
13. Save page and structured metadata atomically where practical.
# Save page and structured metadata atomically where practical.


The system should minimize clicks and avoid repeated confirmation screens.
The system should minimize clicks and avoid repeated confirmation screens.
Line 589: Line 712:
---
---


# 21. Editing Workflow
== 21. Editing Workflow ==


Existing metadata shall load into the editor.
Existing metadata shall load into the editor.
Line 599: Line 722:
---
---


# 22. Page Rename / Move Behavior
== 22. Page Rename / Move Behavior ==


Because Page-valued metadata references page titles, page moves must preserve referential integrity.
Because Page-valued metadata references page titles, page moves must preserve referential integrity.
Line 611: Line 734:
---
---


# 23. Page Delete Behavior
== 23. Page Delete Behavior ==


Deleting a referenced Area, Project, or Topic requires explicit handling.
Deleting a referenced Area, Project, or Topic requires explicit handling.
Line 617: Line 740:
Preferred behavior:
Preferred behavior:


1. Display dependency count before deletion.
# Display dependency count before deletion.
2. Provide links to referencing pages.
# Provide links to referencing pages.
3. Do not silently remove relationship values.
# Do not silently remove relationship values.
4. Allow administrative forced deletion if MediaWiki permissions permit.
# Allow administrative forced deletion if MediaWiki permissions permit.
5. After deletion, Wiki Health shall identify dangling references until repaired.
# After deletion, Wiki Health shall identify dangling references until repaired.


Future enhancement: reassignment during deletion.
Future enhancement: reassignment during deletion.
Line 627: Line 750:
---
---


# 24. Permissions and Privacy
== 24. Permissions and Privacy ==


PARA classification is independent of access control.
PARA classification is independent of access control.
Line 639: Line 762:
---
---


# 25. API Requirements
== 25. API Requirements ==


The extension should expose structured operations through MediaWiki's API or a clearly defined REST interface.
The extension should expose structured operations through MediaWiki's API or a clearly defined REST interface.
Line 645: Line 768:
Minimum operations:
Minimum operations:


```text
<pre>
Get page classification metadata
Get page classification metadata
Set page classification metadata
Set page classification metadata
Line 656: Line 779:
Get Wiki Health counts
Get Wiki Health counts
List Unclassified pages
List Unclassified pages
```
</pre>


API validation rules shall match UI validation rules.
API validation rules shall match UI validation rules.
Line 662: Line 785:
Example payload:
Example payload:


```json
<pre>
{
{
   "pageType": "study",
   "pageType": "study",
Line 670: Line 793:
   "relatedTopics": ["Topic:Programming", "Topic:Python"]
   "relatedTopics": ["Topic:Programming", "Topic:Python"]
}
}
```
</pre>


---
---


# 26. Extension Architecture
== 26. Extension Architecture ==


Recommended implementation: one custom MediaWiki extension responsible for structured PKM behavior.
Recommended implementation: one custom MediaWiki extension responsible for structured PKM behavior.


Working placeholder name: `WikiFarmPKM`.
Working placeholder name: <code>WikiFarmPKM</code>.


Responsibilities:
Responsibilities:


- Wiki Mode configuration
* Wiki Mode configuration
- metadata validation
* metadata validation
- metadata UI integration
* metadata UI integration
- PageType/PageStatus rules
* PageType/PageStatus rules
- Area hierarchy logic
* Area hierarchy logic
- Project default-Area behavior
* Project default-Area behavior
- Topic namespace behavior
* Topic namespace behavior
- Cargo integration
* Cargo integration
- Wiki Health dashboard
* Wiki Health dashboard
- API endpoints
* API endpoints
- maintenance scripts
* maintenance scripts
- onboarding support hooks
* onboarding support hooks
- page move/delete consistency logic
* 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.
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.
Line 700: Line 823:
---
---


# 27. Configuration
== 27. Configuration ==


Recommended wiki-level configuration:
Recommended wiki-level configuration:


```php
<pre>
$wgWikiFarmMode = 'para';
$wgWikiFarmMode = 'para';
```
</pre>


or an equivalent per-wiki application configuration.
or an equivalent per-wiki application configuration.
Line 712: Line 835:
Recommended configurable constants:
Recommended configurable constants:


```text
<pre>
AllowedPageTypes
AllowedPageTypes
AllowedStatuses
AllowedStatuses
Line 722: Line 845:
EnableProjectAreaDefaults
EnableProjectAreaDefaults
EnableWikiHealth
EnableWikiHealth
```
</pre>


Do not hard-code numeric namespace IDs without a configuration constant.
Do not hard-code numeric namespace IDs without a configuration constant.
Line 728: Line 851:
---
---


# 28. Namespace Recommendation
== 28. Namespace Recommendation ==


Use a dedicated namespace:
Use a dedicated namespace:


```text
<pre>
Topic:
Topic:
```
</pre>


Do not place Topic hub pages in the main namespace.
Do not place Topic hub pages in the main namespace.
Line 742: Line 865:
---
---


# 29. Query Examples
== 29. Query Examples ==


Conceptual Cargo queries:
Conceptual Cargo queries:


```text
<pre>
RelatedAreas HOLDS 'Photography'
RelatedAreas HOLDS 'Photography'
```
</pre>


```text
<pre>
PageType='Project'
PageType='Project'
AND PageStatus='Active'
AND PageStatus='Active'
AND RelatedAreas HOLDS 'Family'
AND RelatedAreas HOLDS 'Family'
```
</pre>


```text
<pre>
RelatedTopics HOLDS 'Topic:Python'
RelatedTopics HOLDS 'Topic:Python'
```
</pre>


Unclassified conceptually means PageType is not Area and RelatedAreas, RelatedProjects, and RelatedTopics are all empty.
Unclassified conceptually means PageType is not Area and RelatedAreas, RelatedProjects, and RelatedTopics are all empty.
Line 766: Line 889:
---
---


# 30. Performance Requirements
== 30. Performance Requirements ==


Design for at least:
Design for at least:


```text
<pre>
100,000 normal pages
100,000 normal pages
10,000 Topics
10,000 Topics
10,000 Areas/Projects combined
10,000 Areas/Projects combined
```
</pre>


without schema redesign.
without schema redesign.
Line 784: Line 907:
---
---


# 31. Accessibility and UX
== 31. Accessibility and UX ==


All classification controls shall be keyboard accessible. Do not rely on color alone for status.
All classification controls shall be keyboard accessible. Do not rely on color alone for status.
Line 794: Line 917:
---
---


# 32. Logging and Auditability
== 32. Logging and Auditability ==


Metadata changes should be visible in page revision history where practical.
Metadata changes should be visible in page revision history where practical.
Line 804: Line 927:
---
---


# 33. Maintenance Scripts
== 33. Maintenance Scripts ==


Provide maintenance scripts for:
Provide maintenance scripts for:


```text
<pre>
Rebuild Cargo PKM tables
Rebuild Cargo PKM tables
Validate all PARA metadata
Validate all PARA metadata
Line 818: Line 941:
Rebuild Wiki Health data
Rebuild Wiki Health data
Repair/reconcile metadata after page moves
Repair/reconcile metadata after page moves
```
</pre>


Scripts should support dry-run mode where corrective behavior is possible.
Scripts should support dry-run mode where corrective behavior is possible.
Line 824: Line 947:
---
---


# 34. Migration and Backward Compatibility
== 34. Migration and Backward Compatibility ==


Standard Wiki pages shall not be forced into PARA metadata rules.
Standard Wiki pages shall not be forced into PARA metadata rules.
Line 830: Line 953:
If a wiki changes from Standard to PARA mode, provide a migration/onboarding process rather than immediately invalidating all existing pages.
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.
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.
If a PARA Wiki changes to Standard mode, preserve existing structured metadata unless an administrator explicitly removes it.
Line 836: Line 959:
---
---


# 35. Explicit Non-Goals for Version 1
== 35. Explicit Non-Goals for Version 1 ==


Unless separately approved, version 1 does not include:
Unless separately approved, version 1 does not include:


```text
<pre>
Custom user-defined PageTypes
Custom user-defined PageTypes
Custom user-defined PageStatuses
Custom user-defined PageStatuses
Line 852: Line 975:
Capture inbox implementation
Capture inbox implementation
Gamification beyond Wiki Health warnings/counts
Gamification beyond Wiki Health warnings/counts
```
</pre>


The architecture should not unnecessarily prevent these future capabilities.
The architecture should not unnecessarily prevent these future capabilities.
Line 858: Line 981:
---
---


# 36. Acceptance Criteria
== 36. Acceptance Criteria ==


## Scenario A: Create top-level Area
=== Scenario A: Create top-level Area ===


Create Hobbies with PageType=Area, PageStatus=Active, ParentArea=NULL.
Create Hobbies with PageType=Area, PageStatus=Active, ParentArea=NULL.
Line 866: Line 989:
Expected: save succeeds, Hobbies appears in Area selectors, and Hobbies appears under Top-Level Areas.
Expected: save succeeds, Hobbies appears in Area selectors, and Hobbies appears under Top-Level Areas.


## Scenario B: Create child Area
=== Scenario B: Create child Area ===


Create Photography with PageType=Area, PageStatus=Active, ParentArea=Hobbies.
Create Photography with PageType=Area, PageStatus=Active, ParentArea=Hobbies.
Line 872: Line 995:
Expected: save succeeds; hierarchy shows Hobbies -> Photography; Photography appears in RelatedAreas selectors; Photography has no RelatedAreas value.
Expected: save succeeds; hierarchy shows Hobbies -> Photography; Photography appears in RelatedAreas selectors; Photography has no RelatedAreas value.


## Scenario C: Prevent invalid Area metadata
=== Scenario C: Prevent invalid Area metadata ===


Attempt to save Photography as Area with RelatedAreas=Hobbies.
Attempt to save Photography as Area with RelatedAreas=Hobbies.
Line 878: Line 1,001:
Expected: save rejected and user instructed to use ParentArea.
Expected: save rejected and user instructed to use ParentArea.


## Scenario D: Study with multiple relationships
=== 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.
Create Intro to Python as Study/Active with Areas Learning and Career, Project Complete course on Python, and Topics Programming and Python.
Line 884: Line 1,007:
Expected: all relationships persist and query correctly.
Expected: all relationships persist and query correctly.


## Scenario E: Project Area defaulting
=== Scenario E: Project Area defaulting ===


Plan Italy vacation has Areas Travel & Vacations and Family. Assign it to Hotels in Rome.
Plan Italy vacation has Areas Travel & Vacations and Family. Assign it to Hotels in Rome.
Line 890: Line 1,013:
Expected: both Areas are initially added. User may remove Family before saving. Later changes to Project Areas do not modify Hotels in Rome automatically.
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
=== Scenario F: Archive Area ===


Archive Photography.
Archive Photography.
Line 896: Line 1,019:
Expected: existing references remain; it disappears from default picker; Include archived Areas reveals it; direct access still works.
Expected: existing references remain; it disappears from default picker; Include archived Areas reveals it; direct access still works.


## Scenario G: Unclassified page
=== Scenario G: Unclassified page ===


Create Resource with no Area, Project, or Topic.
Create Resource with no Area, Project, or Topic.
Line 902: Line 1,025:
Expected: save succeeds; warning appears; Wiki Health count increases; page appears in Unclassified list.
Expected: save succeeds; warning appears; Wiki Health count increases; page appears in Unclassified list.


## Scenario H: Invalid status
=== Scenario H: Invalid status ===


Attempt Resource + Inception.
Attempt Resource + Inception.
Line 908: Line 1,031:
Expected: save rejected.
Expected: save rejected.


## Scenario I: Area cycle
=== Scenario I: Area cycle ===


Attempt Hobbies.ParentArea=Photography while Photography.ParentArea=Hobbies.
Attempt Hobbies.ParentArea=Photography while Photography.ParentArea=Hobbies.
Line 914: Line 1,037:
Expected: save rejected with clear cycle error.
Expected: save rejected with clear cycle error.


## Scenario J: Topic behavior
=== Scenario J: Topic behavior ===


Create Topic:Python, assign it to several pages, then archive it.
Create Topic:Python, assign it to several pages, then archive it.
Line 922: Line 1,045:
---
---


# 37. Open Design Questions
== 37. Open Design Questions ==


The developer/coding AI shall not invent final behavior for these items without product approval:
The developer/coding AI shall not invent final behavior for these items without product approval:


1. Exact type-specific metadata fields for each PageType.
# Exact type-specific metadata fields for each PageType.
2. Exact topic-specific metadata definition format.
# Exact topic-specific metadata definition format.
3. Whether Topic pages may themselves be assigned RelatedTopics.
# Whether Topic pages may themselves be assigned RelatedTopics.
4. Whether Area pages may have Topics and/or RelatedProjects. Current recommendation: yes.
# Whether Area pages may have Topics and/or RelatedProjects. Current recommendation: yes.
5. Whether Project pages may have RelatedTopics. Current recommendation: yes.
# Whether Project pages may have RelatedTopics. Current recommendation: yes.
6. Exact VisualEditor integration approach.
# 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.
# 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.
# 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.
# 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.
# Whether starter content is installed by extension code, Page Exchange packages, XML import, or another mechanism.


---
---


# 38. Recommended Implementation Order
== 38. Recommended Implementation Order ==


Phase 1: Wiki Mode, PageType, PageStatus, Cargo table, basic metadata UI, validation.
Phase 1: Wiki Mode, PageType, PageStatus, Cargo table, basic metadata UI, validation.
Line 957: Line 1,080:
---
---


# 39. Testing Requirements
== 39. Testing Requirements ==


Automated tests shall cover at least:
Automated tests shall cover at least:


```text
<pre>
PageType validation
PageType validation
PageStatus validation
PageStatus validation
Line 980: Line 1,103:
page deletion/dangling-reference detection
page deletion/dangling-reference detection
API validation
API validation
```
</pre>


Use MediaWiki-supported unit/integration test frameworks appropriate to the installed version.
Use MediaWiki-supported unit/integration test frameworks appropriate to the installed version.
Line 986: Line 1,109:
---
---


# 40. Coding Standards
== 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.
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.
Line 994: Line 1,117:
---
---


# 41. Naming Standard
== 41. Naming Standard ==


Canonical internal names:
Canonical internal names:


```text
<pre>
WikiMode
WikiMode
PageType
PageType
Line 1,008: Line 1,131:
TopicName
TopicName
TopicStatus
TopicStatus
```
</pre>


Recommended user-facing labels:
Recommended user-facing labels:


```text
<pre>
Wiki Mode
Wiki Mode
Type
Type
Line 1,020: Line 1,143:
Related Projects
Related Projects
Topics
Topics
```
</pre>


Avoid underscores such as `Page_Type` unless required by a specific external convention. Avoid numbered relationship properties.
Avoid underscores such as <code>Page_Type</code> unless required by a specific external convention. Avoid numbered relationship properties.


---
---


# 42. Summary of Core Business Rules
== 42. Summary of Core Business Rules ==


```text
<pre>
Every PARA knowledge page:
Every PARA knowledge page:
     exactly one PageType
     exactly one PageType
Line 1,061: Line 1,184:
     warning/report condition
     warning/report condition
     not a save-blocking error
     not a save-blocking error
```
</pre>


This model shall be treated as the implementation source of truth unless superseded by a later approved specification.
This model shall be treated as the implementation source of truth unless superseded by a later approved specification.
== Dynamic Hub Pages and Navigation ==
=== Purpose ===
Areas, Projects, and Topics shall function as navigational hubs in addition to storing user-authored content.
The system-generated relationship information shall be derived from structured metadata and shall not require the user to manually maintain lists of related pages.
The implementation should use one generalized '''Hub Page''' subsystem rather than separate unrelated implementations for Areas, Projects, and Topics.
=== Hub Page Types ===
The Hub Page subsystem shall apply to:
* pages whose <code>PageType=Area</code>
* pages whose <code>PageType=Project</code>
* pages in the <code>Topic:</code> namespace
The relationship used to populate the dynamic page list depends on the hub type:
{| class="wikitable"
! Hub type !! Relationship query
|-
| Area || Pages whose <code>RelatedAreas</code> contains the current Area
|-
| Project || Pages whose <code>RelatedProjects</code> contains the current Project
|-
| Topic || Pages whose <code>RelatedTopics</code> contains the current Topic
|}
=== Hub Page Layout ===
The rendered page should conceptually contain:
<pre>
Page title
Editable introductory content
System-generated hub section
Optional editable additional content
</pre>
The generated section shall not be directly editable and shall not be saved as ordinary wikitext.
Preferred long-term architecture:
<pre>
main revision-backed content slot
system-generated hub component
secondary revision-backed content slot (optional lower content)
</pre>
Before implementing a secondary slot, verify compatibility with the installed MediaWiki version and VisualEditor. If this materially increases version 1 complexity, version 1 may append the generated hub after the main editable content and defer lower editable content.
=== Area Hub Pages ===
An Area page shall automatically display:
* its Parent Area, when one exists
* its immediate child Areas
* pages directly associated with the Area
* sorting controls
Child Areas are derived from:
<pre>
ParentArea = current Area
</pre>
Directly associated pages are derived from:
<pre>
RelatedAreas HOLDS current Area
</pre>
Direct relationships shall be the default. Descendant content may optionally be included through a control such as "Include pages from sub-areas". Descendant inclusion shall be computed from the hierarchy; ancestor Areas shall not be redundantly written into RelatedAreas.
=== Project Hub Pages ===
A Project page shall automatically display:
* Project metadata
* Related Areas
* pages whose <code>RelatedProjects</code> contains the current Project
* sorting controls
Project-specific metadata such as target date, completion date, progress, or outcome may be displayed when implemented.
=== Topic Hub Pages ===
A Topic page shall automatically display:
* user-authored Topic description
* pages whose <code>RelatedTopics</code> contains the current Topic
* sorting controls
* optional derived counts grouped by PageType
The counts and lists shall be dynamically derived and not manually maintained.
=== Hub List Sorting ===
Every generated relationship list shall support:
* Page Name
* Creation Date
* Last Edit Date
The query layer shall support ascending and descending order.
Recommended user-facing choices:
<pre>
Name A-Z
Name Z-A
Newest Created
Oldest Created
Recently Updated
Least Recently Updated
</pre>
Default: <code>Name A-Z</code>, unless configured otherwise.
=== Hub List Filtering ===
The architecture shall support future filters including:
* PageStatus
* PageType
* direct relationships versus descendant Area relationships
Archived content should be excluded from normal hub lists by default where appropriate and exposed through an explicit filter.
=== Page Creation and Last-Edit Dates ===
MediaWiki revision history shall remain authoritative for creation and last-edit timestamps.
For efficient querying and sorting, the application may maintain indexed/cached values:
<pre>
CreatedAt
UpdatedAt
</pre>
The implementation shall document how they are populated and refreshed and should avoid querying the earliest revision of every result during ordinary rendering.
=== Permissions ===
All generated Hub content shall respect MediaWiki read permissions and future sharing/ACL rules.
A viewer shall not learn the title, existence, metadata, or count contribution of a page they cannot view.
This applies to relationship lists, child Areas, counts, filters, autocomplete, Topic breakdowns, Main Page lists, and APIs.
=== Pagination and Performance ===
Generated lists shall support pagination and server-side sorting for large result sets.
The implementation should use indexed query fields, avoid full-table scans, use MediaWiki caching where appropriate, and invalidate/refresh cached output when relevant relationships or metadata change.
The subsystem should remain practical for hubs containing thousands of related pages.
=== Empty States ===
Hub pages shall render useful empty-state messages, such as:
<pre>
No pages are currently associated with this Area.
No pages are currently assigned to this Project.
No pages currently use this Topic.
</pre>
== Main Page Dashboard ==
In PARA Wiki mode, the Main Page shall provide generated navigation in addition to user-configurable introductory content.
At minimum it shall display:
* a hierarchical list of active Areas
* Active Projects
=== Area Hierarchy ===
Top-level Areas are:
<pre>
PageType = Area
PageStatus = Active
ParentArea = NULL
</pre>
Each top-level Area shall display active child Areas recursively or to a configurable display depth.
The hierarchy shall be derived from <code>ParentArea</code>, never manually maintained.
Archived Areas shall be excluded by default.
=== Active Projects ===
The Main Page shall display:
<pre>
PageType = Project
PageStatus = Active
</pre>
Each title shall link to its Project hub page.
Provide a link to an All Projects view that can include Inception and Archived Projects.
The initial Main Page should remain concise; recently edited pages, unclassified counts, and Wiki Health summaries may be added later.
== System Index Pages ==
The extension shall provide generated index views for:
* All Areas
* All Projects
* All Topics
* Wiki Health
* Unclassified Pages
Where practical these should be MediaWiki Special pages rather than editable normal pages.
Recommended routes:
<pre>
Special:Areas
Special:Projects
Special:Topics
Special:WikiHealth
Special:UnclassifiedPages
</pre>
=== All Areas ===
Support hierarchical display, Active/Archived filtering, links to Area hubs, and optional direct/descendant page counts.
=== All Projects ===
Support PageStatus filtering, Area filtering, sorting by Page Name/Creation Date/Last Edit Date, and links to Project hubs.
=== All Topics ===
At minimum show Topic name, link, Active/Archived filtering, and count of accessible pages using the Topic.
Recommended sorting:
<pre>
Name
Number of Pages
Recently Used
Creation Date
Last Edit Date
</pre>
Potential future maintenance views include unused Topics, Topics without descriptions, archived Topics, and possible duplicates.
== Hub Subsystem Technical Architecture ==
Implement a generalized service rather than independent Cargo queries embedded in templates.
Recommended conceptual components:
{| class="wikitable"
! Component !! Responsibility
|-
| <code>HubService</code> || Determine whether the current page is a Hub and assemble its view model.
|-
| <code>HubQueryService</code> || Retrieve related pages using the appropriate relationship.
|-
| <code>HubRenderer</code> || Render generated Hub sections.
|-
| <code>AreaHierarchyService</code> || Resolve parents, children, descendants, and cycle-safe traversal.
|-
| <code>HubSort</code> || Validate and translate supported sort modes.
|-
| <code>HubFilter</code> || Validate and apply supported filters.
|}
Templates may assist presentation, but relationship selection, permissions, hierarchy traversal, sorting, and validation shall reside in extension code.
Relationship mapping:
<pre>
Area    -> RelatedAreas
Project -> RelatedProjects
Topic  -> RelatedTopics
</pre>
Adding a future Hub-capable object should not require rewriting the subsystem.
== Additional API Requirements for Hubs and Indexes ==
The API shall additionally support operations equivalent to:
<pre>
Get hub metadata
List pages related to an Area
List pages related to a Project
List pages related to a Topic
List child Areas
List Area descendants
List Area hierarchy
List Projects by status
List Topics
</pre>
List operations shall support pagination and, where relevant:
<pre>
sort
direction
status
pageType
includeArchived
includeDescendants
limit
continuation
</pre>
Exact names shall follow MediaWiki/API conventions.
== Additional Acceptance Criteria for Dynamic Hubs ==
=== Scenario K: Area Hub ===
Given Personal as an Active Area and several pages with <code>RelatedAreas=Personal</code>:
* Personal automatically lists those pages.
* no manually maintained list is required
* changing RelatedAreas updates Hub membership
* generated list is not editable as ordinary page text
=== Scenario L: Hub Sorting ===
Given related pages with different names, creation dates, and edit dates:
* sort alphabetically
* sort by creation date
* sort by last edit date
* sorting does not modify metadata
* sorting works with pagination
=== Scenario M: Area Hierarchy ===
Given Photography and Cooking with <code>ParentArea=Hobbies</code>:
* Hobbies displays them as children
* each child displays Hobbies as parent
* hierarchy is generated from ParentArea
=== Scenario N: Direct Area Relationships ===
Given <code>Canon EOS R10</code> with <code>RelatedAreas=Photography</code>:
* it appears in Photography's direct list
* it does not appear in Hobbies' direct list solely because Photography is beneath Hobbies
* a descendant-inclusive view may include it
=== Scenario O: Project Hub ===
Given <code>Hotels in Rome</code> with <code>RelatedProjects=Plan Italy vacation</code>:
* Plan Italy vacation automatically lists Hotels in Rome
* Project Areas are displayed
* generated list is not directly editable
=== Scenario P: Topic Hub ===
Given <code>Topic:Python</code> and multiple pages using it:
* Topic:Python lists accessible associated pages
* it may display derived PageType counts
* archiving the Topic does not destroy relationships
=== Scenario Q: Main Page Area Tree ===
* active top-level Areas render hierarchically
* child Areas appear beneath parents
* archived Areas are excluded by default
* links point to Area hubs
=== Scenario R: Main Page Projects ===
* Active Projects display by default
* Inception and Archived Projects do not
* All Projects view can expose other statuses
=== Scenario S: Topics Index ===
* Special:Topics lists accessible Topics
* Topics can be sorted by name
* usage counts respect permissions
* archived Topics can be filtered
=== Scenario T: Hub Permissions ===
* inaccessible related pages are not displayed
* inaccessible titles do not contribute to exposed counts
* API behavior matches rendered-page behavior
== Additional Open Design Questions ==
# Whether version 1 supports editable content both above and below the generated Hub section, or initially only before it.
# Whether a secondary MediaWiki content slot provides acceptable VisualEditor behavior.
# Whether descendant-Area inclusion ships in version 1 or is deferred.
# Whether Hub sort/filter preferences are temporary, per-user, or per-Hub.
# Exact default pagination size.
# Whether Topic PageType breakdown counts ship in version 1.
# Whether Main Page dashboard sections are configurable/reorderable in version 1.
# Whether system indexes also expose transcludable components in addition to Special pages.
Retrieved from "https://wiki.goalstriving.org/Requirements_and_Specifications"