agentera 3.0.0-dev.7 → 3.0.0-dev.74

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

@@ -1,15 +1,15 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: vision
+    artifact: vision
     local_role: produces_and_consumes
     description: >-
       Build 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).
+      during vision bootstrap.
   2:
     id: A2
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Build consumes TODO state from execution_context and included status state
@@ -17,7 +17,7 @@ ARTIFACTS:
       entries. Severity classified per protocol SI1-SI4.
   3:
     id: A3
-    artifact_id: changelog
+    artifact: changelog
     local_role: produces_and_consumes
     description: >-
       Build consumes changelog boundary from execution_context or the listed
@@ -25,31 +25,38 @@ ARTIFACTS:
       [Unreleased] based on commit type and promotes on version bumps.
   4:
     id: A4
-    artifact_id: progress
+    artifact: progress
     local_role: produces_and_consumes
     description: >-
-      Operational cycle log. Build consumes latest progress evidence from
-      execution_context first, then appends one entry per cycle with mandatory
-      Verified field. Compacted by applying schema COMPACTION rules.
+      Durable project-outcome log and the sole durable channel for bounded
+      autonomous glossary caveat lifecycle evidence. Build consumes latest
+      progress evidence from execution_context first, then bounded `npx -y
+      agentera@next state progress list --limit 20 --format json` discovery or
+      exact `state progress get --id ID` retrieval. The typed writer's
+      progress_write_policy governs whether a cycle appends zero or one record;
+      every appended cycle has a mandatory non-empty verified field.
   5:
     id: A5
-    artifact_id: health
+    artifact: health
     local_role: consumes
     description: >-
       Build consumes health state from execution_context and included status
-      state before direct reads, focusing on critical and degraded findings for
-      work selection.
+      state before bounded `npx -y agentera@next state health list --limit 20 --format json`
+       discovery or exact `state health get --id ID` retrieval, focusing on
+      critical and degraded findings for work selection. Raw reads are
+      diagnostic-only for corruption or CLI-defect investigation.
   6:
     id: A6
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
-      Build consumes decision caveats and fallback commands from
+      Build consumes decision caveats and bounded list/get fallback commands from
       execution_context first. Firm (DL1) entries are constraints and exploratory
-      (DL3) entries are uncertain foundations during work selection.
+      (DL3) entries are uncertain foundations during work selection. Raw reads are
+      diagnostic-only for corruption or CLI-defect investigation.
   7:
     id: A7
-    artifact_id: plan
+    artifact: plan
     local_role: produces_and_consumes
     description: >-
       Build consumes selected task, acceptance criteria, dependencies,
@@ -57,24 +64,40 @@ ARTIFACTS:
       direct plan reads, then updates task status and surprises during execution.
   8:
     id: A8
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
-      Build consumes status profile summary first. Missing or stale profile state
-      is a caveat and does not authorize profile refresh or direct profile reads
-      during normal startup.
+      Build consumes status profile summary first and reads profile grounding
+      only from `npx -y agentera@next report profile-grounding --format json` when shared
+      validity is `valid`. Absent or repair-needed state preserves exact
+      recovery and does not authorize refresh or direct profile reads.
   9:
     id: A9
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Build consumes artifact mappings and docs caveats from execution_context
       and included status docs state before direct docs reads.
   10:
     id: A10
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Build 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.
+  11:
+    id: A11
+    artifact: glossary
+    local_role: produces_and_consumes
+    description: >-
+      Build alone publishes one explicitly user-confirmed terminology proposal
+      through `npx -y agentera@next state glossary publish --input REQUEST`. The typed writer
+      revalidates audit source evidence and atomically records the immutable
+      approval beside the shared-only project entry. Build does not consume the
+      glossary only to validate replay and preserve unrelated publication state.
+      Separately, at governed meaning-sensitive Build events it requests bounded
+      read-only advice through `npx -y agentera@next report glossary-advice --input REQUEST
+      --format json`. Advice and progress caveats never publish terminology,
+      approve a proposal, reuse confirmation, mutate personal profiles or docs
+      mappings, or grant publication authority to another capability.

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

