agentera 3.0.0-dev.2 → 3.0.0-dev.21

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

@@ -11,13 +11,13 @@ Canonical scale: **0-100 integer**.
 
 Five tiers with shared boundaries. Each skill defines its own domain-specific labels describing what the tier means in its context.
 
-| Tier | Range | Semantic |
-|------|-------|----------|
-| 1 (highest) | 90-100 | Verified / near-certain |
-| 2 | 70-89 | Strong evidence / established |
-| 3 | 50-69 | Moderate evidence / emerging |
-| 4 | 30-49 | Weak evidence / uncertain |
-| 5 (lowest) | 0-29 | Speculative / extrapolated |
+| Tier        | Range  | Semantic                      |
+| ----------- | ------ | ----------------------------- |
+| 1 (highest) | 90-100 | Verified / near-certain       |
+| 2           | 70-89  | Strong evidence / established |
+| 3           | 50-69  | Moderate evidence / emerging  |
+| 4           | 30-49  | Weak evidence / uncertain     |
+| 5 (lowest)  | 0-29   | Speculative / extrapolated    |
 
 **Rules**:
 
@@ -36,32 +36,32 @@ Two severity vocabularies serve different purposes in the suite.
 
 Used by skills that produce audit findings (inspektera, dokumentera, visualisera).
 
-| Level | Meaning |
-|-------|---------|
+| Level        | Meaning                                              |
+| ------------ | ---------------------------------------------------- |
 | **critical** | Broken functionality, security issue, data loss risk |
-| **warning** | Works but poorly: fragile, confusing, or degraded |
-| **info** | Minor: cosmetic, style, low-impact improvement |
+| **warning**  | Works but poorly: fragile, confusing, or degraded    |
+| **info**     | Minor: cosmetic, style, low-impact improvement       |
 
 ### Issue severity (TODO.md)
 
 Used by all skills that file to TODO.md.
 
-| Level | Glyph | Meaning |
-|-------|-------|---------|
-| **critical** | ⇶ | Broken functionality, blocks progress |
-| **degraded** | ⇉ | Works but poorly: slow, fragile, ugly |
-| **normal** | → | Standard work: features, improvements, routine tasks |
-| **annoying** | ⇢ | Cosmetic, minor friction, style nit |
+| Level        | Glyph | Meaning                                              |
+| ------------ | ----- | ---------------------------------------------------- |
+| **critical** | ⇶     | Broken functionality, blocks progress                |
+| **degraded** | ⇉     | Works but poorly: slow, fragile, ugly                |
+| **normal**   | →     | Standard work: features, improvements, routine tasks |
+| **annoying** | ⇢     | Cosmetic, minor friction, style nit                  |
 
 ### Mapping
 
 When filing audit findings to TODO.md, map as follows:
 
-| Finding severity | → | Issue severity |
-|-----------------|---|----------------|
-| critical | → | critical |
-| warning | → | degraded or normal |
-| info | → | annoying |
+| Finding severity | →   | Issue severity     |
+| ---------------- | --- | ------------------ |
+| critical         | →   | critical           |
+| warning          | →   | degraded or normal |
+| info             | →   | annoying           |
 
 ### TODO.md format convention
 
@@ -71,24 +71,29 @@ TODO.md uses a conventional checkbox format grouped by severity. Skills write it
 # TODO
 
 ## ⇶ Critical
-- [ ] ISS-N: [type] Description
+
+- [ ] [type:train] Description
 
 ## ⇉ Degraded
-- [ ] ISS-N: [type] Description
+
+- [ ] [type:train] Description
 
 ## → Normal
-- [ ] ISS-N: [type] Description
+
+- [ ] [type:train] Description
 
 ## ⇢ Annoying
-- [ ] ISS-N: [type] Description
 
-## Resolved
-- [x] ~~ISS-N: [type] Description~~ · resolved in commit hash
+- [ ] [type:train] Description
+
+## ✓ Resolved
+
+- [x] [type:train] Description · resolved in commit hash
 ```
 
-Type tags use the conventional commit vocabulary: feat, fix, docs, refactor, chore, test, perf.
+Type tags use the conventional commit vocabulary: feat, fix, docs, refactor, chore, test, perf. An optional train scope in `[type:train]` form marks work targeting a specific release train, e.g. `- [ ] [fix:train]`.
 
-The severity vocabulary (critical/degraded/annoying) is preserved as section headings with severity glyphs. Checkboxes indicate completion state. Resolved items move to the Resolved section with strikethrough and commit reference.
+The severity vocabulary (critical/degraded/annoying) is preserved as section headings with severity glyphs. Checkboxes indicate completion state. Resolved items move to `## ✓ Resolved` with `- [x]` and a commit reference.
 
 **Linter check**: Deterministic. Exact string matching for severity terms in context.
 
@@ -96,11 +101,11 @@ The severity vocabulary (critical/degraded/annoying) is preserved as section hea
 
 Used in DECISIONS.md entries (produced by resonera, consumed by realisera, planera, inspektera, profilera).
 
-| Label | Meaning | How consuming skills treat it |
-|-------|---------|-------------------------------|
-| **firm** | User is committed | Treat as a hard constraint |
-| **provisional** | Best current answer, open to revision | Treat as a strong default |
-| **exploratory** | Direction to try, expected to be revisited | Treat as a suggestion |
+| Label           | Meaning                                    | How consuming skills treat it |
+| --------------- | ------------------------------------------ | ----------------------------- |
+| **firm**        | User is committed                          | Treat as a hard constraint    |
+| **provisional** | Best current answer, open to revision      | Treat as a strong default     |
+| **exploratory** | Direction to try, expected to be revisited | Treat as a suggestion         |
 
 **Linter check**: Deterministic. Enum values in DECISIONS.md format definition.
 
