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

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

@@ -0,0 +1,73 @@
+---
+type: context
+id: semantic-map
+topology_role: root
+authority: authoritative
+---
+
+# Semantic Map
+
+Where authoritative truth lives for each semantic domain.
+
+---
+
+## Memory Domain
+
+| What                   | Authoritative Source                    |
+| ---------------------- | --------------------------------------- |
+| Active story           | `memory/working/active.md`              |
+| Story history          | `memory/working/story-index.md`         |
+| ADR index              | `docs/adr/README.md` (repo-relative, outside `{{MONOLITH_ROOT}}`) |
+| Non-ADR decisions (`DEC-…`) | `memory/long-term/decisions.md`    |
+| Execution log          | `memory/long-term/execution-history.md` |
+| Error records          | `memory/errors/ERR-*.md`                |
+
+---
+
+## Context Domain
+
+| What               | Authoritative Source            |
+| ------------------ | ------------------------------- |
+| Task routing       | `context/maps/routing-map.md`   |
+| Project navigation | `context/maps/project-map.md`   |
+| Roadmap            | `context/maps/roadmap-index.md` |
+| Session state      | `context/boot/HANDOFF.md`       |
+
+---
+
+## Skills Domain
+
+| What             | Authoritative Source     |
+| ---------------- | ------------------------ |
+| Available skills | `skills/INDEX.md`        |
+| Skill procedures | `skills/<name>/SKILL.md` |
+
+---
+
+## Protocols Domain
+
+| What             | Authoritative Source                        |
+| ---------------- | ------------------------------------------- |
+| Boot order       | `protocols/boot/boot-sequence.md`           |
+| Behavioral modes | `protocols/cognition/cognitive-modes.md`    |
+| Memory rules     | `protocols/governance/memory-governance.md` |
+| Core invariants  | `protocols/governance/core-invariants.md`   |
+
+---
+
+## Learning Domain
+
+| What            | Authoritative Source            |
+| --------------- | ------------------------------- |
+| Error lessons   | `learning/mistakes/<category>/` |
+| Injection rules | `learning/injection-map.md`     |
+| Taxonomy        | `learning/taxonomy.md`          |
+
+---
+
+## Governance Domain
+
+| What             | Authoritative Source        |
+| ---------------- | --------------------------- |
+| Governance rules | `governance/GOV-*.md`       |
+| Rule schema      | `governance/RULE_SCHEMA.md` |

package/templates/default-instance/monolith/context/models/model-registry.md

@@ -0,0 +1,37 @@
+---
+type: context
+id: model-registry
+authority: authoritative
+---
+
+# Model Registry
+
+Available AI models and their capability tiers for this project.
+
+Reference: `context/models/privacy-classification.md`
+
+---
+
+## Tiers
+
+| Tier      | Description                    | Use When                            |
+| --------- | ------------------------------ | ----------------------------------- |
+| `default` | Cloud model (e.g. Claude Opus) | General tasks, public/internal data |
+| `local`   | Local LLM (e.g. Ollama)        | Sensitive/restricted data           |
+
+---
+
+## Default Model
+
+**Tool:** {{AI_TOOL}}  
+**Default tier:** cloud
+
+---
+
+## Privacy Override
+
+When context contains `sensitive` or `restricted` data:
+→ Switch to `local` tier if available
+→ Otherwise: proceed with caution and flag to user
+
+See: `protocols/execution/hybrid-execution.md`

package/templates/default-instance/monolith/context/models/privacy-classification.md

@@ -0,0 +1,35 @@
+---
+type: context
+id: privacy-classification
+authority: authoritative
+---
+
+# Privacy Classification
+
+Data classification levels that determine model tier routing.
+
+---
+
+## Levels
+
+| Level        | Examples                        | Model Tier      |
+| ------------ | ------------------------------- | --------------- |
+| `public`     | Open source code, public docs   | default (cloud) |
+| `internal`   | Internal architecture, planning | default (cloud) |
+| `sensitive`  | API keys, credentials, PII      | local only      |
+| `restricted` | Compliance data, secrets        | local only      |
+
+---
+
+## Detection Rules
+
+Flag as `sensitive` or `restricted` if the context includes:
+
+- API keys or tokens
+- Database credentials
+- Personal identifiable information (PII)
+- Payment data
+- Health data
+- Anything marked CONFIDENTIAL
+
+When flagged: route to `local` tier, or pause and alert user.

package/templates/default-instance/monolith/context/templates/plan-template.md