@@ -3,9 +3,11 @@ EXIT_CONDITIONS:
     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.
+      One full cycle completed. Work was selected, implemented, and verified
+      against the project's test/build suite. Required artifact updates
+      preceded the cycle's single conventional commit. They include TODO,
+      changelog, and plan updates. Progress is present for policy-required
+      cases and optional for allowed durable outcomes.
     exit_signal: complete
   2:
     id: E2
@@ -13,15 +15,15 @@ EXIT_CONDITIONS:
     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.
+      than intended due to scope reduction, or durable discoveries recorded in
+      progress state 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
+      vision bootstrap 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

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

@@ -1,49 +1,27 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests build for autonomous development.
+    description: A scoped implementation task or one verified development cycle.
     priority: high
-    patterns:
-      - "build"
-      - "/build"
-    confidence_threshold: 60
-    borderline_band: 10
   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"
-    confidence_threshold: 50
+    description: Implement one requested feature, fix, or bounded development task.
+    priority: high
+    disambiguates_against:
+      - capability: vision
+        hint: "build implements code; vision defines or refines project direction"
+      - capability: profile
+        hint: "build implements a software task; profile builds a reusable decision profile"
+      - capability: orchestrate
+        hint: "build completes one task or cycle; orchestrate runs an entire plan or multiple tasks"
   3:
     id: T3
-    description: >-
-      Continuous development signals. Matches when the user wants ongoing
-      building or to start working on the project.
+    description: Start or continue a single concrete implementation task.
     priority: medium
-    patterns:
-      - "keep building"
-      - "start building"
-      - "work on the project"
-    confidence_threshold: 50
   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.
+    description: Implement a scoped task after its plan or requirements are established.
     priority: medium
-    patterns:
-      - "refine the vision"
-    confidence_threshold: 50
     disambiguates_against:
-      - capability: vision
-        hint: "build implements code after vision work; vision defines direction"
-    patterns_regex:
-      - "\\brefine\\s+the\\s+vision\\b"
+      - capability: plan
+        hint: "build implements an established task; plan structures work before implementation"

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

@@ -3,9 +3,10 @@ VALIDATION:
     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.
+      Every progress entity record appended by Build MUST have a non-empty
+      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"
@@ -14,17 +15,22 @@ VALIDATION:
     id: V2
     rule: one_cycle_per_invocation
     description: >-
-      Build executes exactly one cycle per invocation. After logging (Step 9),
-      the capability MUST stop. Multiple cycles require separate invocations or
-      /loop.
+      Build executes exactly one cycle per invocation. After logging required
+      artifacts (Step 7) and committing once (Step 8), the capability MUST stop.
+      The typed progress_write_policy determines whether the cycle appends zero
+      or one progress record. Multiple cycles require separate invocations or an
+      explicit user request.
     severity: critical
     checks:
-      - "Only one cycle entry appended to PROGRESS.md per invocation"
+      - "At most one progress entity is appended per invocation"
+      - "Durable outcomes needed by future work may append one verified record"
+      - "Required glossary caveats and plan-completion sweeps append one verified record"
+      - "Attempt-only cycles with no durable project truth append no record"
   3:
     id: V3
     rule: no_remote_push
     description: >-
-      Build MUST NEVER push to any remote repository. All commits are local
+      Build MUST NOT push to any remote repository. All commits are local
       only. Remote operations require explicit user instruction outside this
       capability.
     severity: critical
@@ -35,36 +41,38 @@ VALIDATION:
     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).
+      during a vision bootstrap.
     severity: critical
     checks:
       - "Vision artifact not modified outside brainstorm"
   5:
     id: V5
-    rule: consecutive_failure_guard
+    rule: attempt_history_authority
     description: >-
