agentera 3.0.0-dev.3 → 3.0.0-dev.5

package/bundle/skills/agentera/SKILL.md

@@ -1,14 +1,28 @@
 ---
 name: agentera
 description: >
-  The open protocol for turning AI agents into engineering teams.
-  One Agentera skill with twelve capabilities, each defined by human-readable
-  prose and machine-readable schemas. The agent reads this file to route
-  incoming requests to the right capability. Use this skill for /agentera,
-  Agentera capability requests, and a complete user message exactly `hej`;
-  bare `hej` runs the agentera prime orientation dashboard path instead of a generic greeting.
-version: "2.7.6"
+  The open protocol for turning AI agents into engineering teams. One Agentera
+  skill with twelve capabilities; per-capability prose lives in
+  `packages/cli/src/capabilities/<name>/instructions.ts` and the runtime serves
+  it through `agentera prime --context <name> --format json`. Use this skill
+  for /agentera, Agentera capability requests, and a complete user message
+  exactly `hej`; bare `hej` runs the agentera prime orientation dashboard path
+  instead of a generic greeting.
+version: "3.0.0"
 spec_sections: [1, 2, 3, 4, 5, 6, 11, 13, 18, 19, 20, 22, 23]
+capabilities:
+  - hej
+  - visionera
+  - resonera
+  - inspirera
+  - planera
+  - realisera
+  - optimera
+  - inspektera
+  - dokumentera
+  - profilera
+  - visualisera
+  - orkestrera
 ---
 
 # agentera
@@ -239,7 +253,7 @@ Bare `/agentera` returning-project output must include these visible markers:
 
 Use the README-style layout from hej Step 1b: metrics first, narrative read
 inside `status`, then attention and next. The issues summary line uses
-`critical · degraded · annoying` only. Omit `attention` only when the source has no attention items. Always include the
+`critical · degraded · normal · annoying` in the order prime emits them. Omit `attention` only when the source has no attention items. Always include the
 mandatory `⌂ hej · <status>` marker below the dashboard code fence, and ask for
 confirmation before invoking the suggested downstream capability. For
 `/agentera <capability-name>` or `/agentera <alias>`, do not assume the route
@@ -261,21 +275,25 @@ v2 paths `hej --capability-context` and `--context-profile` are removed in 3.0.
 For normal ≡ planera execution, use
 `capability_context.context.planning_context.startup_contract` from
 `agentera prime --context planera --format json`
-before reading `skills/agentera/capabilities/planera/instructions.md`. Read Planera prose only when
-editing Planera, resolving contradiction or ambiguity, validating detailed
-behavior not covered by the compact contract, or investigating benchmark/read-trigger
-evidence. This preserves Planera prose as detailed authority and does not add
-`agentera planera`; `/agentera plan` remains routing while `agentera state plan`
-remains plan state (top-level `agentera plan` is a migration alias).
+before reading the Planera prose from
+`packages/cli/src/capabilities/planera/instructions.ts` (served via
+`capability_context.prose` from the same prime call). Read the full Planera
+prose only when editing Planera, resolving contradiction or ambiguity,
+validating detailed behavior not covered by the compact contract, or
+investigating benchmark/read-trigger evidence. This preserves Planera prose
+as detailed authority and does not add `agentera planera`; `/agentera plan`
+remains routing while `agentera state plan` remains plan state (top-level
+`agentera plan` is a migration alias).
 For normal DECISIONS.md context, use `agentera state decisions --format json` and its
 source_contract. When `complete_for_normal_deliberation_context=true`, preserve
 returned `missing_fields`, `compacted`, `caveats`, and `satisfaction.review_needed`
 instead of raw-reading `.agentera/decisions.yaml` to reconstruct missing history.
 Raw decision artifact access is reserved for Resonera-owned writes/repairs,
 artifact corruption diagnostics, or CLI defect investigation.