@@ -114,44 +119,44 @@ Three project-facing files at the project root; nine operational files in `.agen
 
 **Root (project-facing)**:
 
-| File | Purpose |
-|------|---------|
-| VISION.md | Project north star |
-| TODO.md | Actionable items with priority and checkboxes |
+| File         | Purpose                                           |
+| ------------ | ------------------------------------------------- |
+| VISION.md    | Project north star                                |
+| TODO.md      | Actionable items with priority and checkboxes     |
 | CHANGELOG.md | Version-level change summaries (keep-a-changelog) |
 
 **.agentera/ (operational)**:
 
-| File | Purpose |
-|------|---------|
-| PROGRESS.md | Cycle-by-cycle operational log |
-| DECISIONS.md | Reasoning trail |
-| PLAN.md | Active work plan |
-| HEALTH.md | Audit grades and findings |
-| OBJECTIVE.md | Optimization target (per-objective, under `.agentera/optimera/<name>/`) |
-| EXPERIMENTS.md | Experiment log (per-objective, under `.agentera/optimera/<name>/`) |
-| DESIGN.md | Visual identity |
-| DOCS.md | Documentation contract + optional artifact path overrides |
-| archive/ | Completed plans, superseded visions and designs |
+| File           | Purpose                                                                 |
+| -------------- | ----------------------------------------------------------------------- |
+| PROGRESS.md    | Cycle-by-cycle operational log                                          |
+| DECISIONS.md   | Reasoning trail                                                         |
+| PLAN.md        | Active work plan                                                        |
+| HEALTH.md      | Audit grades and findings                                               |
+| OBJECTIVE.md   | Optimization target (per-objective, under `.agentera/optimera/<name>/`) |
+| EXPERIMENTS.md | Experiment log (per-objective, under `.agentera/optimera/<name>/`)      |
+| DESIGN.md      | Visual identity                                                         |
+| DOCS.md        | Documentation contract + optional artifact path overrides               |
+| archive/       | Completed plans, superseded visions and designs                         |
 
-**PROFILE.md** is global. Profilera determines the platform-appropriate data directory: `$PROFILERA_PROFILE_DIR/PROFILE.md` (defaulting to `$XDG_DATA_HOME/agentera/PROFILE.md` on Linux, `~/Library/Application Support/agentera/PROFILE.md` on macOS, `%APPDATA%/agentera/PROFILE.md` on Windows). <!-- platform: profile-path --> Skills read it from the profilera-determined path directly. PROFILERA_PROFILE_DIR is the sibling of AGENTERA_HOME (Section 7): both are adapter-injected env vars. PROFILERA_PROFILE_DIR scopes to profile data; AGENTERA_HOME scopes to the Agentera app home. User data such as PROFILE.md, USAGE.md, history, and intermediate corpus data stays at the app-home root; managed app code lives separately under `$AGENTERA_HOME/app`.
+**PROFILE.md** is global. Profilera determines the platform-appropriate data directory: `$AGENTERA_PROFILE_DIR/PROFILE.md` (defaulting to `$XDG_DATA_HOME/agentera/PROFILE.md` on Linux, `~/Library/Application Support/agentera/PROFILE.md` on macOS, `%APPDATA%/agentera/PROFILE.md` on Windows). <!-- platform: profile-path --> Skills read it from the profilera-determined path directly. AGENTERA_PROFILE_DIR is the sibling of AGENTERA_HOME (Section 7): both are adapter-injected env vars. AGENTERA_PROFILE_DIR scopes to profile data; AGENTERA_HOME scopes to the Agentera app home. User data such as PROFILE.md, USAGE.md, history, and intermediate corpus data stays at the app-home root; managed app code lives separately under `$AGENTERA_HOME/app`.
 
 ### Format contracts
 
-| Artifact | Path | Producer | Consumers | Key structural elements |
-|----------|------|----------|-----------|------------------------|
-| VISION.md | .agentera/vision.yaml | visionera, realisera | realisera, planera, inspektera, dokumentera, visualisera, orkestrera | north_star, personas, principles, direction, identity |
-| TODO.md | TODO.md | realisera, inspektera | realisera, planera, orkestrera | ## ⇶ Critical, ## ⇉ Degraded, ## → Normal, ## ⇢ Annoying, ## Resolved |
-| 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** |
-| 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** |
-| DESIGN.md | DESIGN.md | visualisera | realisera, visionera | Standard design sections with embedded `design:` YAML blocks |
-| DOCS.md | .agentera/docs.yaml | dokumentera | all skills (path resolution) | conventions, mapping, index |
-| PROFILE.md | (profile-path capability) <!-- platform: profile-path --> | profilera | all skills (directly when present) | ## Category, ### Decision, inline conf metadata |
+| Artifact       | Path                                                      | Producer              | Consumers                                                            | Key structural elements                                                                                           |
+| -------------- | --------------------------------------------------------- | --------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| VISION.md      | .agentera/vision.yaml                                     | visionera, realisera  | realisera, planera, inspektera, dokumentera, visualisera, orkestrera | north_star, personas, principles, direction, identity                                                             |
+| TODO.md        | TODO.md                                                   | realisera, inspektera | realisera, planera, orkestrera                                       | ## ⇶ Critical, ## ⇉ Degraded, ## → Normal, ## ⇢ Annoying, ## ✓ Resolved                                           |
+| 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/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** |
+| DESIGN.md      | DESIGN.md                                                 | visualisera           | realisera, visionera                                                 | Standard design sections with embedded `design:` YAML blocks                                                      |
+| DOCS.md        | .agentera/docs.yaml                                       | dokumentera           | all skills (path resolution)                                         | conventions, mapping, index                                                                                       |
+| PROFILE.md     | (profile-path capability) <!-- platform: profile-path --> | profilera             | all skills (directly when present)                                   | ## Category, ### Decision, inline conf metadata                                                                   |
 
 **Dual-write**: realisera writes both CHANGELOG.md (public, version-level summaries for project contributors) AND `.agentera/progress.yaml` (operational cycle-level detail for consuming skills). Consuming skills that need cycle detail read `.agentera/progress.yaml`; project contributors read CHANGELOG.md.
 
@@ -163,17 +168,17 @@ Three project-facing files at the project root; nine operational files in `.agen
 
 Inspektera assesses codebases across these dimensions, selecting applicable ones per audit. Each dimension produces an A-F grade, confidence-scored findings, and trend tracking.
 
-| Dimension | What it evaluates |
-|-----------|-------------------|
-| Architecture alignment | Code vs stated architecture: pattern mismatches, boundary violations, layering breaks |
-| Pattern consistency | Naming, error handling, structure, abstractions used consistently |
-| Coupling health | Hidden dependencies, circular imports, god modules, inappropriate intimacy |
-| Complexity hotspots | Long functions, deep nesting, high fan-out, accumulated conditionals |
-| Test health | Coverage gaps, test quality, test-to-code ratio, behavior vs implementation testing |
-| Dependency health | Outdated deps, security advisories, unused deps, pinning discipline |
-| Version health | Unreleased feat/fix commits since last version bump |
-| Artifact freshness | State artifacts current relative to plan activity or recent development |
-| Security hygiene | Hardcoded secrets, dangerous function calls, basic injection patterns (lightweight regex scan; recommends dedicated tools for comprehensive analysis) |
+| Dimension              | What it evaluates                                                                                                                                     |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Architecture alignment | Code vs stated architecture: pattern mismatches, boundary violations, layering breaks                                                                 |
+| Pattern consistency    | Naming, error handling, structure, abstractions used consistently                                                                                     |
+| Coupling health        | Hidden dependencies, circular imports, god modules, inappropriate intimacy                                                                            |
+| Complexity hotspots    | Long functions, deep nesting, high fan-out, accumulated conditionals                                                                                  |
+| Test health            | Coverage gaps, test quality, test-to-code ratio, behavior vs implementation testing                                                                   |
+| Dependency health      | Outdated deps, security advisories, unused deps, pinning discipline                                                                                   |
+| Version health         | Unreleased feat/fix commits since last version bump                                                                                                   |
+| Artifact freshness     | State artifacts current relative to plan activity or recent development                                                                               |
+| Security hygiene       | Hardcoded secrets, dangerous function calls, basic injection patterns (lightweight regex scan; recommends dedicated tools for comprehensive analysis) |
 
 ### CHANGELOG.md format convention
 
