@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.0

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@latysh-development/monolith",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.0",
+  "description": "MONOLITH: Cognitive Infrastructure for AI. An open-source toolkit for observable project state, structured knowledge, and explicit execution governance.",
+  "author": "Dmytro Latysh",
+  "license": "MIT",
+  "homepage": "https://github.com/Demion-L/the_monolith#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Demion-L/the_monolith.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Demion-L/the_monolith/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/scripts",
+    "templates"
+  ],
+  "bin": {
+    "monolith": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "dogfood-graph": "node dist/scripts/dogfood-graph.js",
+    "prepublishOnly": "npm run build",
+    "dev:api": "node dist/scripts/dev-api.js",
+    "dev:ui": "vite --config ui/vite.config.ts",
+    "typecheck:ui": "vue-tsc -p ui/tsconfig.json --noEmit",
+    "build:ui": "vite build --config ui/vite.config.ts",
+    "test:ui": "vitest run --config ui/vitest.config.ts"
+  },
+  "keywords": [
+    "monolith",
+    "knowledge-toolkit",
+    "ai-assistant",
+    "enforcement",
+    "protocol"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitejs/plugin-vue": "^5",
+    "@vue/test-utils": "^2",
+    "jsdom": "^25",
+    "typescript": "^5.6.3",
+    "vite": "^6",
+    "vitest": "^2.0.0",
+    "vue": "^3.5",
+    "vue-tsc": "^2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/default-instance/instruction/.cursorrules

@@ -0,0 +1,53 @@
+# {{PROJECT_NAME}} — Cursor Instructions
+
+This repository runs MONOLITH, a portable project knowledge and governance toolkit for AI-assisted development.
+Before acting on any skill-triggering request, read the corresponding skill file.
+
+---
+
+## Session Start (every session)
+
+Before starting any task, read in order:
+
+1. `AGENTS.md` — project overview, architecture principles, current scope
+2. `{{MONOLITH_ROOT}}/memory/working/active.md` — what story is active (or confirm none)
+3. `{{MONOLITH_ROOT}}/context/maps/routing-map.md` — classify the task type
+4. `{{MONOLITH_ROOT}}/learning/injection-map.md` — load lesson categories relevant to the task type
+5. `{{MONOLITH_ROOT}}/protocols/cognition/cognitive-modes.md` — declare the behavioral mode for this task
+
+Declare the cognitive mode before starting work. State it explicitly: "Mode: implementation" or "Mode: exploration". This constrains what mutations are allowed.
+
+---
+
+## Skill Activation
+
+When the user's request matches a trigger phrase, read the skill file before taking any action.
+
+| Trigger phrases | Skill |
+|---|---|
+| "finalize story", "finalize X.Y", "complete story", "mark story done" | `{{MONOLITH_ROOT}}/skills/finalize-story/SKILL.md` |
+| "status", "what are we working on", "current status" | `{{MONOLITH_ROOT}}/skills/current-status/SKILL.md` |
+| "global overview", "project status", "global status" | `{{MONOLITH_ROOT}}/skills/global-status/SKILL.md` |
+| "analyze mistake", "learn from error", "self-improvement" | `{{MONOLITH_ROOT}}/skills/self-improvement/SKILL.md` |
+
+Full skill index: `{{MONOLITH_ROOT}}/skills/INDEX.md`
+Routing map: `{{MONOLITH_ROOT}}/context/maps/routing-map.md`
+
+---
+
+## Key Protocols
+
+- Memory governance: `{{MONOLITH_ROOT}}/protocols/governance/memory-governance.md`
+- Command policy: `{{MONOLITH_ROOT}}/protocols/governance/command-policy.md`
+- Core invariants: `{{MONOLITH_ROOT}}/protocols/governance/core-invariants.md`
+- Skills governance: `{{MONOLITH_ROOT}}/protocols/governance/skills.md`
+
+---
+
+## Project Structure (quick reference)
+
+| Layer | Path | Purpose |
+|---|---|---|
+| Working memory | `{{MONOLITH_ROOT}}/memory/working/` | Active story, story index |
+| Long-term memory | `{{MONOLITH_ROOT}}/memory/long-term/` | Decisions, execution history |
+| Skills | `{{MONOLITH_ROOT}}/skills/` | Workflow procedures |

package/templates/default-instance/instruction/.windsurfrules

@@ -0,0 +1,53 @@
+# {{PROJECT_NAME}} — Windsurf Instructions
+
+This repository runs MONOLITH, a portable project knowledge and governance toolkit for AI-assisted development.
+Before acting on any skill-triggering request, read the corresponding skill file.
+
+---
+
+## Session Start (every session)
+
+Before starting any task, read in order:
+
+1. `AGENTS.md` — project overview, architecture principles, current scope
+2. `{{MONOLITH_ROOT}}/memory/working/active.md` — what story is active (or confirm none)
+3. `{{MONOLITH_ROOT}}/context/maps/routing-map.md` — classify the task type
+4. `{{MONOLITH_ROOT}}/learning/injection-map.md` — load lesson categories relevant to the task type
+5. `{{MONOLITH_ROOT}}/protocols/cognition/cognitive-modes.md` — declare the behavioral mode for this task
+
+Declare the cognitive mode before starting work. State it explicitly: "Mode: implementation" or "Mode: exploration". This constrains what mutations are allowed.
+
+---
+
+## Skill Activation
+
+When the user's request matches a trigger phrase, read the skill file before taking any action.
+
+| Trigger phrases | Skill |
+|---|---|
+| "finalize story", "finalize X.Y", "complete story", "mark story done" | `{{MONOLITH_ROOT}}/skills/finalize-story/SKILL.md` |
+| "status", "what are we working on", "current status" | `{{MONOLITH_ROOT}}/skills/current-status/SKILL.md` |
+| "global overview", "project status", "global status" | `{{MONOLITH_ROOT}}/skills/global-status/SKILL.md` |
+| "analyze mistake", "learn from error", "self-improvement" | `{{MONOLITH_ROOT}}/skills/self-improvement/SKILL.md` |
+
+Full skill index: `{{MONOLITH_ROOT}}/skills/INDEX.md`
+Routing map: `{{MONOLITH_ROOT}}/context/maps/routing-map.md`
+
+---
+
+## Key Protocols
+
+- Memory governance: `{{MONOLITH_ROOT}}/protocols/governance/memory-governance.md`
+- Command policy: `{{MONOLITH_ROOT}}/protocols/governance/command-policy.md`
+- Core invariants: `{{MONOLITH_ROOT}}/protocols/governance/core-invariants.md`
+- Skills governance: `{{MONOLITH_ROOT}}/protocols/governance/skills.md`
+
+---
+
+## Project Structure (quick reference)
+
+| Layer | Path | Purpose |
+|---|---|---|
+| Working memory | `{{MONOLITH_ROOT}}/memory/working/` | Active story, story index |
+| Long-term memory | `{{MONOLITH_ROOT}}/memory/long-term/` | Decisions, execution history |
+| Skills | `{{MONOLITH_ROOT}}/skills/` | Workflow procedures |

package/templates/default-instance/instruction/CLAUDE.md

@@ -0,0 +1,53 @@
+# {{PROJECT_NAME}} — Claude Code Instructions
+
+This repository runs MONOLITH, a portable project knowledge and governance toolkit for AI-assisted development.
+Before acting on any skill-triggering request, read the corresponding skill file.
+
+---
+
+## Session Start (every session)
+
+Before starting any task, read in order:
+
+1. `AGENTS.md` — project overview, architecture principles, current scope
+2. `{{MONOLITH_ROOT}}/memory/working/active.md` — what story is active (or confirm none)
+3. `{{MONOLITH_ROOT}}/context/maps/routing-map.md` — classify the task type
+4. `{{MONOLITH_ROOT}}/learning/injection-map.md` — load lesson categories relevant to the task type
+5. `{{MONOLITH_ROOT}}/protocols/cognition/cognitive-modes.md` — declare the behavioral mode for this task
+
+**Declare the cognitive mode before starting work.** State it explicitly: "Mode: implementation" or "Mode: exploration". This constrains what mutations are allowed.
+
+---
+
+## Skill Activation
+
+When the user's request matches a trigger phrase, **read the skill file before taking any action**.
+
+| Trigger phrases | Skill |
+|---|---|
+| "finalize story", "finalize X.Y", "complete story", "mark story done" | `{{MONOLITH_ROOT}}/skills/finalize-story/SKILL.md` |
+| "status", "what are we working on", "current status" | `{{MONOLITH_ROOT}}/skills/current-status/SKILL.md` |
+| "global overview", "project status", "global status" | `{{MONOLITH_ROOT}}/skills/global-status/SKILL.md` |
+| "analyze mistake", "learn from error", "self-improvement" | `{{MONOLITH_ROOT}}/skills/self-improvement/SKILL.md` |
+
+Full skill index: `{{MONOLITH_ROOT}}/skills/INDEX.md`
+Routing map: `{{MONOLITH_ROOT}}/context/maps/routing-map.md`
+
+---
+
+## Key Protocols
+
+- Memory governance: `{{MONOLITH_ROOT}}/protocols/governance/memory-governance.md`
+- Command policy: `{{MONOLITH_ROOT}}/protocols/governance/command-policy.md`
+- Core invariants: `{{MONOLITH_ROOT}}/protocols/governance/core-invariants.md`
+- Skills governance: `{{MONOLITH_ROOT}}/protocols/governance/skills.md`
+
+---
+
+## Project Structure (quick reference)
+
+| Layer | Path | Purpose |
+|---|---|---|
+| Working memory | `{{MONOLITH_ROOT}}/memory/working/` | Active story, story index |
+| Long-term memory | `{{MONOLITH_ROOT}}/memory/long-term/` | Decisions, execution history |
+| Skills | `{{MONOLITH_ROOT}}/skills/` | Workflow procedures |

package/templates/default-instance/monolith/context/boot/HANDOFF.md

@@ -0,0 +1,49 @@
+---
+type: context
+id: context-boot-handoff
+category: boot
+stability: volatile
+authority: authoritative
+---
+
+# Session Handoff
+
+Transfer capsule for the next AI session.
+
+Update this file at the end of each work session before closing.
+
+---
+
+## Active Story
+
+<!-- STORY X.Y — Story Name -->
+
+---
+
+## Objective
+
+<!-- What was being worked on? What is the goal of this story? -->
+
+---
+
+## Completed This Session
+
+<!-- Bullet list of what was done. -->
+
+---
+
+## Constraints
+
+<!-- Any constraints or decisions made that the next session must respect. -->
+
+---
+
+## Next Step
+
+<!-- Exactly what to do first in the next session. Be specific. -->
+
+---
+
+## Files in Flight
+
+<!-- Files that were being edited but may not be complete. -->

package/templates/default-instance/monolith/context/boot/WORK_SESSION.md

@@ -0,0 +1,30 @@
+---
+type: context
+id: context-boot-work-session
+category: boot
+stability: volatile
+---
+
+# Work Session
+
+Active work session context.
+
+Updated by the finalize-story skill at story completion.
+
+---
+
+## Story
+
+<!-- STORY X.Y — Story Name -->
+
+## Phase
+
+<!-- Phase N — Phase Name -->
+
+## Status
+
+<!-- IN PROGRESS | COMPLETE -->
+
+## Session Log
+
+<!-- Brief log of actions taken this session. -->

package/templates/default-instance/monolith/context/execution/current-state.md

@@ -0,0 +1,30 @@
+---
+type: context
+id: context-execution-current-state
+category: execution
+stability: volatile
+---
+
+# Current State
+
+Global navigation state. Legacy fallback for Full Recovery Mode.
+
+For primary navigation use: `memory/working/active.md`
+
+---
+
+## Active Phase
+
+<!-- Phase N — Phase Name -->
+
+## Active Story
+
+<!-- STORY X.Y — Story Name -->
+
+## Last Update
+
+<!-- YYYY-MM-DD -->
+
+## Notes
+
+<!-- Any context needed for recovery that isn't in active.md -->

package/templates/default-instance/monolith/context/maps/dependency-map.md

@@ -0,0 +1,38 @@
+---
+type: context
+id: dependency-map
+topology_role: root
+authority: authoritative
+---
+
+# Dependency Map
+
+Tracks dependencies between stories, skills, protocols, and memory.
+
+---
+
+## Story Dependencies
+
+<!-- Added as stories are created. -->
+<!-- Format: STORY X.Y depends on STORY X.Z (reason) -->
+
+---
+
+## Skill Dependencies
+
+| Skill            | Depends On                                                   |
+| ---------------- | ------------------------------------------------------------ |
+| finalize-story   | memory-governance, integrity-verification                    |
+| current-status   | memory/working/active.md                                     |
+| global-status    | docs/adr/README.md, memory/long-term/decisions.md, context/maps/roadmap-index.md |
+| self-improvement | memory/errors/, learning/taxonomy.md                         |
+
+---
+
+## Protocol Dependencies
+
+| Protocol               | Depends On                        |
+| ---------------------- | --------------------------------- |
+| finalize-story         | memory-governance                 |
+| integrity-verification | memory-governance                 |
+| failure-memory-logging | memory-governance, error-taxonomy |

package/templates/default-instance/monolith/context/maps/project-map.md

@@ -0,0 +1,85 @@
+---
+type: context
+id: project-map
+topology_role: root
+authority: authoritative
+---
+
+# Project Map — {{PROJECT_NAME}}
+
+Navigation guide for the cognitive architecture of this project.
+
+---
+
+## Memory
+
+| Location                                                        | Purpose                 |
+| --------------------------------------------------------------- | ----------------------- |
+| `{{MONOLITH_ROOT}}/memory/working/active.md`                    | Active phase and story  |
+| `{{MONOLITH_ROOT}}/memory/working/story-index.md`               | Implementation history  |
+| `{{MONOLITH_ROOT}}/memory/long-term/decisions.md`               | Non-ADR decisions (`DEC-…`) |
+| `{{MONOLITH_ROOT}}/memory/long-term/architecture-principles.md` | Core principles         |
+| `{{MONOLITH_ROOT}}/memory/long-term/tech-debt.md`               | Tech debt registry      |
+| `{{MONOLITH_ROOT}}/memory/long-term/execution-history.md`       | Finalization log        |
+
+---
+
+## Context
+
+| Location                                           | Purpose                |
+| -------------------------------------------------- | ---------------------- |
+| `{{MONOLITH_ROOT}}/context/maps/routing-map.md`    | Task type → activation |
+| `{{MONOLITH_ROOT}}/context/maps/roadmap-index.md`  | Phases and progress    |
+| `{{MONOLITH_ROOT}}/context/maps/semantic-map.md`   | Where truth lives      |
+| `{{MONOLITH_ROOT}}/context/maps/dependency-map.md` | Artifact dependencies  |
+| `{{MONOLITH_ROOT}}/context/boot/HANDOFF.md`        | Session transfer       |
+
+---
+
+## Skills
+
+| Skill                                                | Trigger          |
+| ---------------------------------------------------- | ---------------- |
+| `{{MONOLITH_ROOT}}/skills/finalize-story/SKILL.md`   | finalize story   |
+| `{{MONOLITH_ROOT}}/skills/current-status/SKILL.md`   | status check     |
+| `{{MONOLITH_ROOT}}/skills/global-status/SKILL.md`    | global overview  |
+| `{{MONOLITH_ROOT}}/skills/self-improvement/SKILL.md` | self improvement |
+
+---
+
+## Protocols
+
+| Protocol                                                      | Purpose               |
+| ------------------------------------------------------------- | --------------------- |
+| `{{MONOLITH_ROOT}}/protocols/boot/boot-sequence.md`           | Session startup order |
+| `{{MONOLITH_ROOT}}/protocols/cognition/cognitive-modes.md`    | Behavioral modes      |
+| `{{MONOLITH_ROOT}}/protocols/governance/memory-governance.md` | Memory rules          |
+| `{{MONOLITH_ROOT}}/protocols/governance/core-invariants.md`   | Always-on rules       |
+
+---
+
+## Knowledge Base
+
+| Location                              | Purpose                                              |
+| ------------------------------------- | ---------------------------------------------------- |
+| `MANIFESTO.md`                        | Engineering foundation — why this project exists     |
+| `docs/README.md`                      | Knowledge base navigation index                      |
+| `docs/DOCUMENTATION_PRINCIPLES.md`   | Documentation rules and layer hierarchy              |
+| `docs/adr/`                           | Architecture Decision Records                        |
+| `docs/adr/README.md`                  | The only ADR index (created with the first ADR)      |
+| `docs/architecture/`                  | Current system description                           |
+
+Add `docs/research/` and `docs/vision/` layers if this project's own
+knowledge base needs them — they are not provisioned by default.
+
+---
+
+## Project Structure
+
+<!-- Describe your project's source code structure here. -->
+<!-- Example: -->
+<!-- | Directory | Purpose | -->
+<!-- |-----------|---------|  -->
+<!-- | `src/` | Application source code | -->
+<!-- | `packages/` | Shared packages | -->
+<!-- | `apps/` | Application entry points | -->

package/templates/default-instance/monolith/context/maps/roadmap-index.md

@@ -0,0 +1,41 @@
+---
+type: context
+id: roadmap-index
+topology_role: root
+authority: authoritative
+---
+
+# Roadmap Index — {{PROJECT_NAME}}
+
+Navigable index of project phases and their status.
+
+---
+
+## Phases
+
+<!-- Add phases below. Status: PLANNED | IN PROGRESS | COMPLETE -->
+
+### Phase 1 — (Add phase name)
+
+**Status:** PLANNED
+
+Stories:
+
+- STORY 1.1 — (Add story name)
+
+---
+
+## Current Focus
+
+<!-- Keep this in sync with memory/working/active.md -->
+
+Active Phase: —
+Active Story: —
+
+---
+
+## Completion Summary
+
+| Phase | Stories | Status |
+| ----- | ------- | ------ |
+| —     | —       | —      |

package/templates/default-instance/monolith/context/maps/routing-map.md

@@ -0,0 +1,147 @@
+---
+type: context
+id: routing-map
+topology_role: root
+---
+
+# Routing Map
+
+## Purpose
+
+Declarative activation map. Given a task type, resolves:
+
+- which cognitive mode to apply
+- which skill to activate
+- which protocols to enforce
+- which memory regions to load
+- which learning categories to inject
+- what model tier to use
+
+---
+
+## Table 1 — Task Type → Cognitive Mode
+
+| Task Type            | Cognitive Mode |
+| -------------------- | -------------- |
+| finalize-story       | finalization   |
+| implementation-task  | implementation |
+| new-feature          | implementation |
+| bug-investigation    | debugging      |
+| architecture-review  | review         |
+| code-review          | review         |
+| planning-request     | planning       |
+| exploration-request  | exploration    |
+| status-check         | exploration    |
+| global-overview      | exploration    |
+| learning-update      | reflection     |
+| self-improvement     | reflection     |
+| story-transition     | finalization   |
+| documentation-update | implementation |
+
+Reference: `{{MONOLITH_ROOT}}/protocols/cognition/cognitive-modes.md`
+
+---
+
+## Table 2 — Task Type → Skills
+
+| Task Type            | Primary Skill        |
+| -------------------- | -------------------- |
+| finalize-story       | finalize-story       |
+| status-check         | current-status       |
+| global-overview      | global-status        |
+| self-improvement     | self-improvement     |
+| implementation-task  | (no dedicated skill) |
+| new-feature          | (no dedicated skill) |
+| bug-investigation    | (no dedicated skill) |
+| architecture-review  | (no dedicated skill) |
+| code-review          | (no dedicated skill) |
+| planning-request     | (no dedicated skill) |
+| exploration-request  | (no dedicated skill) |
+| learning-update      | self-improvement     |
+| story-transition     | finalize-story       |
+| documentation-update | (no dedicated skill) |
+
+Skill files: `{{MONOLITH_ROOT}}/skills/`
+
+---
+
+## Table 3 — Task Type → Protocols
+
+| Task Type            | Protocols                                                 |
+| -------------------- | --------------------------------------------------------- |
+| finalize-story       | finalize-story, memory-governance, integrity-verification |
+| implementation-task  | memory-governance, command-policy                         |
+| new-feature          | memory-governance, command-policy                         |
+| bug-investigation    | memory-governance, command-policy                         |
+| architecture-review  | memory-governance, core-invariants                        |
+| code-review          | memory-governance, command-policy                         |
+| planning-request     | memory-governance, semantic-planning                      |
+| exploration-request  | memory-governance                                         |
+| status-check         | memory-governance                                         |
+| global-overview      | memory-governance                                         |
+| learning-update      | memory-governance, failure-memory-logging                 |
+| self-improvement     | memory-governance, failure-memory-logging                 |
+| story-transition     | memory-governance, finalize-story                         |
+| documentation-update | memory-governance                                         |
+
+---
+
+## Table 4 — Task Type → Memory Regions
+
+| Task Type           | Memory Regions                                                         |
+| ------------------- | ---------------------------------------------------------------------- |
+| finalize-story      | working/active, working/story-index, long-term/execution-history       |
+| implementation-task | working/active, long-term/architecture-principles                      |
+| new-feature         | working/active, long-term/decisions, long-term/architecture-principles |
+| bug-investigation   | working/active, long-term/tech-debt                                    |
+| architecture-review | working/active, long-term/decisions, long-term/architecture-principles |
+| planning-request    | working/active, context/maps/roadmap-index                             |
+| status-check        | working/active, context/maps/roadmap-index                             |
+| global-overview     | working/active, long-term/decisions, context/maps/roadmap-index        |
+| self-improvement    | learning/mistakes, memory/errors                                       |
+
+---
+
+## Table 5 — Task Type → Learning Hooks
+
+| Task Type           | Learning Categories                         |
+| ------------------- | ------------------------------------------- |
+| finalize-story      | workflow, architecture                      |
+| implementation-task | architecture, typescript, dependencies      |
+| new-feature         | architecture, dependencies                  |
+| bug-investigation   | architecture, nonexistent-api, context-sync |
+| code-review         | architecture, typescript                    |
+| self-improvement    | all categories                              |
+
+---
+
+## Table 6 — Task Type → Model Tier
+
+| Task Type            | Model Tier |
+| -------------------- | ---------- |
+| implementation-task  | default    |
+| new-feature          | default    |
+| architecture-review  | default    |
+| planning-request     | default    |
+| finalize-story       | default    |
+| bug-investigation    | default    |
+| code-review          | default    |
+| exploration-request  | default    |
+| status-check         | default    |
+| global-overview      | default    |
+| self-improvement     | default    |
+| documentation-update | default    |
+
+Model registry: `{{MONOLITH_ROOT}}/context/models/model-registry.md`
+Privacy rules: `{{MONOLITH_ROOT}}/context/models/privacy-classification.md`
+
+---
+
+## Table 7 — Fallback Routing Rules
+
+| Condition                      | Resolution                                    |
+| ------------------------------ | --------------------------------------------- |
+| Task type unclear              | Use exploration mode. Ask for clarification.  |
+| Multiple task types applicable | Use the most restrictive cognitive mode.      |
+| No matching skill              | Execute task inline without a skill template. |
+| Sensitive data in context      | Override to local model tier.                 |