itworx-knowledge-hub-Public/docs/15-project-hub.md

Project hub

Purpose

Project dossiers turn scattered project notes into a reliable current-state and history view while keeping long-form documents as normal wiki pages.

A project is not a duplicate folder. It is a structured aggregate linked to pages, decisions, runbooks, updates and milestones.

Project fields

Required:

• name;
• slug;
• concise summary;
• lifecycle status;
• priority;
• current-state Markdown;
• owner;
• created/updated timestamps.

Optional:

• start/target/completion dates;
• repository URL;
• live URL;
• documentation URL;
• issue tracker URL;
• technologies;
• icon/image;
• visibility classification;
• external identifiers.

URLs are validated and never used for server-side fetches in v1.

Lifecycle

Concept → Planned → Active ↔ Blocked
                         ↘ Maintenance
Any non-archived state → Paused
Active/Maintenance → Completed
Any state → Archived

Transitions are flexible enough for personal projects but recorded in project history. Archived projects remain searchable by explicit filter and API permission.

Project overview

The page contains:

1. status and summary;
2. current verified state;
3. primary links and technologies;
4. active milestones;
5. recent project updates;
6. accepted/current decisions;
7. important runbooks;
8. linked architecture/deployment/testing/troubleshooting pages;
9. known issues/documentation warnings;
10. revision/history access.

The default view is concise. It does not render every full linked document.

Project documents

A page can be linked with a role:

• Overview
• Current state
• Architecture
• Deployment
• Infrastructure
• Security
• Testing
• Troubleshooting
• Release
• User documentation
• Other

One page may be linked to multiple projects where meaningful. The page remains canonical; the project stores the relationship, not a copy.

Project updates

Categories:

• Progress
• Feature
• Fix
• Deployment
• Validation
• Release
• Decision
• Risk
• Blocker
• Documentation
• Maintenance

An update includes title, bounded summary Markdown, occurred time, actor/source, verification status and optional references:

• commit SHA;
• release/tag;
• issue identifier;
• URL;
• page;
• decision;
• milestone;
• attachment.

Verification status:

• Reported
• Verified
• Superseded

The UI must distinguish reported agent/user claims from validated evidence.

Project milestones

Project-specific milestones have:

• name;
• order;
• state;
• target date;
• completion date;
• summary;
• success criteria;
• linked updates/documents.

They do not reuse repository build milestone IDs.

Project context bundle

The bounded context API is designed for external retrieval:

• project identity/status/summary/current state;
• configurable number of recent verified updates;
• active milestones;
• accepted decisions;
• validated runbooks;
• selected document summaries and citations;
• known blockers;
• explicit truncation information.

It must not synthesize facts that are not stored. Summaries are stored/maintained fields, not automatic LLM output in v1.

Dashboard behavior

Active projects show:

• name/status;
• one-line current state;
• last verified update;
• stale/documentation warning;
• direct open action.

Cards use consistent heights and alignment without hiding essential content.

Deletion/archive

Projects archive by default. Deletion cannot delete linked pages. Timeline, decision and audit history remains recoverable. A privileged purge path requires explicit dependency review.