-      If the last 3 PROGRESS.md entries all record failed cycles, build
-      MUST stop and surface the pattern to the user. Do not attempt a 4th
-      consecutive cycle on the same failing problem.
+      Build MUST NOT reconstruct task or release attempt history from progress.
+      Plan evaluations own task attempts, while qualification and publication
+      receipts own release attempts and retry state. Missing retry state does
+      not authorize an attempt-only progress record.
     severity: critical
     checks:
-      - "Failure pattern checked before cycle start"
+      - "Progress is not used as task or release attempt history"
+      - "Retry state comes only from its owning plan or receipt authority"
   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/).
+      Entity state MUST use exact/list CLI reads and typed writers discovered by
+      `npx -y agentera@next state <artifact> explain`. Check .agentera/docs.yaml only for
+      intentional singleton path overrides.
     severity: warning
     checks:
-      - "DOCS.md checked before artifact access"
+      - "Entity files are not read or edited directly"
+      - "docs.yaml checked before singleton artifact access"
   7:
     id: V7
     rule: execution_context_first
     description: >-
-      Build startup SHOULD begin from `agentera prime --context build
+      Build startup SHOULD begin from `npx -y agentera@next prime --context build
       --format json` and consume complete execution_context
       state before direct reads of plan, progress, TODO, docs, health,
       decisions, changelog, vision, profile, or design artifacts.
@@ -93,7 +101,7 @@ VALIDATION:
     severity: critical
     checks:
       - "No protected state mutation during context generation"
-      - "No unsupported `agentera build` or `agentera build` command introduced"
+      - "No unsupported `agentera build` command introduced"
   10:
     id: V10
     rule: satisfaction_authority_boundary
@@ -108,3 +116,69 @@ VALIDATION:
       - "Provisional satisfaction requires evidence"
       - "Only the user confirms final satisfaction"
       - "Missing or compacted satisfaction caveats are preserved"
+  11:
+    id: V11
+    rule: sanitized_profile_grounding
+    description: >-
+      Build MUST ground only from the `content` returned by `npx -y agentera@next report
+      profile-grounding --format json` when shared validity is valid; it MUST
+      preserve absent/repair-needed recovery and MUST NOT direct-read PROFILE.md.
+    severity: critical
+    checks:
+      - "Sanitized grounding command used after prime startup"
+      - "Prime and report validity objects agree before content use"
+      - "Raw profile path not read"
+  12:
+    id: V12
+    rule: governed_glossary_advice
+    description: >-
+      At initial meaning-sensitive cycle intent and later user-authored changes
+      or clarification answers that can alter intent, Build MUST request bounded
+      advice through `npx -y agentera@next report glossary-advice --input REQUEST --format
+      json`. Unchanged replay, unrelated turns, rendering, and tool output MUST
+      NOT refresh advice.
+    severity: critical
+    checks:
+      - "Exact project authority or proven-gap personal fallback grounds intent"
+      - "Governed changes refresh only the affected meaning"
+      - "Incidental turns and unchanged replay do not refresh"
+  13:
+    id: V13
+    rule: glossary_review_and_autonomy
+    description: >-
+      Interactive Build MUST ask one focused clarification before disputed
+      meaning-sensitive reliance whenever review is required. If autonomous Build
+      cannot pause, it MUST avoid the disputed meaning, proceed conservatively
+      only where safe, and append one idempotent privacy-safe glossary_caveat
+      lifecycle envelope through the typed progress writer.
+    severity: critical
+    checks:
+      - "Clarification precedes meaning-sensitive execution and re-evaluates only the affected meaning"
+      - "Autonomous work does not assume disputed meaning"
+      - "Current, resolved, and superseded caveat events obey opaque identity lifecycle"
+  14:
+    id: V14
+    rule: glossary_publication_isolation
+    description: >-
+      Advice, tension, clarification, and progress caveat lifecycle MUST NOT call
+      `npx -y agentera@next state glossary publish`, create or reuse approval, substitute for
+      digest-bound user confirmation, satisfy decisions or plan state, or grant
+      Discuss or Audit publication authority.
+    severity: critical
+    checks:
+      - "Advice and caveat paths perform zero glossary publication writes"
+      - "Only separately supplied digest-confirmed publication retains Build authority"
+  15:
+    id: V15
+    rule: transient_no_plan_execution_input
+    description: >-
+      When no current executable plan owns startup, Build MAY accept one bounded
+      `agentera.buildExecutionRequest.v1` through `prime --context build --input
+      <file|-> --format json`. The request supplies explicit scope and acceptance
+      transiently; it MUST NOT persist, create, or mutate plan state. Current
+      plan-owned execution conflicts instead of silently ignoring the request.
+    severity: critical
+    checks:
+      - "Transient input is used only when no current executable plan owns startup"
+      - "No request content is placed in argv or persisted"
+      - "No-plan execution requires explicit scope and acceptance"

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

@@ -1,7 +1,7 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: design
+    artifact: design
     local_role: produces_and_consumes
     description: >-
       Visual identity system with design tokens, typography, colors,
@@ -9,35 +9,35 @@ ARTIFACTS:
       reads agent-readable YAML token blocks with HTML comment markers.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Design reads the Identity section to propose visual tokens
       coherent with the declared verbal personality.
   3:
     id: A3
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Design reads this during refine mode to identify UI work and
       inline design decisions since the design system was written.
   4:
     id: A4
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Design reads this to check for design-related issues and files
       code drift findings here during audit mode.
   5:
     id: A5
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Design reads this first to resolve project-local artifact mappings
       before accessing other artifacts.
   6:
     id: A6
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Design reads aesthetic preferences from the profile as defaults

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

@@ -4,16 +4,16 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       DESIGN.md was written (Create/Replace mode), updated (Refine mode),
-      or audited with findings reported (Audit mode). Validation script
-      ran without errors, and all changes had explicit user approval.
+      or audited with findings reported (Audit mode). npx -y agentera@next check lint
+      --artifact design passed, and all changes had explicit user approval.
     exit_signal: complete
   2:
     id: E2
     condition: flagged
     description: >-
       The design system was produced or audited but with issues worth
-      surfacing. Possible causes: validation passed with advisory warnings,
-      the design drifts from VISION.md Identity, or audit findings were
+      surfacing. Possible causes: lint passed with advisory warnings,
+      the design drifts from vision Identity, or audit findings were
       neither fixed nor filed.
     exit_signal: flagged
   3:
@@ -21,7 +21,7 @@ EXIT_CONDITIONS:
     condition: stuck
     description: >-
       Cannot write DESIGN.md because the user declined to approve the
-      draft, the validation script reports unresolvable errors, or the
+      draft, npx -y agentera@next check lint reports unresolvable errors, or the
       project's UI stack is inaccessible.
     exit_signal: stuck
   4:

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

@@ -1,45 +1,16 @@
 TRIGGERS:
   1:
     id: T1
-    description: >-
-      Direct invocation by name or slash command. Matches when the user
-      explicitly requests design.
+    description: Define, maintain, or assess visual identity and a design system.
     priority: high
-    patterns:
-      - "design"
-      - "/design"
-    confidence_threshold: 60
-    borderline_band: 10
-    patterns_regex:
-      - "\\b/design\\b"
   2:
     id: T2
-    description: >-
-      Design system creation requests. Matches when the user wants to
-      create or set up a visual identity system or design tokens.
-    priority: medium
-    patterns:
-      - "create design system"
-      - "write DESIGN.md"
-      - "design tokens"
-      - "visual identity"
-      - "define the aesthetic"
-      - "set up design system"
-    confidence_threshold: 50
+    description: Create a visual identity, design system, design tokens, or aesthetic direction.
+    priority: high
   3:
     id: T3
-    description: >-
-      Design system refinement and audit requests. Matches when the user
-      wants to evolve, check, or update an existing design system.
-    priority: medium
-    patterns:
-      - "audit design"
-      - "refine design system"
-      - "update DESIGN.md"
-    confidence_threshold: 50
+    description: Refine, update, or audit a visual design system, including “audit the design system”.
+    priority: high
     disambiguates_against:
       - capability: audit
         hint: "design here is about visual identity, not codebase auditing"
-    patterns_regex:
-      - "\\baudit\\s+design\\b"
-      - "update\\s+DESIGN\\.md"

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

@@ -14,13 +14,13 @@ VALIDATION:
     id: V2
     rule: vision_identity_coherence
     description: >-
-      Design tokens MUST NOT conflict with VISION.md Identity. If the
+      Design tokens MUST NOT conflict with vision Identity. If the
       verbal identity says "warm and approachable" and the user wants a
       cold brutalist palette, the tension MUST be surfaced explicitly
       for the user to resolve.
     severity: critical
     checks:
-      - "Design tokens cohere with VISION.md Identity"
+      - "Design tokens cohere with vision Identity"
       - "Tensions surfaced when detected"
   3:
     id: V3

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

@@ -1,18 +1,20 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: decisions
+    artifact: decisions
     local_role: produces_and_consumes
     description: >-
       Reasoning trail with confidence labels. Discuss reads existing decisions
-      through `agentera decisions --format json` and its source_contract to avoid
-      re-deliberation, and writes new decision entries with confidence (DL1
-      firm, DL2 provisional, DL3 exploratory). Compact older entries by applying
-      schema COMPACTION rules; incomplete compacted entries are caveated context,
-      not a reason for historical reconstruction during normal deliberation.
+      through bounded `npx -y agentera@next state decisions list --limit 20 --format json`
+       discovery plus exact `npx -y agentera@next state decisions get --id ID --format json`
+      retrieval and its source_contract to avoid re-deliberation, and writes new decision entries with confidence
+      (DL1 firm, DL2 provisional, DL3 exploratory). Compact older entries by
+      applying schema COMPACTION rules; incomplete compacted entries are
+      caveated context, not a reason for historical reconstruction during
+      normal deliberation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: produces_and_consumes
     description: >-
       Discuss may update project direction only with explicit user
@@ -20,28 +22,30 @@ ARTIFACTS:
       context during deliberation.
   3:
     id: A3
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Discuss may add tech debt items surfaced during deliberation only with
       explicit user confirmation. Severity per protocol SI1-SI4.
   4:
     id: A4
-    artifact_id: objective
+    artifact: objective
     local_role: produces_and_consumes
     description: >-
       Discuss may write optimization decisions only with explicit user
       confirmation when a decision feeds into what to optimize.
   5:
     id: A5
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
-      Discuss reads this at session start to acknowledge high-confidence
-      entries and avoid re-deliberating settled ground.
+      Discuss reads only sanitized non-glossary content from `npx -y agentera@next report
+      profile-grounding --format json` at session start. It never direct-reads
+      the profile path. It uses content only when the shared validity object is
+      valid; absent or repair-needed results fail closed with exact recovery.
   6:
     id: A6
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Discuss reads this first to resolve project-local artifact mappings.

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

@@ -4,7 +4,7 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       Deliberation reached a conclusion the user chose to act on; any
-      requested artifacts (DECISIONS.md, VISION.md, OBJECTIVE.md, TODO.md)
+      requested artifacts (decisions, vision, objective, todo)
       were written with user approval, and the decision confidence level
       was captured.
     exit_signal: complete
@@ -15,7 +15,7 @@ EXIT_CONDITIONS:
       Deliberation concluded but the decision remains unresolved or
       provisional: the user wrapped up without a clear choice, significant
       tensions could not be resolved, or the conclusion contradicts prior
-      decisions in DECISIONS.md without explicit acknowledgment.
+      decisions without explicit acknowledgment.
     exit_signal: flagged
   3:
     id: E3