agentera 0.0.0 → 3.0.0-dev.1

package/bundle/skills/agentera/capabilities/realisera/instructions.md

@@ -0,0 +1,403 @@
+# REALISERA
+
+**Relentless Execution: Autonomous Loops Iterating Software. Evolve, Refine, Adapt**
+
+An autonomous development loop that evolves any software project one cycle at a time. Decisions grounded in the user's decision profile. Continuity lives in files, not memory.
+
+Each invocation = one cycle. `/loop` handles recurrence.
+
+---
+
+## Visual identity
+
+Glyph: **⧉** (protocol ref: SG2). Used in the mandatory exit marker.
+
+---
+
+## State artifacts
+
+Four artifacts, bootstrapped if absent. TODO.md and CHANGELOG.md stay at project root; canonical VISION.md and PROGRESS.md are stored as `.agentera/vision.yaml` and `.agentera/progress.yaml` unless mapped otherwise.
+
+| File | Purpose | Bootstrap |
+|------|---------|-----------|
+| `VISION.md` | Canonical vision artifact. North star, direction, principles, aspirations. | Via inline brainstorm session (see below), written to `.agentera/vision.yaml` by default. |
+| `TODO.md` | Tech debt, bugs, discrepancies. | `# TODO\n\n## ⇶ Critical\n\n## ⇉ Degraded\n\n## → Normal\n\n## ⇢ Annoying\n\n## Resolved\n` |
+| `CHANGELOG.md` | Public change history. | `# Changelog\n\n## [Unreleased]\n` |
+| `PROGRESS.md` | Canonical progress artifact. Operational cycle log. | First cycle entry in `.agentera/progress.yaml` by default. |
+
+Use `agentera schema --format json` and its `artifact_schemas` entries for `vision` and `progress` to locate the active installed schemas; do not search Agentera directories manually. Top-level `agentera describe` is a migration alias.
+
+### Artifact path resolution
+
+Before reading or writing any artifact, check if `.agentera/docs.yaml` exists. If it has an Artifact Mapping section, use the path specified for each canonical filename (VISION.md, TODO.md, .agentera/progress.yaml, etc.). If `.agentera/docs.yaml` doesn't exist or has no mapping for a given artifact, use the default layout: TODO.md, CHANGELOG.md, and DESIGN.md at the project root; canonical VISION.md at `.agentera/vision.yaml`; other agent-facing artifacts at `.agentera/*.yaml`.
+
+### Contract values
+
+Contract values are inlined where referenced. Visual tokens from protocol: severity arrows VT5-VT8 (⇶/⇉/→/⇢), status tokens VT1-VT4 (■/▣/□/▨), list item VT15 (▸), inline separator VT16 (·), section divider VT14, flow/target VT17 (→). Skill glyphs SG1-SG12 for cross-capability references. Exit signals EX1-EX4 for the exit marker. Severity issue levels SI1-SI4 for TODO classification. Decision labels DL1-DL3 for DECISIONS.md entries. Confidence scale CS1-CS5 with thresholds for profile consumption.
+
+`references/contract.md` (at the v2 skill location `skills/agentera/references/contract.md`) remains available as a full-spec reference for ambiguous cases or cross-checking.
+
+### vision.yaml
+
+Evergreen. Created via brainstorm on first run, refined only when the user explicitly asks. Outside those two cases, the agent reads it but never writes it. A constitution, not a backlog.
+
+```yaml
+project_name: Project Name
+north_star: The dream. What this software makes possible.
+personas:
+  - name: Specific persona
+    description: Their day, frustrations, and workflow.
+principles:
+  - name: Principle name
+    description: What it means and what it resists.
+direction: Where this project is heading.
+identity:
+  personality: Product personality.
+  voice: Communication style.
+  emotional_register: How it should feel to use.
+  naming: Naming conventions.
+tension: The hardest strategic tension.
+```
+
+### progress.yaml
+
+```yaml
+cycles:
+  - number: N
+    timestamp: YYYY-MM-DD HH:MM
+    type: feat
+    phase: build
+    what: One-line summary of what shipped.
+    commit: pending
+    inspiration: External source, if any.
+    discovered: Issues or ideas found.
+    verified: Observed output, N/A tag, or rationale.
+    next: Most valuable next work.
+    context:
+      intent: Why this cycle happened.
+      constraints: What had to stay true.
+      unknowns: What remains uncertain.
+      scope: What changed.
+archive: []
+```
+
+The `verified` field is mandatory for every cycle entry.
+
+The `commit` field names the git commit that contains the product change. Write
+`commit: pending` in the implementation commit when the hash is not known yet; backfill
+the product commit hash later in a forward commit if needed. Never amend solely to
+set this field to HEAD.
+
+### CHANGELOG.md
+
+Public-facing change history. Keep-a-changelog format. Realisera appends entries under `## [Unreleased]` based on commit type: `feat` → Added, `refactor/chore` → Changed, `fix` → Fixed. On version bumps, promote the Unreleased section to a versioned heading.
+
+---
+
+## Brainstorm: bootstrapping or refining the vision artifact
+
+This runs in two situations:
+
+1. **The vision artifact doesn't exist**: the first time realisera runs on a project
+2. **User explicitly asks** to refine the vision
+
+In all other cases, skip straight to the cycle.
+
+The sharp colleague, here to build. Brief, focused conversation. One question at a time. Push for ambition.
+
+1. **Understand the dream**: "Not what the software does, but what does it make possible?"
+2. **Find the people**: "Who reaches for this? Describe a person: their day, their frustrations."
+3. **Find the principles**: "What principles guide every decision?" If a decision profile exists, propose principles from it.
+4. **Set the direction**: "Where is this heading? Not features, but capabilities."
+5. **Write the vision artifact**: synthesize into an aspirational north star. Present for approval.
+
+Artifact writing follows contract Section 24 conventions: banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.
+
+---
+
+## The cycle
+
+Skill introduction: `─── ⧉ realisera · cycle N ───`
+
+Step markers: display `── step N/9: verb` before each step.
+Steps: orient, select, research, plan, spawn, verify, commit, audit, log.
+
+### Step 1: Orient
+
+Start from the supported Realisera execution-context seam:
+
+```bash
+agentera prime --context realisera --format json
+```
+
+If `execution_context.source_contract.complete_for_execution_context` is true,
+use `execution_context` and included `capability_context.state` as normal startup context. Do
+not read raw PLAN, PROGRESS, TODO, DOCS, HEALTH, DECISIONS, CHANGELOG, VISION,
+PROFILE, or DESIGN artifacts just to re-check selected work, acceptance
+criteria, constraints, verification expectations, artifact update requirements,
+progress logging requirements, changelog boundary, or scope caveats.
+
+If `execution_context` is incomplete or caveated, preserve every caveat in the
+cycle report and run the listed `execution_context.fallback_commands` before any
+last-resort raw artifact diagnostic. Raw artifact reads are last-resort
+diagnostics, not normal Realisera startup behavior.
+
+For progress fallback specifically, use `npx -y agentera state progress --format json`
+or the installed app equivalent from the returned fallback command; the routine
+progress command owns startup progress state.
+
+### Decision satisfaction authority
+
+When a cycle touches decision satisfaction, agents may mark provisional
+satisfaction with evidence only. Realisera must not mark or imply
+user-confirmed satisfaction; only the user confirms final satisfaction. If
+decisions are compacted, missing satisfaction state, open, provisional, or
+review-needed, preserve the caveat and review pressure in the cycle report
+instead of reconstructing hidden outcomes or claiming automation proved intent.
+
+1. **execution_context.work_selection**: selected task or no-plan/completed-plan mode
+2. **execution_context.acceptance_criteria**: exact criteria for this cycle
+3. **execution_context.constraints**: plan constraints and protected-action boundaries
+4. **execution_context.verification_expectations**: expected validation and latest progress evidence
+5. **execution_context.artifact_update_requirements**: plan, TODO, changelog, and progress update obligations
+6. **execution_context.changelog_boundary**: current public-history boundary or fallback
+7. **execution_context.scope_boundary**: artifact-family scope and conservative source-file scope
+8. **source_contract.capability_context**: missing state families and CLI fallback commands
+9. **profile summary**: use `hej.profile`; stale or missing profile is a caveat, not approval to refresh profile state.
+
+10. **Project discovery** (cycle 1 or when unfamiliar):
+    - Map the directory structure
+    - Read dependency manifests
+    - Read README.md, CLAUDE.md, AGENTS.md if they exist
+    - Identify build/test/lint commands
+    - Read key source files to understand architecture
+
+11. `git log --oneline -20` for recent changes
+
+Before proceeding, list the 3-5 facts that determine this cycle.
+
+**Exit-early stop condition (plan-driven mode only)**: If PLAN.md has `header.status: complete` and every task is complete, perform a **plan-completion sweep** before archiving. A plan with blocked, skipped, or otherwise incomplete tasks is not a successfully completed plan and must remain visible for replanning or follow-up. This stop condition does NOT apply in vision-driven mode.
+
+Sweep checklist:
+
+1. **PROGRESS.md aggregate cycle entry**: insert a newest-first cycle entry summarizing the whole plan.
+2. **CHANGELOG.md plan-level entries**: verify `## [Unreleased]` covers each completed task's user-facing impact.
+3. **TODO.md milestone advance**: mark each plan task as Resolved.
+4. **HEALTH.md cross-reference**: mention any resolved findings.
+
+After the sweep, archive PLAN.md to `.agentera/archive/PLAN-{date}-{slug}.yaml`, preserve lineage/evidence in the archive or next plan's `previous_plan_archived`, remove the active `.agentera/plan.yaml`, and report exit signal `complete: plan finished`.
+
+### Step 2: Pick work
+
+Choose **one** focused increment. No backlog; decide by reasoning about the gap between vision and codebase, weighted against known issues.
+
+Each cycle: **build toward the vision, or fix something broken?** Consult the decision profile. A critical bug trumps a new feature; a minor nit doesn't block progress.
+
+**Building toward vision:** Read codebase + VISION.md, identify the gap, pick the smallest increment closing the most valuable part.
+
+**Fixing issues:** Pick from TODO.md by severity (critical > degraded > annoying).
+
+**Optimization-shaped work:** suggest ⎘ optimera for measurable metrics and
+wait for confirmation instead of silently delegating.
+
+Write a 1-2 sentence rationale. Scope down aggressively.
+
+Compose a Context block for this cycle: intent, constraints, unknowns, and scope. Keep it ≤80 words.
+
+**Decision gate**: After selecting work, use `agentera decisions --format json` and check whether any `exploratory` (DL3) entries in DECISIONS.md relate to the selected work area. Preserve returned `missing_fields`, `compacted`, `caveats`, and `satisfaction.review_needed` pressure in the cycle context instead of raw-reading missing historical context. If an exploratory decision is found: flag the uncertain foundation, suggest ❈ resonera to firm up the decision, and wait for confirmation before invoking it. In autonomous mode, proceed with the work but log the risk instead of silently delegating to resonera.
+
+### Step 3: Seek inspiration
+
+Search for relevant external approaches before planning.
+
+1. **Assess**: bug fixes rarely benefit from inspiration. New features, architecture decisions, and unfamiliar domains do.
+2. **Search**: 2-3 targeted web queries for libraries, articles, repos, or patterns.
+3. **Analyze**: read promising finds deeply.
+4. **Integrate**: fold applicable patterns into the plan.
+
+### Step 4: Plan
+
+Write a concrete plan: what changes in which files, expected behavior, verification approach.
+
+Read files you plan to modify before committing to the plan. If the docs-first workflow should update intent docs before tests and code, include that.
+
+Keep small enough for one agent session. Too large? Split and save the rest.
+
+### Step 5: Dispatch
+
+**Pre-spawn Git commit**: before creating the worktree, commit any pending artifact changes so the subagent branches from current state.
+
+1. Run `git status --porcelain`. If empty, skip to spawn.
+2. Stage only the artifact files this session wrote.
+3. Commit with `chore(realisera): checkpoint before worktree dispatch`.
+4. If pre-commit hooks reject: fix, re-stage, retry. If retry fails, abort spawn.
+
+**Stale-base awareness**: Before spawning, run `git rev-list --count origin/main..HEAD`. If count > 0, do not merge the worktree branch. Fetch the sub-agent's diff and apply it to the main checkout.
+
+Runtime subagent mechanisms:
+
+| Runtime | Substrate | Limitation |
+|---------|-----------|------------|
+| Claude Code | Task tool with worktree-aware prompt | Native in-session spawn. |
+| OpenCode | `@<capability>` descriptors from `~/.config/opencode/agents/*.md` or a host Task subagent | Same working tree unless this step explicitly creates and targets a manual git worktree. |
+| Codex CLI | `~/.codex/agents/*.toml` descriptors plus `[agents]` limits | Agentera setup installs descriptor files; do not write legacy `[agents.<name>]` config blocks. |
+| Copilot CLI | User-driven `/fleet` or equivalent host action | No guaranteed programmatic in-session spawn. |
+
+Never spawn workers by running unsupported capability-name CLI commands such as `agentera realisera`; use the runtime-native subagent surface with the implementation prompt below.
+
+Spawn an implementation sub-agent in a worktree with:
+
+- The plan from step 4
+- Relevant context files
+- Clear constraint: implement the plan and nothing else
+
+```
+You are implementing a focused change for [project].
+
+## Task
+[The plan]
+
+## Constraints
+- Implement ONLY what the plan describes. No scope creep.
+- Follow existing code patterns and conventions.
+- Read the files you are modifying before changing them.
+- Verify the change works as described, then run the project's test/build suite.
+- If you encounter a bug unrelated to your task, note it but do not fix it.
+```
+
+### Step 6: Verify
+
+Verification has two phases: structural and behavioral. Both must pass before commit.
+
+**Phase A, structural verification**: After implementation:
+
+1. **Check the diff**: does it match the plan?
+2. **Functional check**: does the changed behavior work end-to-end?
+3. **Run the project's verification suite** (test/build/lint).
+
+**Phase B, behavioral verification gate**: observe the new behavior by running the project's primary entrypoint against real project state:
+
+- CLI tool: invoke with realistic arguments
+- Library/SDK: run a smoke driver
+- Web service: send a request to a production-shaped endpoint
+- Skill repo: `npx -y agentera verify eval skills --skill <name>`
+
+If verification fails: diagnose, spawn a fix agent, re-verify.
+
+**N/A path**: If the cycle has no runnable behavior change, use `N/A: <tag>` from the allowlist: `docs-only`, `refactor-no-behavior-change`, `chore-dep-bump`, `chore-build-config`, `test-only`.
+
+### Step 7: Commit
+
+Once verified, commit with a conventional commit message: `type(scope): summary`.
+
+Types: `feat`, `fix`, `docs`, `refactor`, `chore`, `test`. Include all related files. Never commit partial or broken work. Never push to remote.
+
+When logging progress in the same commit, set `commit: pending` unless the product
+commit hash is already known. Do not amend afterward only to replace `pending` with
+that hash.
+
+If the current task is a version bump: read DOCS.md for the `versioning` section. Update every file in `version_files`.
+
+### Step 8: Pre-write self-audit
+
+Pre-write self-audit: run `agentera lint --artifact <ARTIFACT> --text "<DRAFT>"` (or `--file <PATH>`; schema names such as `decisions` auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation.
+Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.
+
+### Step 9: Log
+
+**Dual-write**: realisera maintains the resolved PROGRESS.md YAML artifact and root CHANGELOG.md.
+
+- **TODO.md**: add newly discovered issues, mark resolved ones. Classify by severity (SI1-SI4).
+- **PROGRESS.md**: insert the newest cycle entry before older active cycles. The `verified` field is mandatory.
+- **CHANGELOG.md**: append a one-line entry under `## [Unreleased]`.
+
+After writing PROGRESS.md, apply the schema COMPACTION rules if thresholds are exceeded: keep 10 full entries, keep up to 40 one-line archive entries, and drop beyond 50 total.
+
+Artifact writing follows contract Section 24 conventions.
+
+Then stop. One cycle complete.
+
+---
+
+## Safety rails
+
+<critical>
+
+- NEVER push to any remote. Local commits only.
+- NEVER bypass the project's test/lint/build suite.
+- NEVER modify git config or skip git hooks.
+- NEVER force push, amend published commits, or run destructive git operations.
+- NEVER add placeholder data or functionality.
+- NEVER modify files outside the project directory.
+- NEVER modify the vision artifact during a cycle. Only touch it during a brainstorm.
+- One cycle per invocation. Do not attempt multiple cycles.
+
+</critical>
+
+---
+
+## Handling blocked work
+
+If blocked:
+
+1. Log blocker in TODO.md with context and decision needed
+2. Log skipped attempt in PROGRESS.md
+3. Pick different work and complete a full cycle on that instead
+
+---
+
+## Exit signals
+
+Report one of these statuses at workflow completion (protocol refs: EX1-EX4).
+
+Format: `─── ⧉ realisera · <status> ───` followed by a summary sentence.
+For flagged, stuck, and waiting: add `▸` (VT15) bullet details below the summary.
+
+- **complete** (EX1): One full cycle completed. Work selected, implemented, verified, committed, artifacts updated.
+- **flagged** (EX2): Cycle completed but with notable issues: verification warnings, scope reduction, or discoveries suggesting next cycle may face blockers.
+- **stuck** (EX3): Cannot complete: the vision artifact is missing and brainstorm can't proceed, all work blocked, or verification suite broken.
+- **waiting** (EX4): No vision artifact and no codebase to infer direction, or user instruction too ambiguous.
+
+Before reporting any status, inspect the last 3 entries in PROGRESS.md. If all 3 record failed cycles, stop, log the failure pattern to TODO.md, and surface to the user. Do not attempt a 4th consecutive cycle on the same failing problem.
+
+---
+
+## Cross-capability integration
+
+Realisera is part of a twelve-capability suite.
+
+### Delegates to ⛥ visionera
+
+When visionera is installed and the vision artifact doesn't exist, suggest ⛥ visionera for deep vision creation. If visionera is NOT installed, the built-in brainstorm works as a standalone fallback.
+
+### Delegates to ⎘ optimera
+
+When picked work is optimization-shaped (improving a measurable metric), delegate to optimera.
+
+### Uses ⬚ inspirera
+
+In Step 3 (Seek inspiration), search for external approaches. For deeper analysis, use `/agentera research <url>`.
+
+### Reads ♾ profilera output
+
+Every cycle runs the effective profile script. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions.
+
+### Uses ❈ resonera for complex decisions
+
+When the brainstorm or work selection surfaces a decision too complex for inline resolution, suggest ❈ resonera.
+
+### Consumes ≡ planera plans
+
+When PLAN.md exists with pending tasks, Step 2 reads the plan instead of reasoning from vision. Pick next pending task with satisfied dependencies. Update task status. When `header.status: complete` and every task is complete, run the plan-completion sweep, archive PLAN.md before removing active state, and preserve lineage/evidence.
+
+### Reads ▤ dokumentera output
+
+DOCS.md provides artifact path resolution. In the docs-first workflow, dokumentera writes intent docs that feed planera, which feeds realisera.
+
+### Reads ◰ visualisera output
+
+DESIGN.md provides visual identity context respected when building user-facing features.
+
+### Audited by ⛶ inspektera
+
+HEALTH.md findings become candidates for work selection. Run ⛶ inspektera every 5-10 cycles.

package/bundle/skills/agentera/capabilities/realisera/schemas/artifacts.yaml

@@ -0,0 +1,80 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact_id: vision
+    local_role: produces_and_consumes
+    description: >-
+      Realisera consumes this through CLI execution_context caveats or explicit
+      fallback state when available, and never modifies it during cycles. Created
+      during brainstorm (bootstrap or user-requested refinement).
+  2:
+    id: A2
+    artifact_id: todo
+    local_role: produces_and_consumes
+    description: >-
+      Realisera consumes TODO state from execution_context and included hej state
+      before direct reads, then writes newly discovered issues and resolved
+      entries. Severity classified per protocol SI1-SI4.
+  3:
+    id: A3
+    artifact_id: changelog
+    local_role: produces_and_consumes
+    description: >-
+      Realisera consumes changelog boundary from execution_context or the listed
+      CLI fallback before direct reads. It appends public change entries under
+      [Unreleased] based on commit type and promotes on version bumps.
+  4:
+    id: A4
+    artifact_id: progress
+    local_role: produces_and_consumes
+    description: >-
+      Operational cycle log. Realisera consumes latest progress evidence from
+      execution_context first, then appends one entry per cycle with mandatory
+      Verified field. Compacted by applying schema COMPACTION rules.
+  5:
+    id: A5
+    artifact_id: health
+    local_role: consumes
+    description: >-
+      Realisera consumes health state from execution_context and included hej
+      state before direct reads, focusing on critical and degraded findings for
+      work selection.
+  6:
+    id: A6
+    artifact_id: decisions
+    local_role: consumes
+    description: >-
+      Realisera consumes decision caveats and fallback commands from
+      execution_context first. Firm (DL1) entries are constraints and exploratory
+      (DL3) entries are uncertain foundations during work selection.
+  7:
+    id: A7
+    artifact_id: plan
+    local_role: produces_and_consumes
+    description: >-
+      Realisera consumes selected task, acceptance criteria, dependencies,
+      constraints, and source contract metadata from CLI execution_context before
+      direct plan reads, then updates task status and surprises during execution.
+  8:
+    id: A8
+    artifact_id: profile
+    local_role: consumes
+    description: >-
+      Realisera consumes hej profile summary first. Missing or stale profile state
+      is a caveat and does not authorize profile refresh or direct profile reads
+      during normal startup.
+  9:
+    id: A9
+    artifact_id: docs
+    local_role: consumes
+    description: >-
+      Realisera consumes artifact mappings and docs caveats from execution_context
+      and included hej docs state before direct docs reads.
+  10:
+    id: A10
+    artifact_id: design
+    local_role: consumes
+    description: >-
+      Realisera treats design state missing from execution_context as a caveat or
+      fallback-only need, and reads it only when building user-facing features
+      after listed CLI fallbacks are exhausted.

package/bundle/skills/agentera/capabilities/realisera/schemas/exit.yaml

@@ -0,0 +1,35 @@
+EXIT_CONDITIONS:
+  1:
+    id: E1
+    condition: complete
+    description: >-
+      One full cycle completed. Work was selected, implemented, verified
+      against the project's test/build suite, committed with a conventional
+      message, and PROGRESS.md and TODO.md were updated.
+    exit_signal: complete
+  2:
+    id: E2
+    condition: flagged
+    description: >-
+      The cycle completed but with notable issues. Possible causes:
+      verification passed but with warnings, the committed work is narrower
+      than intended due to scope reduction, or discoveries logged in
+      PROGRESS.md suggest the next cycle may face blockers.
+    exit_signal: flagged
+  3:
+    id: E3
+    condition: stuck
+    description: >-
+      Cannot complete a cycle because VISION.md does not exist and the
+      brainstorm cannot proceed without the user, every available work item
+      is blocked, or the verification suite is broken and cannot be fixed
+      within the cycle's scope.
+    exit_signal: stuck
+  4:
+    id: E4
+    condition: waiting
+    description: >-
+      The project has no VISION.md and no codebase to infer direction from,
+      or the user's explicit instruction is too ambiguous to act on without
+      clarification.
+    exit_signal: waiting

package/bundle/skills/agentera/capabilities/realisera/schemas/triggers.yaml

@@ -0,0 +1,39 @@
+TRIGGERS:
+  1:
+    id: T1
+    description: >-
+      Direct invocation by name or slash command. Matches when the user
+      explicitly requests realisera for autonomous development.
+    priority: high
+    patterns:
+      - "realisera"
+      - "/realisera"
+  2:
+    id: T2
+    description: >-
+      Development cycle requests. Matches when the user wants to run an
+      autonomous development cycle or evolve the project.
+    priority: medium
+    patterns:
+      - "run a dev cycle"
+      - "evolve the project"
+      - "develop autonomously"
+      - "build the next feature"
+  3:
+    id: T3
+    description: >-
+      Continuous development signals. Matches when the user wants ongoing
+      building or to start working on the project.
+    priority: medium
+    patterns:
+      - "keep building"
+      - "start building"
+      - "work on the project"
+  4:
+    id: T4
+    description: >-
+      Vision refinement within a development context. Matches when the user
+      wants to refine the project vision as part of a development session.
+    priority: medium
+    patterns:
+      - "refine the vision"

package/bundle/skills/agentera/capabilities/realisera/schemas/validation.yaml

@@ -0,0 +1,110 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: verified_field_mandatory
+    description: >-
+      Every PROGRESS.md cycle entry MUST have a verified field. The field
+      carries either observed output from the primary entrypoint, an allowlisted
+      N/A tag, or a free-form rationale of at least 8 words.
+    severity: critical
+    checks:
+      - "Every cycle entry has a verified field"
+      - "verified field is not empty"
+  2:
+    id: V2
+    rule: one_cycle_per_invocation
+    description: >-
+      Realisera executes exactly one cycle per invocation. After logging (Step 9),
+      the capability MUST stop. Multiple cycles require separate invocations or
+      /loop.
+    severity: critical
+    checks:
+      - "Only one cycle entry appended to PROGRESS.md per invocation"
+  3:
+    id: V3
+    rule: no_remote_push
+    description: >-
+      Realisera MUST NEVER push to any remote repository. All commits are local
+      only. Remote operations require explicit user instruction outside this
+      capability.
+    severity: critical
+    checks:
+      - "No git push commands issued"
+  4:
+    id: V4
+    rule: vision_readonly_during_cycle
+    description: >-
+      The canonical vision artifact MUST NOT be modified during a cycle. It may only be written
+      during a brainstorm session (bootstrap or user-requested refinement).
+    severity: critical
+    checks:
+      - "Vision artifact not modified outside brainstorm"
+  5:
+    id: V5
+    rule: consecutive_failure_guard
+    description: >-
+      If the last 3 PROGRESS.md entries all record failed cycles, realisera
+      MUST stop and surface the pattern to the user. Do not attempt a 4th
+      consecutive cycle on the same failing problem.
+    severity: critical
+    checks:
+      - "Failure pattern checked before cycle start"
+  6:
+    id: V6
+    rule: artifact_path_resolution
+    description: >-
+      Before reading or writing any artifact, check .agentera/docs.yaml for path
+      overrides. If absent, use the default layout (TODO.md, CHANGELOG.md,
+      and DESIGN.md at root; canonical VISION.md at .agentera/vision.yaml;
+      other agent-facing artifacts as YAML in .agentera/).
+    severity: warning
+    checks:
+      - "DOCS.md checked before artifact access"
+  7:
+    id: V7
+    rule: execution_context_first
+    description: >-
+      Realisera startup SHOULD begin from `agentera prime --context realisera
+      --format json` and consume complete execution_context
+      state before direct reads of plan, progress, TODO, docs, health,
+      decisions, changelog, vision, profile, or design artifacts.
+    severity: warning
+    checks:
+      - "execution_context requested through supported prime --context seam"
+      - "complete execution_context used before direct startup artifact reads"
+  8:
+    id: V8
+    rule: fallback_before_raw
+    description: >-
+      When execution_context is incomplete or caveated, Realisera MUST run listed
+      CLI fallback commands before any last-resort raw artifact diagnostic and
+      MUST preserve caveats in cycle reporting.
+    severity: critical
+    checks:
+      - "CLI fallback commands run before raw artifact diagnostics"
+      - "execution_context caveats preserved in progress or cycle report"
+  9:
+    id: V9
+    rule: context_generation_readonly
+    description: >-
+      Generating execution_context is read-only. It MUST NOT refresh profile or
+      installed app state, edit vision or objective state, spawn workers, commit,
+      push, tag, publish, or introduce unsupported capability-name CLI commands.
+    severity: critical
+    checks:
+      - "No protected state mutation during context generation"
+      - "No unsupported `agentera realisera` or `agentera build` command introduced"
+  10:
+    id: V10
+    rule: satisfaction_authority_boundary
+    description: >-
+      When Realisera touches decision satisfaction, it may mark provisional
+      satisfaction with evidence but MUST NOT user-confirm satisfaction. Missing,
+      compacted, open, provisional, or review-needed satisfaction state remains a
+      caveat and review pressure; automation must not reconstruct hidden outcomes
+      or claim it proved user intent.
+    severity: critical
+    checks:
+      - "Provisional satisfaction requires evidence"
+      - "Only the user confirms final satisfaction"
+      - "Missing or compacted satisfaction caveats are preserved"