@@ -0,0 +1,56 @@
+---
+type: template
+id: plan-template
+category: templates
+---
+
+# Plan: {{PLAN_TITLE}}
+
+**Story:** STORY X.Y — Story Name  
+**Date:** YYYY-MM-DD  
+**Mode:** planning
+
+---
+
+## Objective
+
+<!-- What does this plan achieve? -->
+
+---
+
+## Constraints
+
+<!-- What must NOT change? What are the boundaries? -->
+
+---
+
+## Approach
+
+<!-- Step-by-step implementation approach. -->
+
+1.
+2.
+3.
+
+---
+
+## Files Affected
+
+| File | Change Type |
+| ---- | ----------- |
+|      |             |
+
+---
+
+## Risks
+
+<!-- What could go wrong? -->
+
+---
+
+## Definition of Done
+
+<!-- How will we know this is complete? -->
+
+- [ ]
+- [ ]

package/templates/default-instance/monolith/governance/README.md

@@ -0,0 +1,29 @@
+# Governance
+
+This directory stores active governance rules for this project.
+
+## Structure
+
+```
+governance/
+├── RULE_SCHEMA.md   — format for GOV-*.md files
+├── README.md        — this file
+└── GOV-*.md         — active governance rules (created at runtime)
+```
+
+## What Are Governance Rules?
+
+Rules created when repeated failure patterns are detected. They encode project-specific behavioral constraints that the AI assistant must follow.
+
+Unlike `protocols/governance/core-invariants.md` (universal rules), GOV-\*.md files are project-specific and evolve with the project.
+
+## Lifecycle
+
+1. A failure pattern is detected (via self-improvement skill or governance evaluation)
+2. A `GOV-*.md` file is created following `RULE_SCHEMA.md`
+3. The rule is enforced on subsequent sessions via the governance gate
+4. Rules can be superseded or archived when no longer relevant
+
+## Governance Evaluation
+
+Run `monolith validate` to check for rule violations.

package/templates/default-instance/monolith/governance/RULE_SCHEMA.md

@@ -0,0 +1,58 @@
+---
+type: schema
+id: governance-rule-schema
+authority: authoritative
+---
+
+# Governance Rule Schema
+
+Format for governance rules in `governance/GOV-*.md`.
+
+## File Naming
+
+`GOV-YYYY-XXXX.md` where YYYY = year, XXXX = sequential ID.
+
+## Fields
+
+```yaml
+---
+id: GOV-YYYY-XXXX
+date: YYYY-MM-DD
+trigger: pattern that activates this rule
+severity: critical | high | medium | low
+status: active | superseded | archived
+origin_story: STORY X.Y (optional — which story created this rule)
+---
+```
+
+## Body
+
+```markdown
+## Rule
+
+One-sentence statement of the rule. Must be actionable and unambiguous.
+
+## Context
+
+Why this rule exists. What failure pattern it prevents.
+
+## Pattern
+
+The trigger condition: what behavior or situation activates this rule.
+
+## Action
+
+What to do when the pattern is detected.
+
+## Examples
+
+Concrete examples of the rule in action.
+```
+
+## When to Create a Rule
+
+Create `GOV-*.md` when:
+
+- A mistake occurs more than once with the same root cause
+- A boundary violation is detected in governance evaluation
+- A new constraint is established through discussion

package/templates/default-instance/monolith/learning/INDEX.md

@@ -0,0 +1,48 @@
+---
+type: reference
+id: learning-index
+authority: authoritative
+---
+
+# Learning Layer
+
+Overview of the MONOLITH learning system for this project.
+
+---
+
+## Purpose
+
+Capture lessons from mistakes and inject them into future tasks to prevent repetition.
+
+---
+
+## Structure
+
+```
+learning/
+├── INDEX.md            — this file (navigation overview)
+├── taxonomy.md         — 8 error categories
+├── injection-map.md    — task type → lesson categories
+└── mistakes/
+    ├── architecture/         — architectural mistakes
+    ├── dependencies/         — dependency/import errors
+    ├── nonexistent-api/      — calling nonexistent methods/APIs
+    ├── context-sync/         — memory/state sync errors
+    ├── workflow/             — protocol violations
+    ├── typescript/           — TypeScript errors
+    └── documentation/        — missing or incorrect docs
+```
+
+---
+
+## How Lessons Are Injected
+
+At boot step 8, the AI reads `learning/injection-map.md` to determine which lesson categories to load based on the current task type.
+
+Lessons are searched by filename, tags, and keywords. Matching lessons are prepended to the task context to prevent known mistakes.
+
+---
+
+## How to Add a Lesson
+
+Use the `self-improvement` skill. Or manually create `LESSON-YYYY-XXXX.md` in the appropriate category directory.

package/templates/default-instance/monolith/learning/injection-map.md