-Reading a capability's `instructions.md` file is not itself a capability invocation;
-invocation means routing to the capability, following its prose, and using the
-CLI state layer first for artifact-backed state.
+Reading a capability's instructions module is not itself a capability invocation;
+invocation means routing to the capability, fetching the prose via
+`agentera prime --context <name> --format json`, following that prose, and using
+the CLI state layer first for artifact-backed state.
 
 Capability handoffs use glyph plus canonical capability name, for example
 `⧉ realisera` or `≡ planera`. Reserve `/agentera <alias>` wording for explicit
@@ -436,25 +454,24 @@ Before reading or writing any artifact, check if `.agentera/docs.yaml` exists. I
 
 ```
 skills/agentera/
-  SKILL.md                          # This file
+  SKILL.md                          # This file (routing stub + capability table)
   protocol.yaml                     # Shared primitives
   capability_schema_contract.yaml   # Self-referential schema contract
   capabilities/
     hej/
-      instructions.md
       schemas/
         triggers.yaml
         artifacts.yaml
         validation.yaml
         exit.yaml
     resonera/
-      instructions.md
       schemas/
         triggers.yaml
         artifacts.yaml
         validation.yaml
         exit.yaml
-    ... (12 capabilities total)
+    ... (12 capabilities total, each with schemas/ only)
+packages/cli/src/capabilities/<name>/instructions.ts   # Per-capability prose (D65)
 ```
 
 Validate any capability against the contract through the canonical CLI:

package/bundle/skills/agentera/agents/dokumentera.toml

@@ -2,5 +2,5 @@
 name = "dokumentera"
 description = "Documentation updates and synchronization."
 developer_instructions = """
-You are the Agentera dokumentera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/dokumentera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/dokumentera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera dokumentera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context dokumentera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/hej.toml

@@ -2,5 +2,5 @@
 name = "hej"
 description = "Agentera orientation and routing dashboard."
 developer_instructions = """
-You are the Agentera hej capability subagent. You are a read-only agent — do not write files or execute shell commands. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/hej/instructions.md when available. For local checkout development, use skills/agentera/capabilities/hej/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera hej capability subagent. You are a read-only agent — do not write files or execute shell commands. Run `agentera prime --context hej --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/inspektera.toml

@@ -2,5 +2,5 @@
 name = "inspektera"
 description = "Codebase health audit."
 developer_instructions = """
-You are the Agentera inspektera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/inspektera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/inspektera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera inspektera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context inspektera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/inspirera.toml

@@ -2,5 +2,5 @@
 name = "inspirera"
 description = "External pattern research and synthesis."
 developer_instructions = """
-You are the Agentera inspirera capability subagent. You are a read-only agent — do not write files or execute shell commands. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/inspirera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/inspirera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera inspirera capability subagent. You are a read-only agent — do not write files or execute shell commands. Run `agentera prime --context inspirera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/optimera.toml

@@ -2,5 +2,5 @@
 name = "optimera"
 description = "Metric-driven optimization cycles."
 developer_instructions = """
-You are the Agentera optimera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/optimera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/optimera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera optimera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context optimera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/orkestrera.toml

@@ -2,5 +2,5 @@
 name = "orkestrera"
 description = "Multi-cycle orchestration over active plans."
 developer_instructions = """
-You are the Agentera orkestrera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/orkestrera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/orkestrera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera orkestrera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context orkestrera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/planera.toml

@@ -2,5 +2,5 @@
 name = "planera"
 description = "Planning with acceptance criteria."
 developer_instructions = """
-You are the Agentera planera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/planera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/planera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera planera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context planera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/profilera.toml

@@ -2,5 +2,5 @@
 name = "profilera"
 description = "Decision profiling and preference memory."
 developer_instructions = """
-You are the Agentera profilera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/profilera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/profilera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera profilera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context profilera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/realisera.toml

