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

package/templates/default-instance/monolith/memory/working/story-index.md

@@ -0,0 +1,28 @@
+---
+type: memory
+id: memory-working-story-index
+category: working
+topology_role: root
+authority: authoritative
+related_protocols:
+  - memory-governance
+---
+
+# Story Index
+
+## Purpose
+
+Fast navigation index for implementation history.
+
+Use this when you need to know:
+
+- where a feature was implemented
+- which story changed a module
+- why a decision was made
+
+---
+
+# Stories
+
+<!-- Stories are added here as they are finalized via the finalize-story skill. -->
+<!-- Format: ## Phase N — Phase Name / ### STORY X.Y — Story Name -->

package/templates/default-instance/monolith/protocols/boot/boot-sequence.md

@@ -0,0 +1,59 @@
+---
+type: protocol
+id: protocol-boot-sequence
+category: governance
+scope: system
+enforcement: mandatory
+applies_to:
+  - all
+topology_role: node
+---
+
+# AI Assistant Boot Sequence
+
+Required context recovery order for any AI assistant entering this repository.
+
+Follow this sequence STRICTLY.
+
+---
+
+# Fast Recovery Mode (Preferred)
+
+For quick session recovery, read in order:
+
+1. `AGENTS.md`
+2. `{{MONOLITH_ROOT}}/context/maps/project-map.md`
+3. `{{MONOLITH_ROOT}}/context/maps/routing-map.md` — classify task type
+4. `{{MONOLITH_ROOT}}/memory/working/active.md`
+5. `{{MONOLITH_ROOT}}/context/maps/roadmap-index.md`
+6. `{{MONOLITH_ROOT}}/protocols/governance/memory-governance.md`
+7. Relevant skill from `{{MONOLITH_ROOT}}/skills/` (resolved via routing-map Table 2)
+8. `{{MONOLITH_ROOT}}/learning/injection-map.md` — load relevant lesson categories
+9. `{{MONOLITH_ROOT}}/protocols/cognition/cognitive-modes.md` — apply behavioral constraints
+
+---
+
+# Full Recovery Mode
+
+When context is lost or session is starting cold:
+
+1. Read AGENTS.md
+2. Read `{{MONOLITH_ROOT}}/context/maps/project-map.md`
+3. Read `{{MONOLITH_ROOT}}/context/maps/routing-map.md`
+4. Read `{{MONOLITH_ROOT}}/memory/working/active.md`
+5. Read `{{MONOLITH_ROOT}}/context/maps/roadmap-index.md`
+6. Read `{{MONOLITH_ROOT}}/context/boot/HANDOFF.md` — session transfer
+7. Read `{{MONOLITH_ROOT}}/context/execution/current-state.md`
+8. Read `{{MONOLITH_ROOT}}/protocols/governance/memory-governance.md`
+9. Read `{{MONOLITH_ROOT}}/protocols/governance/core-invariants.md`
+10. Load skill from `{{MONOLITH_ROOT}}/skills/` per routing-map
+11. Load learning lessons per `{{MONOLITH_ROOT}}/learning/injection-map.md`
+12. Apply `{{MONOLITH_ROOT}}/protocols/cognition/cognitive-modes.md`
+
+---
+
+# Rules
+
+- Do NOT start any task before completing the boot sequence.
+- Do NOT skip steps 3, 4, 8, 9 under any circumstances.
+- One story at a time. Verify active.md before accepting new work.

package/templates/default-instance/monolith/protocols/cognition/cognitive-modes.md