@@ -0,0 +1,49 @@
+---
+type: reference
+id: learning-injection-map
+authority: authoritative
+---
+
+# Learning Injection Map
+
+Maps task types to lesson categories that should be loaded at boot step 8.
+
+---
+
+## Injection Rules
+
+| Task Type              | Load Lesson Categories                                    |
+| ---------------------- | --------------------------------------------------------- |
+| `implementation-task`  | architecture, typescript, dependencies                    |
+| `new-feature`          | architecture, dependencies                                |
+| `bug-investigation`    | architecture, nonexistent-api, context-sync, dependencies |
+| `code-review`          | architecture, typescript                                  |
+| `finalize-story`       | workflow, architecture                                    |
+| `architecture-review`  | architecture                                              |
+| `planning-request`     | architecture                                              |
+| `documentation-update` | documentation                                             |
+| `self-improvement`     | all categories                                            |
+| `learning-update`      | all categories                                            |
+| `status-check`         | context-sync                                              |
+| `global-overview`      | context-sync                                              |
+| `story-transition`     | workflow                                                  |
+| `exploration-request`  | context-sync                                              |
+
+---
+
+## Injection Threshold
+
+Load lessons if they contain at least one of:
+
+- A keyword matching the current task description
+- A tag matching the current task type or cognitive mode
+- A protocol name referenced in the current context
+
+---
+
+## Custom Injections
+
+Add project-specific injection rules at the bottom of this file.
+
+<!-- Example: -->
+<!-- | `database-migration` | architecture, context-sync, workflow | -->

package/templates/default-instance/monolith/learning/taxonomy.md

@@ -0,0 +1,30 @@
+---
+type: reference
+id: learning-taxonomy
+authority: authoritative
+---
+
+# Learning Taxonomy
+
+7 canonical categories for organizing lessons and mistakes.
+
+---
+
+| Category          | Lessons About                                                                       |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| `architecture`    | Structural violations, layer boundary breaches, coupling issues, wrong abstractions |
+| `dependencies`    | Missing packages, version conflicts, circular imports, import resolution errors     |
+| `nonexistent-api` | Calling functions, methods, endpoints, or properties that do not exist              |
+| `context-sync`    | Memory state out of sync with actual project state, stale assumptions               |
+| `workflow`        | Protocol violations, skipped steps, wrong execution order, gate bypass              |
+| `typescript`      | Type errors, incorrect generics, wrong inference, `any` misuse                      |
+| `documentation`   | Missing docs, stale descriptions, incorrect examples, wrong paths                   |
+
+---
+
+## Usage
+
+- When creating a lesson with the self-improvement skill, map the mistake to exactly one category
+- When searching for lessons, start with the most specific category
+- Use `context-sync` for "I assumed X but it was actually Y" mistakes
+- Use `nonexistent-api` for "I called X which doesn't exist" mistakes

package/templates/default-instance/monolith/memory/errors/README.md

@@ -0,0 +1,26 @@
+# Error Memory
+
+This directory stores failure records for this project.
+
+## Structure
+
+```
+memory/errors/
+├── SCHEMA.md       — format for ERR-*.md files
+├── TAXONOMY.md     — 8 error categories
+└── ERR-*.md        — individual error records (created at runtime)
+```
+
+## When to Create a Record
+
+Create an `ERR-*.md` file when:
+
+- A significant error occurred during implementation
+- A misunderstanding caused wrong behavior
+- A pattern of mistakes was identified
+
+## How to Create
+
+Use the `self-improvement` skill or manually create `ERR-YYYY-XXXX.md` following `SCHEMA.md`.
+
+Lessons extracted from errors live in `learning/mistakes/<category>/`.

package/templates/default-instance/monolith/memory/errors/SCHEMA.md

@@ -0,0 +1,47 @@
+---
+type: schema
+id: error-schema
+category: errors
+authority: authoritative
+---
+
+# Error Record Schema
+
+Schema for error records in `memory/errors/`.
+
+## Format
+
+Filename: `ERR-YYYY-XXXX.md` where YYYY = year, XXXX = sequential ID.
+
+## Fields
+
+```yaml
+---
+id: ERR-YYYY-XXXX
+date: YYYY-MM-DD
+category: architecture | dependencies | nonexistent-api | context-sync | workflow | typescript | documentation | other
+severity: critical | high | medium | low
+story: STORY X.Y — Story Name (optional)
+resolved: true | false
+---
+```
+
+## Body
+
+```markdown
+## Error Description
+
+What went wrong.
+
+## Root Cause
+
+Why it happened.
+
+## Resolution
+
+How it was fixed.
+
+## Prevention
+
+How to avoid in future (becomes a lesson in learning/mistakes/).
+```

package/templates/default-instance/monolith/memory/errors/TAXONOMY.md