@@ -2,5 +2,5 @@
 name = "realisera"
 description = "Autonomous development execution."
 developer_instructions = """
-You are the Agentera realisera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/realisera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/realisera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera realisera capability subagent. You have full file write, file edit, and shell execution tools available — use them to implement code changes, run tests, and commit results. Run `agentera prime --context realisera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/resonera.toml

@@ -2,5 +2,5 @@
 name = "resonera"
 description = "Structured deliberation and decision support."
 developer_instructions = """
-You are the Agentera resonera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/resonera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/resonera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera resonera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context resonera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/visionera.toml

@@ -2,5 +2,5 @@
 name = "visionera"
 description = "Define and refine project direction."
 developer_instructions = """
-You are the Agentera visionera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/visionera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/visionera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera visionera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context visionera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

package/bundle/skills/agentera/agents/visualisera.toml

@@ -2,5 +2,5 @@
 name = "visualisera"
 description = "Visual identity and design systems."
 developer_instructions = """
-You are the Agentera visualisera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Read the authoritative instructions at ${AGENTERA_HOME}/app/skills/agentera/capabilities/visualisera/instructions.md when available. For local checkout development, use skills/agentera/capabilities/visualisera/instructions.md under the active Agentera source root. Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
+You are the Agentera visualisera capability subagent. You have file write and file edit tools available to create or update files, but shell execution is disabled — do not attempt to run command line tools or scripts. Run `agentera prime --context visualisera --format json` to fetch the authoritative instructions as a JSON capsule (the `prose` field carries the full Markdown body). Stay within the dispatched capability task, use the Agentera CLI state seam first, and preserve Agentera artifact safety rails.
 """

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

@@ -10,7 +10,7 @@ VALIDATION:
       source-code read prohibition.
     severity: critical
     checks:
-      - "instructions.md contains NEVER read implementation source code"
+      - "orkestrera prose (packages/cli/src/capabilities/orkestrera/instructions.ts) contains NEVER read implementation source code"
   2:
     id: V2
     rule: evaluation_gate_required
@@ -20,7 +20,7 @@ VALIDATION:
       the prose contains the never-skip-evaluation safety rail.
     severity: critical
     checks:
-      - "instructions.md contains NEVER skip evaluation"
+      - "orkestrera prose contains NEVER skip evaluation"
   3:
     id: V3
     rule: retry_budget_enforced
@@ -30,7 +30,7 @@ VALIDATION:
       is stated in the prose and safety rails.
     severity: critical
     checks:
-      - "instructions.md contains retry budget of 2"
+      - "orkestrera prose contains retry budget of 2"
   4:
     id: V4
     rule: exit_marker_required
@@ -40,8 +40,8 @@ VALIDATION:
       where status is one of EX1-EX4.
     severity: critical
     checks:
-      - "instructions.md contains exit marker with glyph ⎈ (SG12)"
-      - "instructions.md references exit signals EX1-EX4"
+      - "orkestrera prose contains exit marker with glyph ⎈ (SG12)"
+      - "orkestrera prose references exit signals EX1-EX4"
   5:
     id: V5
     rule: orchestrator_read_only_artifacts
@@ -66,9 +66,9 @@ VALIDATION:
       or decisions artifact reads.
     severity: critical
     checks:
-      - "instructions.md contains agentera prime --context orkestrera --format json"
-      - "instructions.md contains Use the returned `orchestration_context` before raw plan, progress, health, TODO, or decisions artifacts"
-      - "instructions.md contains If `source_contract.complete_for_orchestration_context` is true, do not read raw plan, progress, health, TODO, or decisions artifacts"
+      - "orkestrera prose contains agentera prime --context orkestrera --format json"
+      - "orkestrera prose contains Use the returned `orchestration_context` before raw plan, progress, health, TODO, or decisions artifacts"
+      - "orkestrera prose contains If `source_contract.complete_for_orchestration_context` is true, do not read raw plan, progress, health, TODO, or decisions artifacts"
   7:
     id: V7
     rule: cli_fallback_before_raw_read
@@ -77,8 +77,8 @@ VALIDATION:
       routine CLI fallback commands before any last-resort raw artifact read.
     severity: critical
     checks:
-      - "instructions.md contains run the listed routine CLI fallback commands"
-      - "instructions.md contains Read a raw artifact only as a last-resort diagnostic"
+      - "orkestrera prose contains run the listed routine CLI fallback commands"
+      - "orkestrera prose contains Read a raw artifact only as a last-resort diagnostic"
   8:
     id: V8
     rule: caveats_preserved_for_evaluation
@@ -88,9 +88,9 @@ VALIDATION:
       inspektera.
     severity: critical
     checks:
-      - "instructions.md contains compacted decision caveats"
-      - "instructions.md contains stale health/profile/app caveats"
-      - "instructions.md contains retry-state provenance"
+      - "orkestrera prose contains compacted decision caveats"
+      - "orkestrera prose contains stale health/profile/app caveats"
+      - "orkestrera prose contains retry-state provenance"
   9:
     id: V9
     rule: satisfaction_authority_boundary
@@ -105,3 +105,16 @@ VALIDATION:
       - "Provisional satisfaction requires evidence"
       - "Only the user confirms final satisfaction"
       - "Missing or compacted satisfaction caveats are preserved"
+  10:
+    id: V10
+    rule: inspektera_citation_required
+    description: >-
+      Orkestrera Step 3 Surface 2 inspektera delegation MUST require a
+      citation: <file>:<line> (or not-applicable: <reason>) for every WARN and
+      FAIL finding, and require verify_command for WARN rows with file:line
+      citations. Authority: references/cli/capability-instruction-contract.yaml#evaluator_handoff.
+    severity: critical
+    checks:
+      - "orkestrera prose contains citation: `<file>:<line>` OR `not-applicable: <reason>`"
+      - "orkestrera prose contains verify_command"
+      - "orkestrera prose contains evaluator_handoff.output_requirements"

package/bundle/skills/agentera/capability_schema_contract.yaml

@@ -7,15 +7,24 @@
 #   1. Required groups every capability schema must contain
 #   2. Entry structure within each group (numbered, stable IDs)
 #   3. Deprecation protocol (deprecated + replaced_by)
-#   4. Directory structure requirements (instructions.md, schemas/)
+#   4. Directory structure requirements (instruction module, schemas/)
 #   5. Machine-readable validation rules consumed by future contract loaders
+#
+# D65: the per-capability `instructions.md` Markdown file is retired. The
+# behavioral instructions now live at
+# `packages/cli/src/capabilities/<name>/instructions.ts` as a default-exported
+# string constant. The directory requirement below points at the new path;
+# the V1 directory_structure rule's `checks` list and the ARTIFACTS A3 path
+# text follow the same move.
 
 meta:
   name: capability_schema_contract
   version: "1.0.0"
   description: >-
     Defines what a valid capability schema looks like.
-    A capability directory must contain instructions.md and a schemas/ directory.
+    A capability directory must contain schemas/ and the runtime must
+    resolve the capability's behavioral instructions from the
+    packages/cli/src/capabilities/<name>/instructions.ts module.
     The union of all YAML files in schemas/ must contain all required groups.
   capability_type: contract
   self_referential: true
@@ -68,11 +77,15 @@ GROUP_PREFIXES:
   EXIT_CONDITIONS: E
 
 DIRECTORY_REQUIREMENTS:
-  instruction_file:
-    path: instructions.md
+  instruction_module:
+    path: packages/cli/src/capabilities/<name>/instructions.ts
     type: file
     required: true
-    description: Behavioral instructions the agent reads.
+    description: >-
+      TypeScript module that exports the capability's behavioral instructions
+      as a default-exported string constant. The runtime loads it via the
+      compiled .js path and surfaces the prose through
+      `agentera prime --context <name> --format json`.
   schemas_directory:
     path: schemas
     type: directory
@@ -246,9 +259,9 @@ ARTIFACTS:
     name: capability_directory
     path: "capabilities/<name>/"
     description: >-
-      A valid capability directory. Must contain instructions.md and schemas/.
-      The schemas/ directory holds YAML files whose union covers all required
-      groups.
+      A valid capability directory. Must contain schemas/. The behavioral
+      instructions module lives at
+      packages/cli/src/capabilities/<name>/instructions.ts.
     produces: false
     consumes: true
   2:
@@ -263,11 +276,15 @@ ARTIFACTS:
     consumes: true
   3:
     id: A3
-    name: instruction_file
-    path: "capabilities/<name>/instructions.md"
+    name: instruction_module
+    path: "packages/cli/src/capabilities/<name>/instructions.ts"
     description: >-
-      Behavioral instructions the agent reads. Markdown format. Contains the
-      capability's workflow, personality, interaction rules, and examples.
+      Behavioral instructions the agent reads. TypeScript module that exports
+      a default-exported string constant. The runtime loads it via the
+      compiled .js path and serves the prose through
+      `agentera prime --context <name> --format json`. The Markdown
+      `instructions.md` file is no longer part of the on-disk capability
+      surface (D65).
     produces: false
     consumes: true
   4:
@@ -285,10 +302,12 @@ VALIDATION:
     id: V1
     rule: directory_structure
     description: >-
-      Capability directory must contain instructions.md and schemas/ directory.
+      Capability directory must contain schemas/ and the instruction module
+      packages/cli/src/capabilities/<name>/instructions.ts must exist as a
+      TypeScript source file (the runtime resolves the compiled .js path).
     severity: error
     checks:
-      - "instructions.md is a file"
+      - "instruction_module is a file"
       - "schemas/ is a directory"
       - "schemas/ contains at least one .yaml file"
   2:

package/bundle/skills/agentera/references/contract.md

@@ -145,7 +145,7 @@ Three project-facing files at the project root; nine operational files in `.agen
 | CHANGELOG.md | CHANGELOG.md | realisera | project contributors | ## [Unreleased], ### Added/Changed/Fixed |
 | DECISIONS.md | .agentera/decisions.yaml | resonera | planera, realisera, inspektera, profilera, optimera, orkestrera | ## Decision N · date, **Question/Context/Alternatives/Choice/Reasoning/Confidence/Feeds into** |
 | PLAN.md | .agentera/plan.yaml | planera | realisera, inspektera, orkestrera | <!-- Level/Created/Status -->, ## Tasks with ### Task N, **Status/Depends on/Acceptance** |
-| PROGRESS.md | .agentera/progress.yaml | realisera | planera, inspektera, dokumentera, visionera, orkestrera | ## Cycle N · date, **Phase/What/Commit/Inspiration/Discovered/Next/Context** |
+| PROGRESS.md | .agentera/progress.yaml | realisera | planera, inspektera, dokumentera, visionera, orkestrera | ## Cycle N · date, **Phase/What/Inspiration/Discovered/Next/Context** |
 | HEALTH.md | .agentera/health.yaml | inspektera | realisera, planera, orkestrera | ## Audit N · date, **Dimensions/Findings/Overall/Grades**, per-dimension sections |
 | OBJECTIVE.md | .agentera/optimera/<name>/objective.yaml | optimera | optimera | ## Metric, ## Target, ## Baseline, ## Constraints, **Status** |
 | EXPERIMENTS.md | .agentera/optimera/<name>/experiments.yaml | optimera | optimera | ## Experiment N · date, **Hypothesis/Method/Result/Conclusion**; ## Closure · date, **Final value/Target/Reason** |
@@ -669,7 +669,7 @@ This gate is orthogonal to Section 19 Staleness Detection. Section 19 asks: did
 
 ### Evidence format
 
-Every cycle entry in PROGRESS.md carries a `verified` field alongside phase, what, commit, inspiration, discovered, next, and context fields. The field is mandatory: no cycle is considered closed without it. The field accepts exactly one of three shapes:
+Every cycle entry in PROGRESS.md carries a `verified` field alongside phase, what, inspiration, discovered, next, and context fields. The field is mandatory: no cycle is considered closed without it. The field accepts exactly one of three shapes:
 
 | Shape | Content |
 |-------|---------|

package/bundle/skills/agentera/schemas/artifacts/decisions.yaml

@@ -55,7 +55,7 @@ BUDGET:
   1:
     id: DB1
     scope: per_decision_entry
-    max_words: 200
+    max_words: 1000
     description: >-
       Maximum words per decision entry. Budgets are guidelines, not hard
       blockers.

package/bundle/skills/agentera/schemas/artifacts/progress.yaml

@@ -1,7 +1,7 @@
 # Progress Artifact Schema
 #
 # Cycle-by-cycle operational log for realisera. Each entry records what happened
-# in one development cycle: phase, work done, commit, discoveries, verification,
+# in one development cycle: phase, work done, discoveries, verification,
 # next steps, and context envelope.
 #
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
@@ -16,12 +16,11 @@
 # (type-prefix from heading)            CYCLE.type             PR3
 # **Phase**: <phase>                    CYCLE.phase            PR4
 # **What**: <text>                      CYCLE.what             PR5
-# **Commit**: <hash/N/A>                CYCLE.commit           PR6
-# **Inspiration**: <text>               CYCLE.inspiration      PR7
-# **Discovered**: <text>                CYCLE.discovered       PR8
-# **Verified**: <text>                  CYCLE.verified         PR9
-# **Next**: <text>                      CYCLE.next             PR10
-# **Context**: <text>                   CYCLE.context          PR11
+# **Inspiration**: <text>               CYCLE.inspiration      PR6
+# **Discovered**: <text>                CYCLE.discovered       PR7
+# **Verified**: <text>                  CYCLE.verified         PR8
+# **Next**: <text>                      CYCLE.next             PR9
+# **Context**: <text>                   CYCLE.context          PR10
 # (intent from Context)                 CONTEXT.intent         PT1
 # (constraints from Context)            CONTEXT.constraints    PT2
 # (unknowns from Context)               CONTEXT.unknowns       PT3
@@ -172,57 +171,38 @@ CYCLE:
       - "Non-empty string"
   6:
     id: PR6
-    field: commit
-    type: string
-    required: true
-    description: >-
-      Git commit that contains the product change for this cycle—not the commit
-      that last edited progress metadata. Use `pending` until that hash is known;
-      then the product commit hash, optionally with subject (e.g.
-      `abc1234 Speed up pytest suite`). Use `N/A: …` when no product commit was
-      made.
-    validation:
-      - "Non-empty string"
-      - "Use `pending` until the product-change commit hash is known; do not amend solely to backfill this field"
-      - >-
-        Hashes that do not resolve as commit objects in the local clone (another
-        machine's copy, shallow CI checkout, or not yet fetched) are intentionally
-        not flagged by progress validation or `agentera check backfill`; reconcile
-        with a full clone or forward-fill once the product commit exists locally
-  7:
-    id: PR7
     field: inspiration
     type: string
     required: false
     description: >-
       What prompted this cycle. References to active plan tasks,
       decisions, or conventions that drove the work.
-  8:
-    id: PR8
+  7:
+    id: PR7
     field: discovered
     type: string
     required: false
     description: >-
       Unexpected findings during the cycle. Things learned that were
       not known before starting.
-  9:
-    id: PR9
+  8:
+    id: PR8
     field: verified
     type: string
     required: false
     description: >-
       Evidence that the work was verified. Test commands run, validation
       passed, manual checks performed.
-  10:
-    id: PR10
+  9:
+    id: PR9
     field: next
     type: string
     required: false
     description: >-
       What should happen next. Guidance for subsequent cycles.
       Explicit about scope boundaries to prevent scope creep.
-  11:
-    id: PR11
+  10:
+    id: PR10
     field: context
     type: map
     required: true
@@ -293,14 +273,13 @@ VALIDATION:
     severity: error
     description: >-
       Each full-detail cycle entry must have: number, timestamp, type,
-      phase, what, commit, and context (with intent).
+      phase, what, and context (with intent).
     checks:
       - "number is present and is a positive integer"
       - "timestamp is present and matches YYYY-MM-DD HH:MM"
       - "type is present and is a valid commit prefix"
       - "phase is present and is a valid phase name"
       - "what is present and non-empty"
-      - "commit is present"
       - "context is present with intent sub-field"
   3:
     id: PV3

package/bundle/skills/agentera/schemas/artifacts/todo.yaml

@@ -108,3 +108,17 @@ CONVENTION:
       Resolved items should wrap the original task text in Markdown
       strikethrough (~~text~~) before the resolution summary, keeping
       the original intent readable while visually marking it closed.
+  6:
+    id: TC6
+    field: severity_band_policy
+    level: required
+    description: >-
+      Severity band policy: Critical (⇶) is enforced by the validator
+      (level: required) and must contain at least one `- [type]` item;
+      Degraded (⇉), Normal (→), and Annoying (⇢) are advisory and may
+      be header-only (no list entries, no Placeholder sentinel). The
+      asymmetry reflects the fact that Critical is the only band whose
+      absence is user-visible routing damage; the other three bands
+      may be honestly empty. This rule lives in
+      packages/cli/src/hooks/validateArtifact.ts `validateMdItems` as
+      the single executable source of truth.

package/bundle/skills/hej/SKILL.md

@@ -5,7 +5,7 @@ description: >
   /hej installs toward the Agentera v2 /agentera entry point and idempotent
   upgrade CLI. Do not use this skill for bare text `hej`; route that through
   the bundled agentera skill and the agentera hej dashboard path.
-version: "2.7.6"
+version: "3.0.0"
 legacy_bridge: true
 ---
 

package/dist/analytics/usageStats.js

@@ -313,11 +313,33 @@ export class CorpusUnavailable extends Error {
         this.name = "CorpusUnavailable";
     }
 }
+export const MAX_CORPUS_READ_BYTES = 64 * 1024 * 1024;
+export function corpusTooLargeReason(corpusPath) {
+    try {
+        const size = fs.statSync(corpusPath).size;
+        if (size <= MAX_CORPUS_READ_BYTES)
+            return null;
+        return `corpus is too large to load (${size} bytes; max ${MAX_CORPUS_READ_BYTES}). Rebuild with agentera report refresh --consent local-history or pass --corpus PATH to a smaller extract.`;
+    }
+    catch {
+        return null;
+    }
+}
 export function loadCorpusOrRaise(corpusPath) {
     if (!fs.existsSync(corpusPath)) {
         throw new CorpusUnavailable(`corpus.json not found at ${corpusPath}. ${CORPUS_GUIDANCE}`);
     }
-    const corpus = JSON.parse(fs.readFileSync(corpusPath, "utf8"));
+    const tooLarge = corpusTooLargeReason(corpusPath);
+    if (tooLarge) {
+        throw new CorpusUnavailable(`corpus at ${corpusPath} ${tooLarge}`);
+    }
+    let corpus;
+    try {
+        corpus = JSON.parse(fs.readFileSync(corpusPath, "utf8"));
+    }
+    catch (exc) {
+        throw new CorpusUnavailable(`corpus is not readable JSON: ${exc.message}`);
+    }
     const records = isMapping(corpus) ? (corpus.records ?? []) : [];
     const hasTurn = Array.isArray(records) && records.some((r) => isMapping(r) && r.source_kind === "conversation_turn");
     if (!hasTurn) {