@@ -0,0 +1,90 @@
+---
+type: protocol
+id: protocol-cognitive-modes
+category: governance
+scope: system
+enforcement: mandatory
+applies_to:
+  - all
+topology_role: node
+---
+
+# Cognitive Modes Protocol
+
+7 named modes that govern AI behavioral posture.
+
+---
+
+## Core Principle
+
+Every task begins with a declared cognitive mode. The mode defines what is allowed, what is forbidden, and what mutations are permitted.
+
+---
+
+### exploration
+
+**Activation triggers:** exploration-request, status-check, global-overview, ambiguous task
+
+**Allowed:** read files, ask clarifying questions, summarize, map relationships  
+**Forbidden:** write code, modify files, create new files, make decisions  
+**Mutations:** none
+
+---
+
+### planning
+
+**Activation triggers:** planning-request, architecture-review when no code change yet
+
+**Allowed:** read files, create plan documents in context/templates/, propose approaches  
+**Forbidden:** implement without user approval, modify source code  
+**Mutations:** context/templates/ only
+
+---
+
+### implementation
+
+**Activation triggers:** implementation-task, new-feature, documentation-update
+
+**Allowed:** read and write source files, create tests, update memory  
+**Forbidden:** autonomous capability expansion, hidden state, silent semantic degradation  
+**Mutations:** source files, tests, memory/working/
+
+---
+
+### debugging
+
+**Activation triggers:** bug-investigation
+
+**Allowed:** read all files, add diagnostic logging, propose and apply fixes  
+**Forbidden:** refactor unrelated code while debugging, change architecture without user approval  
+**Mutations:** source files (targeted fixes only)
+
+---
+
+### review
+
+**Activation triggers:** code-review, architecture-review
+
+**Allowed:** read all files, write review comments, propose changes  
+**Forbidden:** apply changes without user approval  
+**Mutations:** none (propose only)
+
+---
+
+### finalization
+
+**Activation triggers:** finalize-story, story-transition
+
+**Allowed:** verify integrity, update memory, write capsule, update execution-history  
+**Forbidden:** add new features, modify source code logic  
+**Mutations:** memory/ only (working and long-term)
+
+---
+
+### reflection
+
+**Activation triggers:** self-improvement, learning-update
+
+**Allowed:** read error records, extract lessons, write to learning/mistakes/  
+**Forbidden:** modify source code, apply fixes (that's debugging mode)  
+**Mutations:** learning/mistakes/ only

package/templates/default-instance/monolith/protocols/cognition/dry-run.md

@@ -0,0 +1,56 @@
+---
+type: protocol
+id: protocol-dry-run
+category: cognition
+scope: system
+enforcement: conditional
+---
+
+# Cognitive Dry-Run Protocol
+
+When to activate dry-run mode and how to execute it.
+
+---
+
+## Activation
+
+Activate dry-run when:
+
+- Task involves irreversible operations (delete, deploy, drop database)
+- Task scope is unclear
+- Task may affect shared/production systems
+- User explicitly requests dry-run
+
+---
+
+## Severity Levels
+
+| Level      | Description                          | Action                    |
+| ---------- | ------------------------------------ | ------------------------- |
+| `safe`     | Read-only or easily reversible       | Proceed                   |
+| `caution`  | Reversible but significant           | Confirm with user         |
+| `warning`  | Hard to reverse                      | Show dry-run output first |
+| `critical` | Irreversible or production-affecting | Require explicit approval |
+
+---
+
+## Dry-Run Format
+
+```
+DRY RUN — What would happen:
+
+1. [ACTION] file.ts — description of change
+2. [CREATE] new-file.ts — what would be created
+3. [DELETE] old-file.ts — what would be deleted
+
+Severity: warning
+Proceed? (yes / no)
+```
+
+---
+
+## Rules
+
+- Never execute critical operations without dry-run first
+- Never skip dry-run because "it's obvious"
+- Dry-run output must list ALL side effects

package/templates/default-instance/monolith/protocols/cognition/execution-trace-format.md

@@ -0,0 +1,52 @@
+---
+type: protocol
+id: protocol-execution-trace-format
+category: cognition
+scope: system
+enforcement: mandatory
+---
+
+# Execution Trace Format
+
+Standard format for execution traces written to `memory/execution/traces/`.
+
+---
+
+## File Naming
+
+`YYYYMMDD-HHMMSS-<story-id>-<phase>.json`
+
+---
+
+## Schema
+
+```json
+{
+  "traceId": "uuid",
+  "timestamp": "ISO 8601",
+  "protocolId": "finalize-story",
+  "storyId": "story-1-1-name",
+  "phaseId": "phase-1-name",
+  "steps": [
+    {
+      "stepId": "step-1",
+      "description": "What was done",
+      "status": "PASS | FAIL | WARN | SKIP",
+      "duration_ms": 0,
+      "output": "optional output summary"
+    }
+  ],
+  "result": {
+    "status": "PASS | FAIL | WARN",
+    "summary": "One-line summary"
+  }
+}
+```
+
+---
+
+## Rules
+
+- Traces are append-only — never modify existing trace files
+- One trace per protocol execution
+- Failed traces must include error details in the step output

package/templates/default-instance/monolith/protocols/cognition/semantic-planning.md

@@ -0,0 +1,51 @@
+---
+type: protocol
+id: protocol-semantic-planning
+category: cognition
+scope: planning
+enforcement: mandatory
+applies_to:
+  - planning-request
+  - architecture-review
+---
+
+# Semantic Planning Protocol
+
+How to conduct planning tasks in MONOLITH.
+
+---
+
+## When to Activate
+
+- Task type is `planning-request`
+- A new story requires upfront design
+- Architecture review before implementation
+
+---
+
+## Steps
+
+1. **Read context** — Read routing-map, active.md, roadmap-index
+2. **Clarify objective** — One sentence: what does this plan achieve?
+3. **Identify constraints** — What must NOT change?
+4. **Propose approach** — 3-5 numbered steps, each actionable
+5. **List affected files** — Specific paths, not "the codebase"
+6. **Surface risks** — What could go wrong?
+7. **Define done** — Measurable completion criteria
+8. **Get user approval** — Do NOT implement without explicit "proceed"
+
+---
+
+## Output
+
+Use `context/templates/plan-template.md` as the document format.
+
+Store plan in `context/templates/` with a descriptive filename.
+
+---
+
+## Rules
+
+- No implementation during planning mode
+- Plans must be approved before any file is modified
+- If scope changes during planning, restart from step 2

package/templates/default-instance/monolith/protocols/execution/hybrid-execution.md

@@ -0,0 +1,37 @@
+---
+type: protocol
+id: protocol-hybrid-execution
+category: execution
+scope: system
+enforcement: mandatory
+---
+
+# Hybrid Execution Protocol
+
+Governance for hybrid local/cloud AI execution model.
+
+---
+
+## Model Tiers
+
+| Tier            | When                                | Model                    |
+| --------------- | ----------------------------------- | ------------------------ |
+| cloud (default) | Public/internal data, general tasks | Default AI tool          |
+| local           | Sensitive/restricted data           | Local LLM (if available) |
+
+---
+
+## Routing Decision
+
+1. Classify context data using `context/models/privacy-classification.md`
+2. If any data is `sensitive` or `restricted` → switch to local tier
+3. If local model unavailable → pause and alert user
+4. If data is `public` or `internal` → use default cloud model
+
+---
+
+## Rules
+
+- Never send `sensitive` or `restricted` data to cloud models
+- Always check privacy classification before starting a task with external data
+- If in doubt, ask user to classify before proceeding

package/templates/default-instance/monolith/protocols/execution/local-llm-governance.md

@@ -0,0 +1,42 @@
+---
+type: protocol
+id: protocol-local-llm-governance
+category: execution
+scope: system
+enforcement: conditional
+---
+
+# Local LLM Governance
+
+Rules for AI operations using local LLM models.
+
+---
+
+## When Local Model is Required
+
+- Context contains `sensitive` or `restricted` data (per privacy-classification.md)
+- User explicitly requests local execution
+- Compliance requirements mandate on-premise processing
+
+---
+
+## Rules
+
+1. **Capability check** — Verify local model is available before routing
+2. **Fallback** — If local model unavailable: pause task, alert user, do not fall back to cloud for sensitive data
+3. **Quality gate** — Local models may have lower capability; flag to user if confidence is low
+4. **Audit** — Log all local model executions in execution traces
+
+---
+
+## Local Model Setup
+
+Configure local model path in `monolith.config.json`:
+
+```json
+{
+  "models": {
+    "local": "ollama://llama3.2"
+  }
+}
+```

package/templates/default-instance/monolith/protocols/governance/command-policy.md

@@ -0,0 +1,51 @@
+---
+type: protocol
+id: protocol-command-policy
+category: governance
+scope: system
+enforcement: mandatory
+---
+
+# Command Policy
+
+What commands the AI assistant may execute without confirmation, with confirmation, and never.
+
+---
+
+## Execute Without Confirmation
+
+- `git status`, `git log`, `git diff` (read-only)
+- `cat`, `ls`, `find`, `grep` (read-only)
+- Build commands: `tsc`, `pnpm build`, `npm run build`
+- Lint: `eslint`, `prettier`
+- Test: `pnpm test`, `npm test`
+
+---
+
+## Execute With User Confirmation
+
+- `git commit`, `git push`
+- `git reset`, `git checkout`
+- File creation in source directories
+- `npm install`, `pnpm add`
+- Any command that modifies shared state
+
+---
+
+## Never Execute Without Explicit Instruction
+
+- `rm -rf`, `git clean -f`, `git reset --hard`
+- Database migrations on production
+- Deploy to production
+- Publish to npm
+- Delete branches
+- Force push
+
+---
+
+## Rules
+
+1. When in doubt: ask, don't act
+2. Destructive operations: always show dry-run first
+3. Production-affecting operations: require explicit written confirmation
+4. Never bypass safety hooks (--no-verify, --force) without explicit instruction

package/templates/default-instance/monolith/protocols/governance/core-invariants.md

@@ -0,0 +1,40 @@
+---
+type: protocol
+id: protocol-core-invariants
+category: governance
+scope: system
+enforcement: mandatory
+trigger: always_on
+applies_to:
+  - all
+---
+
+# Core Invariants
+
+Always-on operational invariants. Applied to every task regardless of cognitive mode.
+
+---
+
+## Universal Invariants
+
+These never change.
+
+1. **One story at a time** — Never start a new story without finishing or explicitly pausing the current one.
+2. **Vertical slice first** — Implement features end-to-end before expanding scope.
+3. **No autonomous capability expansion** — Never add features not explicitly requested.
+4. **No hidden state** — Every decision and state change must be visible and documented.
+5. **Memory before code** — Read active.md before writing any code.
+6. **Integrity before report** — Run integrity verification before claiming a story done.
+7. **No silent semantic degradation** — If meaning changes, make it explicit.
+
+---
+
+## Current Product Focus
+
+<!-- Add project-specific invariants and current focus here. -->
+<!-- This section is filled by the user after init. -->
+
+<!-- Example: -->
+<!-- - We are building a data pipeline MVP. No UI work until pipeline is stable. -->
+<!-- - TypeScript strict mode everywhere. No `any` without justification. -->
+<!-- - All new endpoints must have integration tests. -->

package/templates/default-instance/monolith/protocols/governance/memory-governance.md

@@ -0,0 +1,54 @@
+---
+type: protocol
+id: protocol-memory-governance
+category: governance
+scope: system
+enforcement: mandatory
+applies_to:
+  - memory
+  - stories
+  - skills
+topology_role: node
+---
+
+# Memory Governance
+
+Rules for creating, updating, migrating, and deprecating memory.
+
+---
+
+## Core Rules
+
+### 1. Avoid Monolithic Context Files
+
+Do not expand a single large file indefinitely. Prefer:
+
+- phase memory (per-phase capsules)
+- story capsules (per-story records)
+- indexed references (pointers, not content duplication)
+- modular memory (separate files per domain)
+
+### 2. Separate Stable vs Volatile Memory
+
+| Type                 | Location             | Update Frequency        |
+| -------------------- | -------------------- | ----------------------- |
+| Volatile (per-story) | `memory/working/`    | Every story             |
+| Stable (cross-story) | `memory/long-term/`  | On significant decision |
+| Error records        | `memory/errors/`     | On failure              |
+| Lessons              | `learning/mistakes/` | On self-improvement     |
+
+### 3. Single Source of Truth
+
+Each fact has exactly one authoritative location. Reference, don't duplicate.
+
+### 4. Append-Only History
+
+`memory/long-term/execution-history.md` is append-only. Never edit past entries.
+
+### 5. Story Context Required
+
+All `memory/working/` updates must reference the active story ID.
+
+### 6. Integrity Before Report
+
+`memory/working/integrity-result.md` must be updated before finalizing a story.

package/templates/default-instance/monolith/protocols/governance/metadata-schema.md

@@ -0,0 +1,62 @@
+---
+type: protocol
+id: protocol-metadata-schema
+category: governance
+scope: system
+enforcement: mandatory
+---
+
+# Metadata Schema
+
+YAML frontmatter schema for all MONOLITH artifacts.
+
+---
+
+## Required Fields
+
+```yaml
+---
+type: memory | context | protocol | skill | schema | reference | template
+id: unique-kebab-case-id
+---
+```
+
+---
+
+## Optional Fields
+
+```yaml
+---
+category: working | long-term | errors | execution | boot | governance | cognition
+stability: volatile | stable | permanent
+authority: authoritative | derived | reference
+topology_role: root | node | leaf
+enforcement: mandatory | conditional | optional
+scope: system | project | story
+applies_to:
+  - task-type-or-all
+related_protocols:
+  - protocol-id
+referenced_by:
+  - artifact-id
+append_only: true | false
+---
+```
+
+---
+
+## topology_role Values
+
+| Value  | Meaning                                      |
+| ------ | -------------------------------------------- |
+| `root` | Entry point; must exist; read at boot        |
+| `node` | Internal; referenced by roots or other nodes |
+| `leaf` | Terminal; not referenced by others           |
+
+---
+
+## Rules
+
+- Every artifact must have `type` and `id`
+- `id` must be unique across the instance
+- `topology_role: root` artifacts are verified by the topology validator

package/templates/default-instance/monolith/protocols/governance/skills.md

@@ -0,0 +1,53 @@
+---
+type: protocol
+id: protocol-skills-governance
+category: governance
+scope: system
+enforcement: mandatory
+---
+
+# Skills Governance
+
+Rules for AI skills — what they can do and what they cannot.
+
+---
+
+## What a Skill Is
+
+A skill is a declarative procedure file that defines:
+
+- when it activates (trigger)
+- what it does (steps)
+- what it produces (outputs)
+- what it must verify (checks)
+
+A skill does NOT contain runtime code. It is a specification read by the AI.
+
+---
+
+## Skill Rules
+
+1. **Atomic** — A skill runs to completion or not at all. No partial execution.
+2. **Idempotent** — Running a skill twice must not corrupt state.
+3. **Single story** — Skills operate on the active story only.
+4. **Memory first** — Read `memory/working/active.md` before starting any skill.
+5. **Verification required** — Skills that modify memory must verify their output.
+
+---
+
+## Skill Boundaries
+
+| Allowed                        | Forbidden                                         |
+| ------------------------------ | ------------------------------------------------- |
+| Read any file                  | Delete files outside memory/                      |
+| Write to memory/               | Modify source code (except implementation skills) |
+| Create context/templates/      | Push to remote repositories                       |
+| Call other skills as sub-steps | Call skills recursively                           |
+
+---
+
+## Adding a Skill
+
+1. Create `skills/<name>/SKILL.md`
+2. Add entry to `skills/INDEX.md`
+3. Add routing entry in `context/maps/routing-map.md` Table 2