@@ -0,0 +1,27 @@
+---
+type: reference
+id: error-taxonomy
+category: errors
+authority: authoritative
+---
+
+# Error Taxonomy
+
+8 canonical error categories for MONOLITH projects.
+
+| Category          | Description                                                    |
+| ----------------- | -------------------------------------------------------------- |
+| `architecture`    | Structural violations, wrong layer boundaries, coupling issues |
+| `dependencies`    | Missing packages, version conflicts, import errors             |
+| `nonexistent-api` | Calling functions/methods/endpoints that don't exist           |
+| `context-sync`    | Memory state out of sync with actual project state             |
+| `workflow`        | Protocol violations, skipped steps, wrong execution order      |
+| `typescript`      | Type errors, inference failures, incorrect generics            |
+| `documentation`   | Missing, stale, or incorrect documentation                     |
+| `other`           | Errors that don't fit the above categories                     |
+
+## Usage
+
+- Reference when creating `ERR-*.md` records
+- The `category` field must match one of the above exactly
+- Lessons in `learning/mistakes/` are organized by these categories

package/templates/default-instance/monolith/memory/long-term/architecture-principles.md

@@ -0,0 +1,31 @@
+---
+type: memory
+id: memory-long-term-architecture-principles
+category: long-term
+authority: authoritative
+related_protocols:
+  - memory-governance
+---
+
+# Architecture Principles
+
+Stable architectural principles for this project. Read before every implementation task.
+
+---
+
+## Principles
+
+<!-- Add your core architectural principles here. -->
+<!-- Example: "Vertical slice first. Feature complete before horizontal scale." -->
+
+---
+
+## Stack Decisions
+
+<!-- Key technology choices and the reasoning behind them. -->
+
+---
+
+## Invariants
+
+<!-- Things that must never change without an explicit ADR. -->

package/templates/default-instance/monolith/memory/long-term/decisions.md

@@ -0,0 +1,36 @@
+---
+type: memory
+id: memory-long-term-decisions
+category: long-term
+authority: authoritative
+related_protocols:
+  - memory-governance
+---
+
+# Decisions
+
+Project decisions that are **not** ADRs (`DEC-…` records). Architecture Decision Records are not listed or summarised here: if this project keeps ADRs, their only index is `docs/adr/README.md`.
+
+Updated by the finalize-story skill when a story records a decision that is not an ADR.
+
+---
+
+## Decision Template
+
+```
+### DEC-YYYY-XXXX — Decision Title
+
+**Date:** YYYY-MM-DD
+**Story:** STORY X.Y — Story Name
+**Status:** Active | Superseded | Deprecated
+
+**Context:** Why this decision was needed.
+**Decision:** What was decided.
+**Consequences:** What changes as a result.
+```
+
+---
+
+## Decisions
+
+<!-- Decisions are recorded here as stories are finalized. -->

package/templates/default-instance/monolith/memory/long-term/execution-history.md

@@ -0,0 +1,20 @@
+---
+type: memory
+id: memory-long-term-execution-history
+category: long-term
+authority: authoritative
+append_only: true
+---
+
+# Execution History
+
+Append-only log of completed story finalizations.
+
+Each entry is written by the finalize-story skill at story completion.
+
+---
+
+## History
+
+<!-- Entries are appended here. Do not edit or delete existing entries. -->
+<!-- Format: ## STORY X.Y — Story Name (YYYY-MM-DD) -->

package/templates/default-instance/monolith/memory/long-term/tech-debt.md

@@ -0,0 +1,25 @@
+---
+type: memory
+id: memory-long-term-tech-debt
+category: long-term
+authority: authoritative
+---
+
+# Technical Debt Registry
+
+Tracks intentional technical debt to prevent accidental "fixing" of accepted trade-offs.
+
+---
+
+## Open Debt
+
+| ID  | Description | Accepted | Rationale |
+| --- | ----------- | -------- | --------- |
+| —   | —           | —        | —         |
+
+---
+
+## Accepted Debt
+
+<!-- Debt that has been consciously accepted with a known trade-off. -->
+<!-- Do NOT fix accepted debt without explicitly revisiting the decision. -->

package/templates/default-instance/monolith/memory/working/active.md

@@ -0,0 +1,41 @@
+---
+type: memory
+id: memory-working-active
+category: working
+stability: volatile
+authority: authoritative
+topology_role: root
+related_protocols:
+  - memory-governance
+referenced_by:
+  - skill-finalize-story
+  - skill-current-status
+  - skill-global-status
+---
+
+# Active Working Memory
+
+## Active Phase
+
+No active phase.
+
+---
+
+## Current Story
+
+No active story.
+
+Previous: —
+
+---
+
+## Last Finalization
+
+No finalization recorded yet.
+
+---
+
+## Current Operational Focus
+
+<!-- Update this section when starting the first phase. -->
+<!-- Describe what the project is building and what is in focus now. -->