@@ -185,17 +190,21 @@ CHANGELOG.md follows the [Keep a Changelog](https://keepachangelog.com/) convent
 ## [Unreleased]
 
 ### Added
+
 - description
 
 ### Changed
+
 - description
 
 ### Fixed
+
 - description
 
 ## [version] · YYYY-MM-DD
 
 ### Added
+
 - description
 ```
 
@@ -207,22 +216,22 @@ Realisera appends entries under `## [Unreleased]` in the appropriate subsection
 
 Per-artifact word limits. Producing skills check approximate word count before writing. If a write would exceed the budget, compact first (see Compaction thresholds below).
 
-| Artifact | Scope | Budget |
-|----------|-------|--------|
-| PROGRESS.md | Per-cycle entry | ≤500 words |
-| PROGRESS.md | Full file | ≤3,000 words |
-| EXPERIMENTS.md | Per-experiment entry | ≤300 words |
-| EXPERIMENTS.md | Full file | ≤2,500 words |
-| HEALTH.md | Per-dimension assessment | ≤150 words |
-| HEALTH.md | Full file | ≤2,000 words |
-| DECISIONS.md | Per-decision entry | ≤200 words |
-| TODO.md | Per-item entry | ≤100 words |
-| CHANGELOG.md | Per-version section | ≤300 words |
-| PLAN.md | Per-task entry | ≤100 words |
-| PLAN.md | Full file | ≤2,500 words |
-| VISION.md | Full file | ≤1,500 words |
-| DESIGN.md | Full file | ≤2,000 words |
-| DOCS.md | Full file | ≤2,000 words |
+| Artifact       | Scope                    | Budget       |
+| -------------- | ------------------------ | ------------ |
+| PROGRESS.md    | Per-cycle entry          | ≤500 words   |
+| PROGRESS.md    | Full file                | ≤3,000 words |
+| EXPERIMENTS.md | Per-experiment entry     | ≤300 words   |
+| EXPERIMENTS.md | Full file                | ≤2,500 words |
+| HEALTH.md      | Per-dimension assessment | ≤150 words   |
+| HEALTH.md      | Full file                | ≤2,000 words |
+| DECISIONS.md   | Per-decision entry       | ≤200 words   |
+| TODO.md        | Per-item entry           | ≤100 words   |
+| CHANGELOG.md   | Per-version section      | ≤300 words   |
+| PLAN.md        | Per-task entry           | ≤100 words   |
+| PLAN.md        | Full file                | ≤2,500 words |
+| VISION.md      | Full file                | ≤1,500 words |
+| DESIGN.md      | Full file                | ≤2,000 words |
+| DOCS.md        | Full file                | ≤2,000 words |
 
 Budgets are guidelines, not hard blockers. A 510-word cycle entry is fine; a 1,200-word entry signals the write step lacks output constraints.
 
@@ -230,54 +239,74 @@ Budgets are guidelines, not hard blockers. A 510-word cycle entry is fine; a 1,2
 
 Artifacts store judgments, intent, reasoning, and context that would be lost without them: the non-derivable residue. Do not duplicate state retrievable from the project's files or history with a deterministic command.
 
-| Exclude from artifacts | Retrieve from |
-|------------------------|---------------|
-| Files modified in a cycle | `git log --stat` |
-| Function signatures from audits | `Grep` against source code |
-| Dependency versions | Manifest files (package.json, go.mod, etc.) |
-| Lines of code per module | `wc -l` or Glob + Read |
-| Code snippets in PROGRESS.md | Commit diffs (`git show`) |
-| Test names enumerated in findings | `Grep` against test files |
+| Exclude from artifacts            | Retrieve from                               |
+| --------------------------------- | ------------------------------------------- |
+| Files modified in a cycle         | `git log --stat`                            |
+| Function signatures from audits   | `Grep` against source code                  |
+| Dependency versions               | Manifest files (package.json, go.mod, etc.) |
+| Lines of code per module          | `wc -l` or Glob + Read                      |
+| Code snippets in PROGRESS.md      | Commit diffs (`git show`)                   |
+| Test names enumerated in findings | `Grep` against test files                   |
 
 The test: if a reader can reconstruct the information from the project's current state or git history, it does not belong in the artifact.
 
 ### Compaction thresholds
 
-Growing artifacts are compacted to cap read cost for consuming skills. Compaction runs when the producing skill writes a new entry. All growing artifacts follow a uniform 10/40/50 rule: 10 full-detail entries, 40 one-line archive entries, drop beyond 50 total.
+Numbered state artifacts use `uniform_10_40_50` as projection capacity to cap
+read cost for consuming skills: 10 active full-detail entries and 40 archive
+projection entries. These are bounded active/archive projections, not retention
+or deletion limits. Verified numbered archives remain authoritative; projection
+compaction performs no destructive deletion. Recovery refuses to omit entries
+when archive evidence is missing and retains full entries with metadata.
+Compaction runs when the producing skill writes a new entry. Other artifacts
+retain their owning artifact-specific compaction rules below.
 
 **CHANGELOG.md is exempt**: it is the public version-level history and is not compacted.
 
 **PROGRESS.md**, compacted by realisera when writing a new cycle entry:
 
-| Tier | Entries | Format |
-|------|---------|--------|
-| Full detail | 10 most recent cycles | Standard cycle entry format |
-| One-line archive | Cycles 11 through 50 | `Cycle N (YYYY-MM-DD): ≤15-word summary` |
-| Dropped | Cycles older than 50 | Removed entirely |
+| Tier                | Entries               | Format                                   |
+| ------------------- | --------------------- | ---------------------------------------- |
+| Active full detail  | 10 most recent cycles | Standard cycle entry format              |
+| Archive projection  | Cycles 11 through 50  | `Cycle N (YYYY-MM-DD): ≤15-word summary` |
+| Outside projection  | Older cycles          | Omission metadata; numbered archive      |
 
-When writing a new cycle: if >10 full-detail entries exist, collapse the oldest to one-line format under an `## Archived Cycles` heading (below the recent cycles). If >40 one-line entries exist, drop the oldest. One-line summaries preserve cycle number, date, and work-type, enough for trend analysis by consuming skills.
+When writing a new cycle: if >10 full-detail entries exist and their numbered
+archives verify, collapse the oldest to one-line format under an `## Archived
+Cycles` heading (below the recent cycles). If >40 one-line entries exist, omit
+the oldest from this bounded projection with metadata; if archive evidence is
+missing, retain the full entry and refuse the projection change. One-line
+summaries preserve cycle number, date, and work-type, enough for trend analysis
+by consuming skills.
 
-Active cycle entries are stored newest-first: descending by cycle number. Insert the newest full-detail cycle before older active cycles so `agentera progress --limit 1` reads the current cycle without scanning the full file.
+Active cycle entries are stored newest-first: descending by cycle number. Insert the newest full-detail cycle before older active cycles so `agentera state progress list --limit 1 --format json` reads the current cycle through the bounded state interface.
 
 **EXPERIMENTS.md**, compacted by optimera when writing a new experiment:
 
-| Tier | Entries | Format |
-|------|---------|--------|
-| Full detail | 10 most recent experiments | Standard experiment entry format |
-| One-line archive | Experiments 11 through 50 | `EXP-N: ≤15-word result summary` |
-| Dropped | Experiments older than 50 | Removed entirely |
+| Tier             | Entries                    | Format                           |
+| ---------------- | -------------------------- | -------------------------------- |
+| Full detail      | 10 most recent experiments | Standard experiment entry format |
+| One-line archive | Experiments 11 through 50  | `EXP-N: ≤15-word result summary` |
+| Dropped          | Experiments older than 50  | Removed entirely                 |
 
-Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest one-line when >40 one-line entries exist. Archive section sits below recent experiments under an `## Archived Experiments` heading.
+Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest
+one-line when >40 one-line entries exist. Archive section sits below recent
+experiments under an `## Archived Experiments` heading.
 
 **DECISIONS.md**, compacted by resonera when writing a new decision:
 
-| Tier | Entries | Format |
-|------|---------|--------|
-| Full detail | 10 most recent decisions | Standard decision entry format |
-| One-line archive | Decisions 11 through 50 | `Decision N (YYYY-MM-DD): [Choice] — ≤15-word summary` |
-| Dropped | Decisions older than 50 | Removed entirely |
+| Tier                | Entries                  | Format                                                 |
+| ------------------- | ------------------------ | ------------------------------------------------------ |
+| Active full detail  | 10 most recent decisions | Standard decision entry format                         |
+| Archive projection  | Decisions 11 through 50  | `Decision N (YYYY-MM-DD): [Choice] — ≤15-word summary` |
+| Outside projection  | Older decisions          | Omission metadata; numbered archive                   |
 
-Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest one-line when >40 one-line entries exist. Archive section sits below recent decisions under an `## Archived Decisions` heading. One-line summaries preserve decision number, date, and the chosen alternative.
+Same logic: collapse oldest full-detail to one-line when >10 exist and their
+numbered archives verify. If >40 one-line entries exist, omit the oldest from
+this bounded projection with metadata; if archive evidence is missing, retain
+the full entry and refuse the projection change. Archive section sits below
+recent decisions under an `## Archived Decisions` heading. One-line summaries
+preserve decision number, date, and the chosen alternative.
 
 When writing a new decision, choose `N` as one greater than the highest decision number in active and archived entries. Insert the new full entry in the active section immediately before `## Archived Decisions`; if no archive exists, append it at the end of the file. Active decision entries must have unique numbers and remain ascending by decision number. Do not reuse or renumber decisions except when repairing artifact corruption.
 
@@ -285,23 +314,45 @@ When writing a new decision, choose `N` as one greater than the highest decision
 
 **HEALTH.md**, compacted by inspektera when writing a new audit:
 
-| Tier | Entries | Format |
-|------|---------|--------|
-| Full detail | 10 most recent audits | Standard audit entry format |
-| One-line archive | Audits 11 through 50 | `Audit N (YYYY-MM-DD): [grade] — ≤15-word summary` |
-| Dropped | Audits older than 50 | Removed entirely |
+| Tier                | Entries               | Format                                             |
+| ------------------- | --------------------- | -------------------------------------------------- |
+| Active full detail  | 10 most recent audits | Standard audit entry format                        |
+| Archive projection  | Audits 11 through 50  | `Audit N (YYYY-MM-DD): [grade] — ≤15-word summary` |
+| Outside projection  | Older audits          | Omission metadata; numbered archive                |
 
-Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest one-line when >40 one-line entries exist. Archive section sits below recent audits under an `## Archived Audits` heading. One-line summaries preserve audit number, date, overall grade, and trajectory.
+Same logic: collapse oldest full-detail to one-line when >10 exist and their
+numbered archives verify. If >40 one-line entries exist, omit the oldest from
+this bounded projection with metadata; if archive evidence is missing, retain
+the full entry and refuse the projection change. Archive section sits below
+recent audits under an `## Archived Audits` heading. One-line summaries preserve
+audit number, date, overall grade, and trajectory.
 
 **TODO.md Resolved section**, compacted by realisera when marking an item resolved:
 
-| Tier | Entries | Format |
-|------|---------|--------|
-| Full detail | 10 most recent resolved items | Standard resolved entry format |
-| One-line archive | Items 11 through 50 | `- [x] ~~[ISS-NN]: ≤15-word resolution summary~~` |
-| Dropped | Items older than 50 | Removed entirely |
-
-Same logic: collapse oldest full-detail to one-line when >10 exist. Drop oldest one-line when >40 one-line entries exist. Compaction applies only within the `## Resolved` section; active severity sections are not affected.
+| Tier             | Entries                       | Format                                           |
+| ---------------- | ----------------------------- | ------------------------------------------------ |
+| Full detail      | 10 most recent resolved items | Standard resolved entry format                   |
+| One-line summary | Items 11 through 50           | `- [x] [type:train] ≤15-word resolution summary` |
+| Dropped          | Items older than 50           | Removed entirely                                 |
+
+The first ten resolved rows are the recent/full-detail tier even when they have
+no indented body; rows 11 through 50 are the summary tier. Collapse the oldest
+full-detail entries to one line when more than 10 exist. Drop the oldest
+summaries when more than 40 exist. Compaction applies only within the
+`## ✓ Resolved` section; active severity sections are not affected.
+
+TODO.md is a **bounded human-facing queue, not a lossless numbered archive**.
+Unlike progress, decisions, and health—which preserve verified numbered archives
+and perform no destructive deletion—TODO compaction is intentionally destructive.
+Dropped resolved entries are removed from the working tree and are recoverable
+only for previously committed content through project history
+(`git log -p -- :/TODO.md`; the `:/` pathspec is project-root-safe). Non-Git
+projects have no historical recovery for dropped entries. Compaction diagnostics
+MUST report removed entries as `dropped` and MUST NOT describe TODO compaction as
+a lossless projection. Exactly one `## ✓ Resolved` section is permitted;
+parsing, validation, and compaction refuse with an actionable diagnostic when
+duplicates are present because parsing processes only the first section and
+otherwise hides trailing entries from the budget.
 
 ## 5. Artifact Path Resolution
 
@@ -340,7 +391,7 @@ Skills that read the decision profile use one of two patterns:
 ### Script pattern (for skills that need confidence-weighted summaries)
 
 ```
-Read `$PROFILERA_PROFILE_DIR/PROFILE.md` directly
+Read `$AGENTERA_PROFILE_DIR/PROFILE.md` directly
 ```
 
 Run from the profilera skill directory. Mentioned skills: realisera, optimera, inspektera, planera, inspirera.
@@ -352,14 +403,14 @@ Standard threshold language (after migration to 0-100):
 
 ### Direct read pattern (for skills that need qualitative profile context)
 
-Read PROFILE.md from the profilera-determined profile path (`$PROFILERA_PROFILE_DIR/PROFILE.md`, defaulting to `$XDG_DATA_HOME/agentera/PROFILE.md` on Linux). <!-- platform: profile-path --> Mentioned skills: resonera, visionera, dokumentera, visualisera.
+Read PROFILE.md from the profilera-determined profile path (`$AGENTERA_PROFILE_DIR/PROFILE.md`, defaulting to `$XDG_DATA_HOME/agentera/PROFILE.md` on Linux). <!-- platform: profile-path --> Mentioned skills: resonera, visionera, dokumentera, visualisera.
 
 Both patterns MUST include a fallback instruction:
 "If the script or PROFILE.md is missing, proceed without persona grounding."
 
 **Linter check**: Deterministic. Script invocation syntax, threshold values, fallback instruction presence.
 
-PROFILERA_PROFILE_DIR is the sibling of AGENTERA_HOME (Section 7): both are adapter-injected env vars, but they scope to different surfaces. PROFILERA_PROFILE_DIR names the profile data directory where PROFILE.md lives; AGENTERA_HOME names the Agentera app home. User data remains at the app-home root; helper scripts referenced by skill prose live in the managed app under `$AGENTERA_HOME/app`.
+AGENTERA_PROFILE_DIR is the sibling of AGENTERA_HOME (Section 7): both are adapter-injected env vars, but they scope to different surfaces. AGENTERA_PROFILE_DIR names the profile data directory where PROFILE.md lives; AGENTERA_HOME names the Agentera app home. User data remains at the app-home root; helper scripts referenced by skill prose live in the managed app under `$AGENTERA_HOME/app`.
 
 ## 11. Exit Signals
 
@@ -367,12 +418,12 @@ Every skill MUST report a completion status at the end of its workflow. This ena
 
 ### Statuses
 
-| Status | Meaning | When to use |
-|--------|---------|-------------|
-| **complete** | All steps completed successfully | The skill's workflow ran to completion and all acceptance criteria (if any) were met |
-| **flagged** | Completed, but with issues the user should know about | The workflow completed but discovered problems, made compromises, or has caveats worth surfacing |
-| **stuck** | Cannot proceed | A hard blocker prevents completion: missing dependency, permission issue, ambiguous requirement too consequential to resolve autonomously |
-| **waiting** | Missing information required to continue | The skill needs input, clarification, or a decision from the user or another skill before it can proceed |
+| Status       | Meaning                                               | When to use                                                                                                                               |
+| ------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **complete** | All steps completed successfully                      | The skill's workflow ran to completion and all acceptance criteria (if any) were met                                                      |
+| **flagged**  | Completed, but with issues the user should know about | The workflow completed but discovered problems, made compromises, or has caveats worth surfacing                                          |
+| **stuck**    | Cannot proceed                                        | A hard blocker prevents completion: missing dependency, permission issue, ambiguous requirement too consequential to resolve autonomously |
+| **waiting**  | Missing information required to continue              | The skill needs input, clarification, or a decision from the user or another skill before it can proceed                                  |
 
 ### Rules
 
@@ -401,20 +452,20 @@ DESIGN.md is the source of truth for token definitions. This spec defines how sk
 
 Each skill has a unique Unicode glyph used as a subtle signature in output.
 
-| Skill | Glyph | Code | Meaning |
-|-------|-------|------|---------|
-| hej | ⌂ | U+2302 | home base |
-| realisera | ⧉ | U+29C9 | joined building blocks |
-| inspektera | ⛶ | U+26F6 | viewfinder frame |
-| resonera | ❈ | U+2748 | spark of insight |
-| planera | ≡ | U+2261 | structured layers |
-| visionera | ⛥ | U+26E5 | guiding star |
-| optimera | ⎘ | U+2398 | measurement |
-| dokumentera | ▤ | U+25A4 | text on page |
-| profilera | ♾ | U+267E | permanent mark |
-| inspirera | ⬚ | U+2B1A | frame to fill |
-| visualisera | ◰ | U+25F0 | design grid |
-| orkestrera | ⎈ | U+2388 | helm, steering |
+| Skill       | Glyph | Code   | Meaning                |
+| ----------- | ----- | ------ | ---------------------- |
+| hej         | ⌂     | U+2302 | home base              |
+| realisera   | ⧉     | U+29C9 | joined building blocks |
+| inspektera  | ⛶     | U+26F6 | viewfinder frame       |
+| resonera    | ❈     | U+2748 | spark of insight       |
+| planera     | ≡     | U+2261 | structured layers      |
+| visionera   | ⛥     | U+26E5 | guiding star           |
+| optimera    | ⎘     | U+2398 | measurement            |
+| dokumentera | ▤     | U+25A4 | text on page           |
+| profilera   | ♾     | U+267E | permanent mark         |
+| inspirera   | ⬚     | U+2B1A | frame to fill          |
+| visualisera | ◰     | U+25F0 | design grid            |
+| orkestrera  | ⎈     | U+2388 | helm, steering         |
 
 ### Semantic tokens
 
@@ -422,46 +473,46 @@ Six token families express status, urgency, certainty, and direction.
 
 **Status** (task/item completion, square fill progression):
 
-| State | Glyph | Code |
-|-------|-------|------|
-| complete | ■ | U+25A0 |
-| in-progress | ▣ | U+25A3 |
-| open | □ | U+25A1 |
-| blocked | ▨ | U+25A8 |
+| State       | Glyph | Code   |
+| ----------- | ----- | ------ |
+| complete    | ■     | U+25A0 |
+| in-progress | ▣     | U+25A3 |
+| open        | □     | U+25A1 |
+| blocked     | ▨     | U+25A8 |
 
 **Severity** (issue priority, rightward arrows, more arrows = higher priority):
 
-| Level | Glyph | Code |
-|-------|-------|------|
-| critical | ⇶ | U+21F6 |
-| degraded | ⇉ | U+21C9 |
-| normal | → | U+2192 |
-| annoying | ⇢ | U+21E2 |
+| Level    | Glyph | Code   |
+| -------- | ----- | ------ |
+| critical | ⇶     | U+21F6 |
+| degraded | ⇉     | U+21C9 |
+| normal   | →     | U+2192 |
+| annoying | ⇢     | U+21E2 |
 
 **Confidence** (decision certainty, box-drawing line weight):
 
-| Level | Glyph | Code |
-|-------|-------|------|
-| firm | ━ | U+2501 |
-| provisional | ─ | U+2500 |
-| exploratory | ┄ | U+2504 |
+| Level       | Glyph | Code   |
+| ----------- | ----- | ------ |
+| firm        | ━     | U+2501 |
+| provisional | ─     | U+2500 |
+| exploratory | ┄     | U+2504 |
 
 **Trends** (direction of change):
 
-| Direction | Glyph | Code |
-|-----------|-------|------|
-| improving | ⮉ | U+2B89 |
-| degrading | ⮋ | U+2B8B |
+| Direction | Glyph | Code   |
+| --------- | ----- | ------ |
+| improving | ⮉     | U+2B89 |
+| degrading | ⮋     | U+2B8B |
 
 **Structural** (layout primitives):
 
-| Element | Glyph/Pattern | Code |
-|---------|---------------|------|
-| section divider | `─── label ───────` | U+2500 |
-| list item | ▸ | U+25B8 |
-| inline separator | · | U+00B7 |
-| flow / target | → | U+2192 |
-| progress bar | █▓░ | U+2588/2593/2591 |
+| Element          | Glyph/Pattern       | Code             |
+| ---------------- | ------------------- | ---------------- |
+| section divider  | `─── label ───────` | U+2500           |
+| list item        | ▸                   | U+25B8           |
+| inline separator | ·                   | U+00B7           |
+| flow / target    | →                   | U+2192           |
+| progress bar     | █▓░                 | U+2588/2593/2591 |
 
 ### Composition rules
 
@@ -478,11 +529,11 @@ Six token families express status, urgency, certainty, and direction.
 
 Three levels of visual dividers create a consistent hierarchy across skill output.
 
-| Level | Pattern | Use |
-|-------|---------|-----|
-| Skill boundary | `─── glyph skillname · context ───` | Session opener, exit signal |
-| Step boundary | `── step N/M: verb` | Workflow progress between steps |
-| Container | `── label` | Mid-session blocks (scratchpad, etc.) |
+| Level          | Pattern                             | Use                                   |
+| -------------- | ----------------------------------- | ------------------------------------- |
+| Skill boundary | `─── glyph skillname · context ───` | Session opener, exit signal           |
+| Step boundary  | `── step N/M: verb`                 | Workflow progress between steps       |
+| Container      | `── label`                          | Mid-session blocks (scratchpad, etc.) |
 
 Step and container dividers share the same visual weight (2-dash), differentiated by label content: step boundaries use `step N/M: verb`, containers use a descriptive label.
 
@@ -548,15 +599,15 @@ Rules:
 
 ### Token-to-artifact mapping
 
-| Artifact | Token families used |
-|----------|---------------------|
-| PLAN.md | Status (■/▣/□/▨) for task states |
-| TODO.md | Severity (⇶/⇉/→/⇢) in section headings, Status (□/■) via checkboxes |
-| DECISIONS.md | Confidence (━/─/┄) alongside confidence labels |
-| HEALTH.md | Trends (⮉/⮋) for trajectory, severity for findings |
-| PROGRESS.md | Status (■) for cycle completion markers |
-| VISION.md | Structural (▸, ·) for principles and direction |
-| DOCS.md | Structural (▸, ·) for index, status tokens for coverage |
+| Artifact     | Token families used                                                 |
+| ------------ | ------------------------------------------------------------------- |
+| PLAN.md      | Status (■/▣/□/▨) for task states                                    |
+| TODO.md      | Severity (⇶/⇉/→/⇢) in section headings, Status (□/■) via checkboxes |
+| DECISIONS.md | Confidence (━/─/┄) alongside confidence labels                      |
+| HEALTH.md    | Trends (⮉/⮋) for trajectory, severity for findings                  |
+| PROGRESS.md  | Status (■) for cycle completion markers                             |
+| VISION.md    | Structural (▸, ·) for principles and direction                      |
+| DOCS.md      | Structural (▸, ·) for index, status tokens for coverage             |
 
 ### Rules
 
@@ -574,25 +625,25 @@ Every realisera cycle operates in one of five phases. Phases map the suite's ski
 
 ### Phases
 
-| Phase | Skills | Purpose |
-|-------|--------|---------|
-| **envision** | visionera | Define or refine the project's north star |
-| **deliberate** | resonera | Reason through decisions before committing to a direction |
-| **plan** | planera | Structure work into tasks with dependencies and acceptance criteria |
-| **build** | realisera, optimera, dokumentera, visualisera | Implement, optimize, document, or design |
-| **audit** | inspektera | Evaluate structural health and alignment |
+| Phase          | Skills                                        | Purpose                                                             |
+| -------------- | --------------------------------------------- | ------------------------------------------------------------------- |
+| **envision**   | visionera                                     | Define or refine the project's north star                           |
+| **deliberate** | resonera                                      | Reason through decisions before committing to a direction           |
+| **plan**       | planera                                       | Structure work into tasks with dependencies and acceptance criteria |
+| **build**      | realisera, optimera, dokumentera, visualisera | Implement, optimize, document, or design                            |
+| **audit**      | inspektera                                    | Evaluate structural health and alignment                            |
 
 ### Transitions
 
 Phases have valid successors. A cycle's phase is determined by the primary skill performing work, not by the phase of the previous cycle (phases are not a strict pipeline).
 
-| From | Valid successors |
-|------|-----------------|
-| envision | deliberate, plan, build |
-| deliberate | plan, build, envision |
-| plan | build, deliberate |
-| build | build, audit, plan |
-| audit | build, plan, deliberate, envision |
+| From       | Valid successors                  |
+| ---------- | --------------------------------- |
+| envision   | deliberate, plan, build           |
+| deliberate | plan, build, envision             |
+| plan       | build, deliberate                 |
+| build      | build, audit, plan                |
+| audit      | build, plan, deliberate, envision |
 
 **Terminal states**: audit and build are terminal in the sense that a project can remain in either phase indefinitely (continuous building, periodic auditing). envision, deliberate, and plan are transitional: they produce artifacts consumed by downstream phases.
 
@@ -622,20 +673,20 @@ Stale artifacts mislead routing decisions and cause skills to act on outdated co
 
 Each skill produces specific artifacts as part of its workflow. When a skill is dispatched (directly or via orkestrera), the artifacts listed here are the ones it is expected to have updated upon completion. This table is the authoritative lookup for staleness checks.
 
-| Skill | Expected artifact outputs |
-|-------|--------------------------|
-| visionera | .agentera/vision.yaml |
-| resonera | .agentera/decisions.yaml |
-| planera | .agentera/plan.yaml |
-| realisera | .agentera/progress.yaml, TODO.md, CHANGELOG.md |
-| optimera | .agentera/optimera/<name>/experiments.yaml, .agentera/optimera/<name>/objective.yaml (paths are per-objective; staleness check uses glob `.agentera/optimera/*/experiments.yaml` and `.agentera/optimera/*/objective.yaml`) |
-| inspektera | .agentera/health.yaml, TODO.md |
-| dokumentera | .agentera/docs.yaml |
-| visualisera | DESIGN.md |
-| profilera | (profile-path capability) <!-- platform: profile-path --> |
-| inspirera | (no owned artifact; findings are filed to TODO.md or fed into other skills) |
-| orkestrera | (orchestrator; updates .agentera/plan.yaml task statuses and delegates to other skills) |
-| hej | (router; reads artifacts but produces none) |
+| Skill       | Expected artifact outputs                                                                                                                                                                                                   |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| visionera   | .agentera/vision.yaml                                                                                                                                                                                                       |
+| resonera    | .agentera/decisions.yaml                                                                                                                                                                                                    |
+| planera     | .agentera/plan.yaml                                                                                                                                                                                                         |
+| realisera   | .agentera/progress.yaml, TODO.md, CHANGELOG.md                                                                                                                                                                              |
+| optimera    | .agentera/optimera/<name>/experiments.yaml, .agentera/optimera/<name>/objective.yaml (paths are per-objective; staleness check uses glob `.agentera/optimera/*/experiments.yaml` and `.agentera/optimera/*/objective.yaml`) |
+| inspektera  | .agentera/health.yaml, TODO.md                                                                                                                                                                                              |
+| dokumentera | .agentera/docs.yaml                                                                                                                                                                                                         |
+| visualisera | DESIGN.md                                                                                                                                                                                                                   |
+| profilera   | (profile-path capability) <!-- platform: profile-path -->                                                                                                                                                                   |
+| inspirera   | (no owned artifact; findings are filed to TODO.md or fed into other skills)                                                                                                                                                 |
+| orkestrera  | (orchestrator; updates .agentera/plan.yaml task statuses and delegates to other skills)                                                                                                                                     |
+| hej         | (router; reads artifacts but produces none)                                                                                                                                                                                 |
 
 Skills that share an artifact (e.g., realisera and inspektera both write to TODO.md) are each expected to update it independently when dispatched. Staleness is checked per-skill, not per-artifact.
 
@@ -669,13 +720,13 @@ 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 |
-|-------|---------|
-| Observed output | A short transcript (or summary) of the primary entrypoint running against real project state, with the observable result recorded verbatim. The transcript should be concrete enough that a reader can tell whether the behavior actually happened |
-| Allowlisted N/A tag | `N/A: <tag>` where `<tag>` is drawn from the enumerated allowlist below |
-| Free-form N/A rationale | A prose sentence of at least 8 words explaining specifically why the change has no observable behavior. Shorter rationales fail the gate |
+| Shape                   | Content                                                                                                                                                                                                                                            |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Observed output         | A short transcript (or summary) of the primary entrypoint running against real project state, with the observable result recorded verbatim. The transcript should be concrete enough that a reader can tell whether the behavior actually happened |
+| Allowlisted N/A tag     | `N/A: <tag>` where `<tag>` is drawn from the enumerated allowlist below                                                                                                                                                                            |
+| Free-form N/A rationale | A prose sentence of at least 8 words explaining specifically why the change has no observable behavior. Shorter rationales fail the gate                                                                                                           |
 
 Observed output is always preferred when the change is runnable. The N/A paths exist only for genuinely unrunnable work; they are not an escape hatch for "I didn't feel like running it."
 
@@ -683,13 +734,13 @@ Observed output is always preferred when the change is runnable. The N/A paths e
 
 Exactly five tags are recognized. Any other shorthand must fall through to the free-form rationale path.
 
-| Tag | Meaning |
-|-----|---------|
-| `docs-only` | The change touched only documentation files (README, spec, skill instructions, templates) with no code path affected |
+| Tag                           | Meaning                                                                                                                     |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `docs-only`                   | The change touched only documentation files (README, spec, skill instructions, templates) with no code path affected        |
 | `refactor-no-behavior-change` | The change restructured code but preserved observable behavior exactly; the existing test suite is the verification surface |
-| `chore-dep-bump` | The change updated a dependency version without modifying any project code that calls that dependency differently |
-| `chore-build-config` | The change modified build tooling, linter configuration, or packaging metadata without altering runtime behavior |
-| `test-only` | The change added or adjusted tests without modifying the code under test |
+| `chore-dep-bump`              | The change updated a dependency version without modifying any project code that calls that dependency differently           |
+| `chore-build-config`          | The change modified build tooling, linter configuration, or packaging metadata without altering runtime behavior            |
+| `test-only`                   | The change added or adjusted tests without modifying the code under test                                                    |
 
 A cycle that bundles runnable work with an N/A-tagged change still requires observed output for the runnable portion. The tag covers only the non-runnable slice.
 
@@ -697,14 +748,14 @@ A cycle that bundles runnable work with an N/A-tagged change still requires obse
 
 "Primary entrypoint" is defined per project archetype, not asserted per cycle. When a cycle touches multiple subsystems, the primary entrypoint is the one most closely tied to the change under verification.
 
-| Archetype | Canonical entrypoint form |
-|-----------|---------------------------|
-| CLI tool | Invoke the binary with realistic arguments that exercise the changed path, capturing stdout/stderr and exit code |
-| Library / SDK | Run a smoke driver (a short script or REPL session) that exercises the public API surface touched by the change |
-| Web service | Send a request to a production-shaped endpoint (local server with production configuration or a staging instance) and record the response |
-| Skill repo | Dispatch the skill via the eval mechanism capability (Section 21) against a representative prompt and capture the observed skill output <!-- platform: eval-mechanism --> |
-| Design system | Render a representative component against the real design tokens and visually inspect (screenshot or DOM snapshot) against the expected output |
-| Data pipeline | Run the pipeline against a real input sample (not synthetic fixtures) and record the observed output or side effects |
+| Archetype     | Canonical entrypoint form                                                                                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CLI tool      | Invoke the binary with realistic arguments that exercise the changed path, capturing stdout/stderr and exit code                                                          |
+| Library / SDK | Run a smoke driver (a short script or REPL session) that exercises the public API surface touched by the change                                                           |
+| Web service   | Send a request to a production-shaped endpoint (local server with production configuration or a staging instance) and record the response                                 |
+| Skill repo    | Dispatch the skill via the eval mechanism capability (Section 21) against a representative prompt and capture the observed skill output <!-- platform: eval-mechanism --> |
+| Design system | Render a representative component against the real design tokens and visually inspect (screenshot or DOM snapshot) against the expected output                            |
+| Data pipeline | Run the pipeline against a real input sample (not synthetic fixtures) and record the observed output or side effects                                                      |
 
 Projects with an archetype not listed here document their canonical entrypoint form in `.agentera/docs.yaml` under a `verification_entrypoint` key. The taxonomy is extensible; the table above is the minimum coverage.
 
@@ -720,9 +771,9 @@ Projects without a `verification_budget` key have no time cap. The default is: t
 
 The gate is enforced independently by two skills; each holds a different phase and a different slice of the enforcement contract.
 
-| Skill | Role | Phase | What it enforces |
-|-------|------|-------|------------------|
-| realisera | Primary enforcer | Cycle close | Runs the primary entrypoint against real project state and writes the observed output into the cycle's `verified` field. Blocks cycle completion if the field cannot be populated with observed output, an allowlisted tag, or a qualifying free-form rationale |
+| Skill      | Role               | Phase           | What it enforces                                                                                                                                                                                                                                                                                                                                                  |
+| ---------- | ------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| realisera  | Primary enforcer   | Cycle close     | Runs the primary entrypoint against real project state and writes the observed output into the cycle's `verified` field. Blocks cycle completion if the field cannot be populated with observed output, an allowlisted tag, or a qualifying free-form rationale                                                                                                   |
 | orkestrera | Secondary enforcer | Task evaluation | Reads the latest PROGRESS.md cycle entry for the delegated task, confirms the `verified` field is present and non-empty (artifact read only; no source code read), and extends its inspektera delegation prompt to include the Section 20 evidence-format snippet so inspektera audits whether the recorded content corresponds to the task's acceptance criteria |
 
 Realisera holds the primary enforcement contract because it is the skill that actually produces cycle entries. Orkestrera holds a lighter presence-and-quality check because it reads artifacts but never touches code; the full content audit is delegated to inspektera via the delegation prompt.
@@ -731,9 +782,16 @@ Realisera holds the primary enforcement contract because it is the skill that ac
 
 ## 22. Session Corpus Contract
 
-Profilera mines decision patterns from host session data to produce PROFILE.md. The extraction currently depends on Claude Code's internal storage layout (JSONL files, memory directories, project-scoped configs). This section defines the normalized data model that any host adapter can produce, decoupling profilera's behavioral contract from a specific runtime's file layout.
+Profilera mines decision patterns from host session data to produce PROFILE.md.
+Claude-specific entries in this legacy section describe the retired,
+consent-gated historical importer only. They are inactive, excluded from default
+analytics, and do not define runtime support. This section defines the normalized
+data model that any active host adapter or explicit historical importer can produce.
 
-The contract is a data model, not a path model. It specifies what profilera needs to observe, not where the host stores it. Claude Code continues to derive this corpus from its native paths; other runtimes produce the same normalized records from their own storage.
+The contract is a data model, not a path model. It specifies what profilera needs
+to observe, not where the host stores it. Active runtimes produce normalized
+records from their own storage; the retired Claude parser runs only after explicit
+historical-import consent.
 
 ### Record types
 
@@ -743,17 +801,17 @@ Four canonical record families capture the decision-relevant signals profilera c
 
 Every record includes these fields regardless of type:
 
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `source_id` | Yes | string | Stable identifier for deduplication across extractions |
-| `timestamp` | Yes | string (ISO 8601) | When the record was created or observed |
-| `project_id` | Yes | string | Project this record belongs to; `"global"` for non-project-scoped data |
-| `project_path` | No | string | Filesystem path to the project, when available |
-| `session_id` | No | string | Host session identifier, when applicable |
-| `source_kind` | Yes | string | Which record family this record belongs to (one of the four portable names below, or a runtime extension name) |
-| `runtime` | Yes | string | Host runtime that produced this record (e.g., `"claude-code"`, `"opencode"`) |
-| `adapter_version` | Yes | string | Version of the adapter that extracted this record |
-| `data` | Yes | object | Type-specific payload for this record |
+| Field             | Required | Type              | Purpose                                                                                                        |
+| ----------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| `source_id`       | Yes      | string            | Stable identifier for deduplication across extractions                                                         |
+| `timestamp`       | Yes      | string (ISO 8601) | When the record was created or observed                                                                        |
+| `project_id`      | Yes      | string            | Project this record belongs to; `"global"` for non-project-scoped data                                         |
+| `project_path`    | No       | string            | Filesystem path to the project, when available                                                                 |
+| `session_id`      | No       | string            | Host session identifier, when applicable                                                                       |
+| `source_kind`     | Yes      | string            | Which record family this record belongs to (one of the four portable names below, or a runtime extension name) |
+| `runtime`         | Yes      | string            | Host runtime that produced this record (e.g., `"claude-code"`, `"opencode"`)                                   |
+| `adapter_version` | Yes      | string            | Version of the adapter that extracted this record                                                              |
+| `data`            | Yes      | object            | Type-specific payload for this record                                                                          |
 
 The `source_id` field enables idempotent re-extraction: the same logical record produces the same `source_id` regardless of when extraction runs. The `runtime` and `adapter_version` fields enable profilera to handle schema variations across runtimes.
 
@@ -763,13 +821,13 @@ All fields listed in the record family tables below live inside `data`, not besi
 
 Global or project-scoped instruction files the host exposes to agents. These encode recurring preferences, constraints, and standards.
 
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `doc_type` | Yes | string | Kind of instruction document (e.g., `"claude_md"`, `"agents_md"`) |
-| `name` | Yes | string | Canonical name for this document |
-| `description` | No | string | Human-readable summary |
-| `content` | Yes | string | Full text content |
-| `scope` | Yes | string | `"global"` or `"project"` |
+| Field         | Required | Type   | Purpose                                                           |
+| ------------- | -------- | ------ | ----------------------------------------------------------------- |
+| `doc_type`    | Yes      | string | Kind of instruction document (e.g., `"claude_md"`, `"agents_md"`) |
+| `name`        | Yes      | string | Canonical name for this document                                  |
+| `description` | No       | string | Human-readable summary                                            |
+| `content`     | Yes      | string | Full text content                                                 |
+| `scope`       | Yes      | string | `"global"` or `"project"`                                         |
 
 Claude Code source: `~/.claude/CLAUDE.md`, `~/git/*/CLAUDE.md`, `~/git/*/AGENTS.md` <!-- platform: artifact-resolution -->
 
@@ -777,10 +835,10 @@ Claude Code source: `~/.claude/CLAUDE.md`, `~/git/*/CLAUDE.md`, `~/git/*/AGENTS.
 
 Decision-rich prompts from the host's command history. These capture what the user asked, when, and in what project context.
 
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `prompt` | Yes | string | The user's prompt text |
-| `signal_type` | Yes | string | Classification: `"decision"`, `"correction"`, or `"question"` |
+| Field         | Required | Type   | Purpose                                                       |
+| ------------- | -------- | ------ | ------------------------------------------------------------- |
+| `prompt`      | Yes      | string | The user's prompt text                                        |
+| `signal_type` | Yes      | string | Classification: `"decision"`, `"correction"`, or `"question"` |
 
 Claude Code source: `~/.claude/history.jsonl`, filtered by decision-pattern regex <!-- platform: artifact-resolution -->
 
@@ -788,12 +846,12 @@ Claude Code source: `~/.claude/history.jsonl`, filtered by decision-pattern rege
 
 Normalized user or assistant turns from host conversation sessions. Profilera uses paired user-assistant exchanges to identify how decisions were made and corrected in context.
 
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `actor` | Yes | string | `"user"` or `"assistant"` |
-| `content` | Yes | string | Turn text content |
-| `preceding_context` | No | string | Prior assistant proposal (for user turns that respond to a proposal) |
-| `signal_type` | No | string | Classification of the user's response: `"decision"`, `"correction"`, or `"question"` |
+| Field               | Required | Type   | Purpose                                                                              |
+| ------------------- | -------- | ------ | ------------------------------------------------------------------------------------ |
+| `actor`             | Yes      | string | `"user"` or `"assistant"`                                                            |
+| `content`           | Yes      | string | Turn text content                                                                    |
+| `preceding_context` | No       | string | Prior assistant proposal (for user turns that respond to a proposal)                 |
+| `signal_type`       | No       | string | Classification of the user's response: `"decision"`, `"correction"`, or `"question"` |
 
 Claude Code source: `~/.claude/projects/**/*.jsonl`, filtered for decision-rich exchanges <!-- platform: artifact-resolution -->
 
@@ -801,11 +859,11 @@ Claude Code source: `~/.claude/projects/**/*.jsonl`, filtered for decision-rich
 
 Recurring configuration or toolchain patterns associated with a project. These are objective evidence of technology choices, linting standards, and build conventions.
 
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `config_type` | Yes | string | Kind of configuration file (e.g., `"gomod"`, `"golangci"`, `"package_json"`) |
-| `file_path` | No | string | Path to the config file within the project |
-| `signals` | Yes | array of string | Extracted key-value signals (dependencies, linters, targets, etc.) |
+| Field         | Required | Type            | Purpose                                                                      |
+| ------------- | -------- | --------------- | ---------------------------------------------------------------------------- |
+| `config_type` | Yes      | string          | Kind of configuration file (e.g., `"gomod"`, `"golangci"`, `"package_json"`) |
+| `file_path`   | No       | string          | Path to the config file within the project                                   |
+| `signals`     | Yes      | array of string | Extracted key-value signals (dependencies, linters, targets, etc.)           |
 
 Claude Code source: `~/git/*/` config files scanned per known config type list <!-- platform: artifact-resolution -->
 
@@ -813,24 +871,24 @@ Claude Code source: `~/git/*/` config files scanned per known config type list <
 
 The four portable record types group into four source families for profilera's consumption. The "Crystallized decisions" family is powered by instruction_document alone (durable, explicitly authored decisions). Runtime extensions may contribute additional record types to this family.
 
-| Family | Record types | Signal character |
-|--------|-------------|-----------------|
-| Crystallized decisions | instruction_document | Highest signal: explicitly authored preferences and standards |
-| Decision history | history_prompt | Broad coverage: what the user asked across all sessions |
-| Conversation exchanges | conversation_turn | Most nuanced: how decisions were made and corrected in context |
-| Config patterns | project_config_signal | Most objective: what technology and standards actually shipped |
+| Family                 | Record types          | Signal character                                               |
+| ---------------------- | --------------------- | -------------------------------------------------------------- |
+| Crystallized decisions | instruction_document  | Highest signal: explicitly authored preferences and standards  |
+| Decision history       | history_prompt        | Broad coverage: what the user asked across all sessions        |
+| Conversation exchanges | conversation_turn     | Most nuanced: how decisions were made and corrected in context |
+| Config patterns        | project_config_signal | Most objective: what technology and standards actually shipped |
 
 ### Degradation
 
 Profilera operates in two modes: full (all four source families) and partial (one or more families missing). The degradation rules specify what profilera can produce given incomplete corpus availability.
 
-| Available families | Profilera mode | Profile quality |
-|--------------------|---------------|-----------------|
-| All four | Full | Complete profile: all 12 categories, cross-validated confidence scores |
-| Crystallized only | Partial | Instruction-heavy profile: strong in architecture/tooling standards, weak in process/workflow and meta-decision patterns |
-| Crystallized + one other | Partial | Substantially complete: most categories populated, confidence scores may be lower for categories that depend on the missing family |
-| History or conversations only (no crystallized) | Partial | Behavior-only profile: can infer patterns from actions but lacks explicit preferences. Confidence scores capped at 60 |
-| Config patterns only | Minimal | Technology fingerprint only: tooling and dependency patterns, no behavioral decisions. Profilera should warn the user this is not a full profile |
+| Available families                              | Profilera mode | Profile quality                                                                                                                                  |
+| ----------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| All four                                        | Full           | Complete profile: all 12 categories, cross-validated confidence scores                                                                           |
+| Crystallized only                               | Partial        | Instruction-heavy profile: strong in architecture/tooling standards, weak in process/workflow and meta-decision patterns                         |
+| Crystallized + one other                        | Partial        | Substantially complete: most categories populated, confidence scores may be lower for categories that depend on the missing family               |
+| History or conversations only (no crystallized) | Partial        | Behavior-only profile: can infer patterns from actions but lacks explicit preferences. Confidence scores capped at 60                            |
+| Config patterns only                            | Minimal        | Technology fingerprint only: tooling and dependency patterns, no behavioral decisions. Profilera should warn the user this is not a full profile |
 
 **Degradation surface rule**: when a source family is missing, profilera MUST note which families were absent in the profile's source metadata comment. This lets consuming skills weight profile entries appropriately: a profile built from config patterns only should not be treated as authoritative for workflow decisions.
 
@@ -844,12 +902,12 @@ Adapters MAY define additional record types beyond the four portable ones to cap
 
 Claude Code provides a built-in memory system that persists user and project memory as Markdown files with optional frontmatter at `~/.claude/projects/*/memory/*.md`. The Claude Code adapter extracts these as instruction_document records with `doc_type: "claude_memory"` rather than as a separate record type, keeping the portable corpus contract clean.
 
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `name` | Yes | string | Entry name or title |
-| `description` | No | string | Summary from frontmatter |
-| `memory_type` | No | string | Host-specific categorization |
-| `content` | Yes | string | Full text content (body after frontmatter) |
+| Field         | Required | Type   | Purpose                                    |
+| ------------- | -------- | ------ | ------------------------------------------ |
+| `name`        | Yes      | string | Entry name or title                        |
+| `description` | No       | string | Summary from frontmatter                   |
+| `memory_type` | No       | string | Host-specific categorization               |
+| `content`     | Yes      | string | Full text content (body after frontmatter) |
 
 When the Claude Code adapter encounters memory files, it emits them as instruction_document records with these additional conventions:
 
@@ -876,22 +934,22 @@ Both fields are required. A valid corpus file always contains exactly these two
 
 The metadata object describes the extraction run, not the records themselves. It provides enough context for consumers to understand what runtimes contributed, how many records were produced, and whether any errors occurred.
 
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `extracted_at` | Yes | string (ISO 8601) | When the extraction ran |
-| `runtimes` | Yes | array of string | Runtime identifiers that were probed and found available (e.g., `["claude-code"]`) |
-| `adapter_version` | Yes | string | Version of the corpus builder that produced this file |
-| `families` | Yes | object | Per-source-family extraction summary (see below) |
-| `total_records` | Yes | integer | Total number of records in the `records` array |
-| `errors` | No | array of string | Human-readable error messages from extraction failures; omitted when empty |
+| Field             | Required | Type              | Purpose                                                                            |
+| ----------------- | -------- | ----------------- | ---------------------------------------------------------------------------------- |
+| `extracted_at`    | Yes      | string (ISO 8601) | When the extraction ran                                                            |
+| `runtimes`        | Yes      | array of string   | Runtime identifiers that were probed and found available (e.g., `["claude-code"]`) |
+| `adapter_version` | Yes      | string            | Version of the corpus builder that produced this file                              |
+| `families`        | Yes      | object            | Per-source-family extraction summary (see below)                                   |
+| `total_records`   | Yes      | integer           | Total number of records in the `records` array                                     |
+| `errors`          | No       | array of string   | Human-readable error messages from extraction failures; omitted when empty         |
 
 The `families` object has one key per source family name (matching the four portable family names from the Source families table: `instruction_document`, `history_prompt`, `conversation_turn`, `project_config_signal`). Each value is an object:
 
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `count` | Yes | integer | Number of records extracted for this family |
-| `status` | Yes | string | `"ok"`, `"partial"`, or `"missing"` |
-| `error` | No | string | Explanation when status is `"partial"` or `"missing"`; omitted when `"ok"` |
+| Field    | Required | Type    | Purpose                                                                    |
+| -------- | -------- | ------- | -------------------------------------------------------------------------- |
+| `count`  | Yes      | integer | Number of records extracted for this family                                |
+| `status` | Yes      | string  | `"ok"`, `"partial"`, or `"missing"`                                        |
+| `error`  | No       | string  | Explanation when status is `"partial"` or `"missing"`; omitted when `"ok"` |
 
 A family with status `"ok"` extracted all records successfully. `"partial"` means some records were extracted but errors occurred during extraction. `"missing"` means the family could not be extracted at all (e.g., the runtime data directory was not found).
 
@@ -910,10 +968,10 @@ Consumers filter and group records by `source_kind` to access specific families.
     "runtimes": ["claude-code"],
     "adapter_version": "2.7.0",
     "families": {
-      "instruction_document": {"count": 12, "status": "ok"},
-      "history_prompt": {"count": 87, "status": "ok"},
-      "conversation_turn": {"count": 234, "status": "ok"},
-      "project_config_signal": {"count": 5, "status": "ok"}
+      "instruction_document": { "count": 12, "status": "ok" },
+      "history_prompt": { "count": 87, "status": "ok" },
+      "conversation_turn": { "count": 234, "status": "ok" },
+      "project_config_signal": { "count": 5, "status": "ok" }
     },
     "total_records": 338,
     "errors": []
@@ -945,8 +1003,8 @@ Before extracting records, the corpus builder probes for available runtimes by c
 
 Each runtime registers a probe function that checks for the existence of its data directory. The probe returns a boolean indicating whether that runtime's data is available on the current system.
 
-| Runtime | Probe path | What it checks |
-|---------|-----------|----------------|
+| Runtime     | Probe path   | What it checks                                                                                 |
+| ----------- | ------------ | ---------------------------------------------------------------------------------------------- |
 | Claude Code | `~/.claude/` | Directory exists and contains session data (e.g., `projects/` subdirectory or `history.jsonl`) |
 
 Future runtimes add their own probe entries. The corpus builder iterates all registered probes, collects the list of available runtimes, and runs their extractors. Runtimes that are not detected are skipped without error.
@@ -979,10 +1037,10 @@ This gate is the entry-side complement to Section 20 (Behavioral Verification Ga
 
 The gate applies to any skill that spawns a subagent with `isolation: "worktree"`. Currently two skills do this:
 
-| Skill | Spawn point | What it writes before spawn |
-|-------|----------------|-------------------------------|
+| Skill     | Spawn point                   | What it writes before spawn                                                           |
+| --------- | ----------------------------- | ------------------------------------------------------------------------------------- |
 | realisera | Step 5 (implementation spawn) | PLAN.md status updates, PROGRESS.md cycle start, context files from orient/plan steps |
-| optimera | Experiment spawn step | EXPERIMENTS.md updates, OBJECTIVE.md refinements, harness configuration changes |
+| optimera  | Experiment spawn step         | EXPERIMENTS.md updates, OBJECTIVE.md refinements, harness configuration changes       |
 
 orkestrera delegates skills without worktree isolation (it runs realisera or other skills as background subagents in the same working directory). orkestrera is covered transitively: when realisera creates a worktree at its Step 5, the gate commits everything in the working tree, including any uncommitted changes orkestrera wrote before spawning realisera.
 
@@ -1029,10 +1087,10 @@ This rule applies to all commits produced by any skill: checkpoint commits, real
 
 The two gates form a coherent pair bracketing the worktree lifecycle:
 
-| Gate | Section | Boundary | Question it answers |
-|------|---------|----------|---------------------|
-| Pre-spawn Git Commit | 23 | Entry: before worktree creation | Does the subagent start from current state? |
-| Behavioral Verification Gate | 20 | Exit: after implementation | Did the work actually run against real state? |
+| Gate                         | Section | Boundary                        | Question it answers                           |
+| ---------------------------- | ------- | ------------------------------- | --------------------------------------------- |
+| Pre-spawn Git Commit         | 23      | Entry: before worktree creation | Does the subagent start from current state?   |
+| Behavioral Verification Gate | 20      | Exit: after implementation      | Did the work actually run against real state? |
 
 Both gates are mandatory for worktree-spawned cycles. A cycle that passes Section 20 verification but skipped the Section 23 gate may have verified behavior built on stale context. A cycle that passes the Section 23 gate but skips Section 20 verification has current context but unverified output.