core · diff

git:20261014.0fe0dae to git:20261112.6bf5824

2 added, 0 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: core
description: >
Initialize and maintain Mycelium living repositories. Use when the user
mentions Mycelium, living repos, crystallizing learnings or findings,
recording decisions or settling which past decision still binds, installing
conventions, tracking todo ideas, migrating an older Mycelium project, or
managing the .living knowledge layer. Do not use for report writing, generic
refactoring, brainstorming, git initialization, or ordinary folder
organization.
---
# Mycelium — Living Repository Skill (Core)
## Bundled paths
Resolve paths beginning with `skills/`, `network/`, or `todo/` relative to the
Mycelium plugin root—the ancestor containing `.codex-plugin/` and
`.claude-plugin/`—not relative to the user's working repository. Keep
`.living/`, `.mycelium/`, and project manifest paths relative to the user's
repository.
When invoked, determine which mode the user needs based on their request, then follow the corresponding protocol.
For analysis, report generation, idea brainstorming, and code review, direct the user to the dedicated skills:
- `/mycelium:analyze` or `$mycelium:analyze` — start or continue an analysis
- `/mycelium:report` or `$mycelium:report` — generate a structured report
- `/mycelium:ideas` or `$mycelium:ideas` — brainstorm with disciplinary personas
- `/mycelium:transfer` or `$mycelium:transfer` — cross-pollinate learnings across sibling projects
- `/mycelium:harden` or `$mycelium:harden` — turn one learning's `structural_mitigation_candidate` into a test that fails when the problem is present and passes on current code, then mark the learning `structural`
- `/mycelium:review` or `$mycelium:review` — review code/analysis changes (PR, commit, or diff) for the kinds of mistakes that matter in scientific work; supports `grill` mode for conversational interrogation of analytical decisions
- `/mycelium:codex-review` or `$mycelium:codex-review` — respond to Codex review comments on a PR: fix the flagged instance and audit the whole branch for other instances of the same error pattern, with an access-gated `@codex review` re-trigger
---
## Mode: `init`
**Trigger**: "set up mycelium", "initialize living repo", "restructure this repo"
**Purpose**: Scaffold a new or existing repo into a mycelium-enabled living repository.
**Steps**:
1. Check if repo already has mycelium structure (look for `.living/` directory).
2. **New repo**: Run full scaffold using `skills/core/scripts/init_repo.py`.
3. **Existing repo**: Run in restructure mode — audit current structure, propose migration plan, ask user to confirm before proceeding.
4. **Auto-install core convention packs**: Scan `network/conventions/*/CONVENTION_PACK.yaml` for packs with `core: true` and install each one using `skills/core/scripts/install_convention.py`. Currently the core packs are `robust-analysis`, `report-generator`, and `idea-generator`. These provide batteries-included practices every repo should have.
5. **Set up skillpacks directory**: Create `skillpacks/` with `.gitignore` and `README.md`. This is where external skill repos (bioSkills, scientific-agent-skills, Autonomous-Science) are cloned for use by the `skill-bridge` convention. The repos are inert reference libraries — never installed as agent skill packs. Prompt the user to clone the repos:
```bash
cd skillpacks/
git clone https://github.com/K-Dense-AI/scientific-agent-skills.git
git clone https://github.com/GPTomics/bioSkills.git
git clone https://github.com/arjunrajlaboratory/Autonomous-Science.git
```
6. Ask which **domain** conventions to install from the network (e.g., bioinformatics, image-analysis, skill-bridge). Domain packs are those without `core: true`.
7. Generate canonical `MYCELIUM.md` guidance plus thin `CLAUDE.md` and `AGENTS.md` adapters using `skills/core/scripts/init_repo.py`.
8. Generate `ENVIRONMENTS_INSTALLATIONS.md` at repo root.
9. Create descriptive manifests in each top-level directory (`ANALYSIS_MANIFEST.md`, `DATA_MANIFEST.md`, `ALGORITHM_MANIFEST.md`, `REFERENCE_MANIFEST.md`).
10. Initialize `.living/` with empty `decisions.md`, `learnings.md`, `conventions.md`; create `.living/log/LOG_REGISTRY.md` (session log registry — tracks work across sessions). Create `.living/outputs/knowledge-transfers/` for cross-project transfer audit trail.
11. **Bootstrap knowledge system**: If `~/.mycelium/knowledge/` does not exist, run `skills/core/scripts/init_knowledge.py` to set up the global progressive disclosure knowledge system. The script also appends the Global Knowledge Domains routing table to every `~/.claude/projects/*/memory/MEMORY.md` (idempotent — skips files where the header is already present). Generate `.living/INDEX.md` for the newly scaffolded project using `skills/core/scripts/generate_index.py --summary-heuristic`.
12. Create `todo/` directory with `TODO_REGISTRY.md` (registry table) and `TODO_ITEM_TEMPLATE.md` (template for individual items). Copy these from the mycelium `todo/` directory.
13. After completion: run `skills/core/scripts/validate_structure.py` to confirm everything is correct.
14. **Codex only**: Mycelium's five command hooks are bundled with the plugin and use
Codex's dynamic `PLUGIN_ROOT`; initialization must not write versioned
plugin-cache paths into `.codex/hooks.json`. After first installing the
plugin, or after an upgrade resolves `PLUGIN_ROOT` to a new cache path, tell
the user to open `/hooks` in a current Codex CLI (not the desktop app),
trust the five plugin hooks, fully exit Codex, and restart it so the
approved hook set is loaded at SessionStart. If `/hooks` is absent, tell
them to run `codex update` and relaunch the CLI first.
**References to consult**:
- `skills/core/references/folder-structure.md` — canonical target structure
- `skills/core/references/environment-setup.md` — environment setup conventions
---
## Mode: `ingest`
**Trigger**: "ingest dataset", "add data", "import data"
**Purpose**: Pull a new dataset into the analytical framework.
**Steps**:
1. Consult `skills/core/references/data-ingest-conventions.md`.
2. Determine data type, source, and format.
3. If a domain convention is active, check its conventions for domain-specific validation.
4. Place raw data in `data/raw/[dataset-name]/`.
5. Generate metadata in `data/metadata/[dataset-name]/` using templates: `skills/core/templates/schema.yaml` for column definitions, `skills/core/templates/provenance.md` for source documentation, and `skills/core/templates/summary_stats.md` for statistical overview.
6. Update `data/DATA_MANIFEST.md` with new entry (use `skills/core/templates/dataset-manifest-entry.yaml`).
7. Log any decisions about data cleaning or exclusion to `.living/decisions.md`.
8. Run the post-action hook protocol (see below).
---
## Mode: `install-convention`
**Trigger**: "install convention", "add bioinformatics conventions", "install convention pack"
**Purpose**: Install a convention pack from the mycelium network into the current repo.
**Context**: Core packs (`robust-analysis`, `report-generator`, `idea-generator`) are auto-installed during `init`. This mode is primarily for adding domain packs after initialization, but can also be used to manually install or reinstall any pack.
**Steps**:
1. Consult `skills/core/references/marketplace-guide.md`.
2. List available conventions from `network/conventions/`, noting which are core (already installed) and which are domain (available to add).
3. User selects which to install.
4. Run `skills/core/scripts/install_convention.py` to copy conventions into `.living/conventions/[name]/`.
5. Update `.living/conventions/ACTIVE_CONVENTIONS.yaml`.
6. Update `MYCELIUM.md` to reference the new convention pack.
---
## Mode: `crystallize`
**Trigger**: "crystallize learnings", "review learnings", "extract patterns"
**Purpose**: Review accumulated learnings and propose new conventions.
**Steps**:
1. Consult `skills/core/references/skill-generation-guide.md`.
2. Consult `skills/core/templates/learning-entry.md` for the entry format used in learnings.md (entries start with `### [YYYY-MM-DD]` and have **Category**, **Tags**, **mitigation_type**, and **structural_mitigation_candidate** fields — use Tags for pattern clustering, and `mitigation_type` for recurrence-risk assessment).
3. Read `.living/learnings.md` and `.living/decisions.md`.
4. Identify recurring patterns using the thresholds defined in `skill-generation-guide.md` — minimum 3 related entries sharing tags or themes. See the worked example in that guide for the complete input→output transformation. To surface near-duplicate entries automatically, run `python3 skills/core/scripts/detect_recurrence.py --living-dir <path>` — it flags clusters of `ambient-awareness` learnings that are strong candidates for convention promotion or structural mitigation.
5. **Promote transferable knowledge**: For patterns that apply beyond the current project, write entries to the matching global domain file in `~/.mycelium/knowledge/{domain}.md` using the structured entry template (What/Evidence/When useful/Scope/Status/Last validated). Set `status: unreviewed` — the weekly audit will confirm.
6. Propose new convention documents or checklists for project-specific patterns.
7. Draft them in `.living/generated-conventions/[name]/` using the template at `skills/core/templates/generated-convention.md`.
8. Include `ORIGIN.md` linking back to the learnings that spawned it.
9. Ask user if they want to contribute it back to the network.
---
## Mode: `crystallize-findings`
**Trigger**: "crystallize findings", "extract findings", "log findings"
**Purpose**: Extract scientific findings from recent work and organize them into topic-based files.
**Steps**:
1. Dispatch a capable subagent with the following instructions:
2. Read the current project's recent session log (`.living/log/` most recent file) and any generated analysis outputs.
3. Identify scientific findings — empirical observations, validated/invalidated hypotheses, quantitative results, or methodological discoveries about the domain. **NOT** tooling/process insights (those go to `learnings.md`).
4. For each finding, check for existing topics:
a. Walk up from repo root to find meta-project (parent dir with `.living/`).
b. Read `{meta-project}/.living/findings/INDEX.md` if it exists.
c. Semantically match the finding against existing topics.
5. Route each finding:
- **Existing topic match** → append to `{project}/.living/findings/{topic-slug}.md` using the entry template from `skills/core/templates/findings-entry.md`.
- **No match** → create new `{project}/.living/findings/{topic-slug}.md` using the topic template from `skills/core/templates/findings-topic.md`.
6. **Topic naming principle**: Prefer broad scientific questions. No project names, organ names, species names, or method names in slugs. Test: "Would a researcher in a different system recognize this as relevant?"
7. **After writing each finding**, upsert a row in `.living/findings/FINDINGS_REGISTRY.md`. If the file doesn't exist, create it from `skills/core/templates/findings-registry.md`, then run `python3 skills/core/scripts/upsert_table_row.py .living/findings/FINDINGS_REGISTRY.md F-NNN '| F-NNN | ... |'`. This locked helper matches the finding ID exactly and preserves concurrent rows. Columns: ID, Claim, Status, Topic (link to topic file), Implications, Tags, Last Updated.
8. Run `python3 skills/core/scripts/crystallize_findings.py` to rebuild the cross-project INDEX.md and regenerate all per-project FINDINGS_REGISTRY.md files from the topic file source of truth.
9. **Consolidation pass** (if invoked explicitly): Scan all topics across all projects, flag potential duplicates (overlapping tags or similar descriptions), and suggest merges to the user.
10. Return single-line summary: "Added N findings to M topics (N new topics created)."
---
## Mode: `transfer`
**Trigger**: "transfer knowledge", "cross-pollinate", "sync learnings", "knowledge transfer"
> **Dormant by design — requires meta-project layout.** This mode only fires when the current repo sits inside a parent directory that itself has `.living/` (the "meta-project"), or when the current repo *is* the meta-project with ≥2 sibling projects each having `.living/`. Sibling repos at the same parent level (e.g. `~/code/projA/`, `~/code/projB/`) do NOT qualify. If your repos are siblings, either (a) nest them under a common meta-project directory and `init` the parent, or (b) skip this mode entirely.
**Purpose**: Cross-pollinate learnings across sibling projects in a meta-project. Identifies insights from one project that would benefit others and **automatically applies** them to target projects' `.living/learnings.md` files.
**Steps**:
1. This mode delegates to the dedicated transfer skill. Read and follow `../transfer/SKILL.md`.
2. The transfer skill is designed to run as a background subagent. Use a capable available model and do not block on results.
3. Transfers are auto-applied to target projects' `.living/learnings.md` with `source: {project} (auto-transferred by mycelium)` for auditability.
4. Audit reports are written to `{meta-project}/.living/outputs/knowledge-transfers/YYYY-MM-DD.md`.
**When this runs**:
- **Automatic**: `mycelium-health.sh` checks `.living/outputs/knowledge-transfers/.last-run` at session start. If >24h old, missing, unreadable (line 1 must be a `YYYY-MM-DDTHH:MM:SSZ` UTC stamp), or in the future, it emits a directive to dispatch the transfer as a background subagent.
- **Manual**: User invokes `/mycelium:transfer` or says "transfer knowledge", "cross-pollinate".
**Lifecycle position**: This phase sits between crystallization (patterns → conventions) and contribution (conventions → network). Crystallize extracts patterns within a project; transfer propagates relevant patterns across projects; contribute shares generalized patterns with the network.
**Notes**:
- Transfers are context-adapted for the target project, not copy-pasted verbatim
- Near-duplicate entries in the target are skipped automatically
- "All clear" reports (no transfers needed) are normal and expected most days
---
## Mode: `contribute`
**Trigger**: "contribute convention", "share back", "submit to network"
> **Dormant by design — manual workflow.** This mode does not fire automatically. It runs only when a user explicitly asks to contribute a convention back to the network, and requires that `crystallize` mode has previously produced a `.living/generated-conventions/[name]/` to package. Most projects never reach this stage; that is normal.
**Purpose**: Package a repo-local generated convention for PR to the mycelium network.
**Steps**:
1. Verify the generated convention exists in `.living/generated-conventions/[name]/` — if not, run `crystallize` mode first.
2. Read the convention and its `ORIGIN.md` provenance document.
3. **Generalize** the convention for broader use:
- Replace repo-specific paths, dataset names, and project references with parameterized placeholders
(e.g., `/home/user/hospital-x/data/` → `[data-source-path]`, "Hospital X CSV exports" → "external tabular data sources")
- Abstract project-specific context while preserving the core convention
- Ensure examples are generic enough to apply outside the original project
- See the encoding validation example in `skills/core/references/skill-generation-guide.md` for reference
4. **Expand into pack structure** if the convention is complex:
- Simple conventions: the generated convention.md becomes `analysis-conventions.md` directly
- Complex conventions: split into a hub file (`analysis-conventions.md`) that links to detail files covering specific aspects
- See `network/conventions/robust-analysis/` for an example of a multi-file pack
5. Create the convention pack directory at `network/community-contributed/[name]/`:
- `CONVENTION_PACK.yaml` — use template at `skills/core/templates/convention-pack.yaml`
- `analysis-conventions.md` — the generalized convention (hub file with progressive disclosure)
- `qc-checklist.md` — quality control checklist for applying the convention correctly
- Additional reference files for complex conventions (e.g., `statistical-conventions.md`)
- `templates/` — reusable templates if applicable
6. Generate a PR description with:
- What the convention covers and why it's useful
- Anonymized provenance (number of learnings, time span, but no project names)
- Which domains or workflows benefit
7. Present the pack to the user for review before committing.
---
## Mode: `file-issue`
**Trigger**: "file issue", "report convention gap", "report bug in convention"
> **Dormant by design — manual workflow.** Fires only when a user explicitly asks to file a network-side issue. No automation routes to this mode.
**Purpose**: Report a convention gap or error to the mycelium network.
**Steps**:
1. Capture context: what went wrong, what convention was involved.
2. Draft a structured GitHub issue using the appropriate template.
3. Categorize as `convention-gap`, `convention-improvement`, or `new-domain-request`.
4. Present to user for review before filing.
---
## Mode: `recall`
**Trigger**: "what do we know about X", "find learnings tagged Y", "fetch entry L-42", "/recall"
**Purpose**: Targeted lookup of `.living/learnings.md` and `.living/decisions.md` entries by tag, ID, or date — without pulling whole files into context.
**Steps**:
1. Identify the filter the user wants:
- **Tag-based**: `--tag <tag>` (repeatable for ANY-match)
- **Text-based**: `--term '<text>'` (case-insensitive literal match on the entry's heading and body; repeatable for ANY-match; keep the quotes so a multiword value stays one argument). Reaches untagged entries.
- **Follow citations**: `--follow` also returns every later entry that cites a returned entry by heading title (such as a `**Supersedes**:` line), repeatedly, so a supersession chain comes back whole.
- **ID-based**: `--id L-42` or `--id D-7` (repeatable)
- **Date-based**: `--since YYYY-MM-DD`
2. Run `python3 skills/core/scripts/recall_lessons.py --living-dir .living/ [filters]`.
3. The script prints only the matching entry blocks, sorted most-recent-first, capped at `--max 20` by default. A capped result says so on stderr; pass `--max 0` when you need every match, and `--count-only` always reports the uncapped total.
4. Use the printed entries directly — the script substitutes for whole-file reads of `learnings.md`/`decisions.md`.
**Discovery**: Tag → ID maps live in `.living/INDEX.md` under the **By tag** subsection (regenerated by the SessionStart hook). Use it to find candidate IDs before recall.
---
## Mode: `decision-status`
**Trigger**: "which decision is current", "what did we decide about X", "is this decision still binding"; or a task depends on a choice that has two or more `.living/decisions.md` entries
**Purpose**: Settle which past decision binds the current task when the append-only decision log holds several entries on the same choice. The newest entry never wins by recency alone.
**Steps**:
1. Follow `skills/core/references/decision-status.md`: retrieve only the entries the task touches, then resolve each decision point by explicit supersession, then scope match, then compatible entries (a `rejected`, `shelved`, or `held` entry about a different option leaves the active choice binding), and treat anything else as contested.
2. Ask the user about contested points only — one question per message, at most three per session — quoting the competing entries by date and exact heading.
3. After the user confirms, append a `Resolution:` entry with `**Supersedes**:` and `**Resolved-by**:` lines. Never edit an existing entry.
---
## Mode: `migrate`
**Trigger**: "migrate this repo", "upgrade mycelium", "this is an old repo"
**Purpose**: Bring a repo started on an earlier Mycelium version up to current spec — creates canonical `MYCELIUM.md` guidance and a Codex `AGENTS.md` adapter, migrates runtime state to `.mycelium/`, tops up Claude hooks, removes obsolete project-local Codex hook paths in favor of the plugin bundle, regenerates the heuristic SUMMARY block, and preserves Claude MEMORY.md routing where available.
**Steps**:
1. Run `python3 skills/core/scripts/migrate_existing_repos.py --repo .` (or `--scan <parent-dir>` to migrate every child).
2. Each action is idempotent — re-running on an already-migrated repo is a no-op.
3. Use `--dry-run` first to preview changes.
4. **Codex only**: after a real migration following plugin install or upgrade,
tell the user to open `/hooks` in a current CLI (not the desktop app), review
and trust all five Mycelium plugin hooks, fully exit Codex, and restart it.
If `/hooks` is absent, run `codex update` and relaunch the CLI first.
---
## Mode: `todo-idea`
**Trigger**: "todo idea", "add todo", "I have an idea", "track this for later", "/todo-idea"
**Purpose**: Capture a future work item, idea, or planned improvement in the project's `todo/` directory.
**Steps**:
1. Ask the user (if not already provided):
- **Title**: Brief name for the item
- **Description**: What is this about?
- **Priority**: critical, high, medium, low, or idea (default: idea)
- **Category**: e.g., validation, feature, refactor, analysis, infrastructure
- **Motivation**: Why is this worth doing?
2. Generate a kebab-case filename from the title (e.g., "Compare Public Data" -> `compare-public-data.md`).
3. Create `todo/[filename].md` using the template at `todo/TODO_ITEM_TEMPLATE.md`. Fill in all fields from user input. Set status to `open`. Set date to today. Set author to the user's name (ask if unknown).
4. Add or update the registry row with `python3 skills/core/scripts/upsert_table_row.py todo/TODO_REGISTRY.md '<item title>' '| <item title> | ... |'`. The title is the exact first-column key. Include priority, status, category, date, author, and a link to the file in the remaining cells.
5. Confirm the item was added and show the user the registry entry.
**Notes**:
- If `todo/` or `todo/TODO_REGISTRY.md` doesn't exist yet, create them first (use the structure from the mycelium `todo/` directory as reference).
- Users can also update existing items by asking to change their status or priority — edit both the item file and registry row.
---
## Mode: `knowledge-init`
**Trigger**: "knowledge init", "set up knowledge", "initialize knowledge system", "progressive disclosure"
**Purpose**: Bootstrap the global progressive disclosure knowledge system (`~/.mycelium/knowledge/`).
**Steps**:
1. Run `skills/core/scripts/init_knowledge.py` to create domain files from templates. Existing files are preserved (idempotent).
2. For each project with a `.living/` directory: run `skills/core/scripts/generate_index.py` to create/update `.living/INDEX.md`.
3. Check each project's MEMORY.md (in `~/.claude/projects/*/memory/`). If missing the "Global Knowledge Domains" table, append it from `skills/core/templates/knowledge/domain-table.md`.
4. Verify the knowledge system is functional: check `~/.mycelium/knowledge/.last-audit` exists, confirm domain file count, report summary.
**Notes**:
- This mode is **global** — it sets up `~/.mycelium/knowledge/` which is shared across all projects.
- Safe to run multiple times. Existing domain files and their entries are never overwritten.
- The weekly audit (triggered by `mycelium-health.sh`) handles ongoing maintenance: staleness checks, INDEX.md regeneration, skills sync, dedup.
- Domain files start empty (header + trigger only). Entries accumulate through the post-action protocol's knowledge promotion step and the crystallize mode.
**References to consult**:
- `skills/core/templates/knowledge/domains.yaml` — domain registry (single source of truth for domain definitions)
- `skills/core/templates/knowledge/domain-table.md` — MEMORY.md routing table template
- `skills/core/templates/knowledge/entry-template.md` — entry format reference
---
## Post-Action Hook Protocol
**This is what makes the repo "living." Execute after ANY significant action** (analysis step, data ingestion, algorithm implementation, report generation):
+ The session log the post-action hook names (`.living/log/<date>-<nnn>-<project>.md`) is hook-owned and append-only: append to it; never rewrite it (Stop needs its header). Rewriting it with a whole-file write drops the YAML frontmatter Stop finalizes, and Stop then blocks until the header is restored.
+
1. **Update manifests**: Update the relevant manifest (`ANALYSIS_MANIFEST.md`, `DATA_MANIFEST.md`, etc.) with new/changed entries.
2. **Update documentation**: Update or create the UPPER_SNAKE_CASE.md file in the affected subfolder with current status, key findings, open questions.
3. **Log decisions**: If a non-obvious choice was made, append to `.living/decisions.md` using the decision log template. Set `**Status**:`. If the choice replaces an earlier entry, name that entry in `**Supersedes**:` by date and exact heading title, never by a positional `D-N` ID; never edit the earlier entry. If entries on the choice disagree, settle them with the `decision-status` mode first.
4. **Log learnings**: If something unexpected was learned (gotcha, edge case, failure), append to `.living/learnings.md` using the learning entry template. **Required field**: set `mitigation_type` to one of `structural | convention | ambient-awareness` (see template comments for definitions). Also fill `structural_mitigation_candidate` with the concrete test or invariant that would catch it. Derive `mitigation_type` by the rule in `skills/core/templates/learning-entry.md`: `structural` if a shipped test, assertion, type constraint, frozenset, or schema validation enforces it; otherwise `convention` if a `.living/conventions.md` entry covers it; otherwise `ambient-awareness`. A candidate that has not shipped does not count; `$mycelium:harden` ships the test and then marks the entry `structural`. **Knowledge promotion**: If the learning is transferable (would help in any project), also append to the matching global domain file in `~/.mycelium/knowledge/{domain}.md` with `status: unreviewed`. Use the structured entry template with a `when_useful` trigger condition.
5. **Log todos**: If future work is identified during the action, create detailed `todo/[item].md` files as needed and mutate `todo/TODO_REGISTRY.md` only through `skills/core/scripts/upsert_table_row.py` so concurrent rows are preserved.
6. **Validate**: Run `skills/core/scripts/validate_structure.py` to confirm repo still conforms.
7. **Crystallize conventions**: Review `.living/learnings.md` for recurring patterns (3+ related entries on the same topic). If found, check whether an equivalent convention already exists in `.living/conventions.md` — if so, append new `Source:` citations and refine the text only if materially improved. If no equivalent exists, add a new convention with `Source:` citations linking to the originating learnings. Then, for each newly cited learning: Derive `mitigation_type` by the rule in `skills/core/templates/learning-entry.md`: `structural` if a shipped test, assertion, type constraint, frozenset, or schema validation enforces it; otherwise `convention` if a `.living/conventions.md` entry covers it; otherwise `ambient-awareness`. Do not create near-duplicate conventions.
8. **Update LOG_REGISTRY**: Use `skills/core/scripts/upsert_registry_row.py` to update the LOG_REGISTRY.md row for this session, using the exact Session ID and command the post-action context names (the `session_id:` field of the active session log). Never invent a session ID; if none is known, leave the registry to Stop, which writes the row. Replace the filename-stub Summary with a 1-sentence past-tense description of what was accomplished (no filenames unless the artifact is the primary output). Fill Key Outputs with semicolon-separated concrete artifacts, metrics, or decisions. Summary and Key Outputs must not duplicate each other.
9. **Convention feedback**: If any convention pack practices were relevant, note whether they were helpful or had gaps.
10. **Write session summary**: Write or update the exact handoff path supplied by the lifecycle hook (`.mycelium/run/<host>/<session-id>/last-session.md` for identified roots; `.mycelium/last-session.md` for legacy hosts) with a 5-section summary covering ALL work since session start. Use the session summary template:
```markdown
SESSION RESUME — Last session (YYYY-MM-DD HH:MM):
## What was worked on
- [Semantic summary of accomplishments — what was built/fixed/analyzed, not file lists]
## Key decisions made
- [Decision]: [rationale] (see .living/decisions.md for full context)
### Locked decisions
- [Decision the next session must not reopen without new evidence or the user's agreement] ([decisions.md date and exact heading])
## Blockers & surprises
- [Resolved/Unresolved]: [what happened, resolution or current status]
### Dead ends — do not redo
- [Approach tried and abandoned]: [why it failed, with the evidence or path]
## Current state
- Branch: X | Tests: N passing | [environment notes]
- [Key metrics, uncommitted changes, data state]
## Next steps
- [Actionable items with specific commands where relevant]
```
Keep exactly these five `##` headings, in this order, with at least one bullet in each section. A `###` heading on its own is not content. Stop replaces a handoff that breaks this shape with a generic fallback, losing what you wrote. Under **Locked decisions**, list choices the user confirmed or that later work builds on, citing each `.living/decisions.md` entry by date and exact heading. Under **Dead ends — do not redo**, list approaches tried and abandoned this session with the reason, so the next session does not retry them. Write `- None.` under a subsection that has nothing to record. (These two subsections are adapted from the `handoff` skill in Mikhael Manurung's [mycelium-extra](https://github.com/mdmanurung/mycelium-extra), MIT.)
**Full-session coverage**: Run `git log --since=<session-start-timestamp>` and `git diff --stat` to capture all work since session start. If crystallization fires multiple times in a session, each write rebuilds the summary covering the entire session (cumulative, not incremental). The summary should get more expansive as the session progresses.
### Automated Enforcement (Claude Code and Codex Hooks)
Mycelium ships shared hook scripts in `skills/core/hooks/`. `init_repo.py`
registers Claude hooks in `.claude/settings.local.json`. Codex discovers five
plugin-bundled registrations from `hooks/hooks.json`; their dispatcher uses
Codex's dynamic `PLUGIN_ROOT` and no-ops outside repositories with `.living/`.
| Hook | Event | Purpose |
|------|-------|---------|
| `mycelium-health.sh` | SessionStart | Loads `.mycelium/last-session.md` for session resume (agent + user); warns if `.living/` is missing or incomplete; records session timestamp; triggers the daily knowledge audit if `~/.mycelium/knowledge/.last-audit` is >24h old, unreadable, or in the future (the stamp is the first token of line 1, e.g. `1791826296 daily-audit`) |
| `mycelium-post-action.sh` | PostToolUse (shell) | Detects code execution and directs the active agent to run the full post-action protocol |
| `mycelium-stop-check.sh` | Stop | Consolidates data lineage synchronously, checks `.living/` was updated after significant work, and warns if the session summary was not written |
**Post-action enforcement**: The PostToolUse hook detects Python/R/Jupyter execution and pipeline runs (`bash run.sh`, `./run.sh`, `snakemake`, `sbatch`, `nextflow run`) in Bash calls (excluding tests, linting, pip, one-liners, and dry runs) and injects a mandatory directive for the active agent. It is **debounced**: fires once per work cycle, then stays silent until `.living/` is updated. The Stop hook serves as a safety net for non-analysis sessions.
**Stop hook logic**: SessionStart snapshots the repository's existing dirty state, so Stop reports only paths changed during the current session. The stop hook checks if `mycelium-post-action.sh` fired during the session (indicated by the presence of `.mycelium/mycelium-reminded.tmp`). If `.living/` was not updated afterward, it blocks immediately—even for a short session—and preserves its work timestamp so repeated Stop attempts cannot bypass enforcement. If `.living/` was updated, it emits a non-blocking reminder to enhance the deterministic session summary. Read-only sessions, config-only sessions, and sessions without meaningful activity are never checked.
Codex requires each exact plugin command hook to be reviewed and trusted through
`/hooks` in the current CLI; the desktop app does not expose that slash command.
If `/hooks` is absent from the CLI, run `codex update` and relaunch it. After
first install or any plugin upgrade, approve all five Mycelium hooks, fully exit
Codex, and restart it.
Codex matches shell and unified-exec work under `Bash`, and its activity tracker
parses `apply_patch` headers. The plugin registry and dispatcher resolve the
live `PLUGIN_ROOT` and refresh `.mycelium/plugin-root` automatically, so cache
replacement does not leave dead hook paths in repositories. Read-access
telemetry remains Claude-only because Codex does not expose internal file reads
to `PostToolUse`. Data-lineage extraction follows preceding shell `cd` commands,
so relative script and data paths are resolved from the directory where the
analysis actually ran.
### Subagent-Driven Sessions
When work is dispatched to subagents (main context = coordination only):
1. **Subagents do not need mycelium awareness** — they focus on their implementation task and report results back.
2. **After all subagent batches complete**, the main context dispatches a crystallization subagent that:
- Reviews the summary of what was accomplished
- Appends entries to `.living/learnings.md` and `.living/decisions.md`. For each learning: Derive `mitigation_type` by the rule in `skills/core/templates/learning-entry.md`: `structural` if a shipped test, assertion, type constraint, frozenset, or schema validation enforces it; otherwise `convention` if a `.living/conventions.md` entry covers it; otherwise `ambient-awareness`.
- Writes the exact handoff path supplied by the current lifecycle context using the 5-section session summary template (covering ALL work since session start, not just the latest batch — run `git log --since=<session-start-ts>` and `git diff --stat` to ground the summary in facts)
- Checks cross-project relevance (if applicable)
3. **The Stop hook enforces this** — it blocks session end if `.living/` wasn't updated after significant work, catching sessions where the crystallization step was forgotten.
---
## How to verify the system is working
Quick checks an agent or human can run to confirm mycelium is wired correctly:
| Check | Command / location | Expected |
|-------|--------------------|----------|
| Claude hooks installed | `cat .claude/settings.local.json` | SessionStart, PostToolUse, and Stop registrations present |
| Codex hooks bundled | Inspect the installed plugin's `hooks/hooks.json` | Five `PLUGIN_ROOT`-based SessionStart, PostToolUse, and Stop registrations present |
| Codex hooks trusted | Open `/hooks` in a current Codex CLI (not the desktop app; run `codex update` if absent) | All five Mycelium plugin hooks show as trusted |
| INDEX.md has knowledge summary | `grep "BEGIN KNOWLEDGE SUMMARY" .living/INDEX.md` | Match present |
| Read-access being logged | `tail .mycelium/mycelium-read-access.log` | Entries appearing when Claude reads `.living/` files |
| MEMORY.md routing table present | `grep "Global Knowledge Domains" ~/.claude/projects/*/memory/MEMORY.md` | At least one match |
| Heuristic clusters populating | `python3 skills/core/scripts/generate_index.py --living-dir .living/ --summary-heuristic --dry-run` | Tag clusters with ≥2 entries shown |
| recall_lessons.py works | `python3 skills/core/scripts/recall_lessons.py --living-dir .living/ --tag <known-tag>` | Matching entries printed |
If any check fails, run `python3 skills/core/scripts/migrate_existing_repos.py --repo .` to bring the repo up to spec.
---
## Troubleshooting
| Problem | Solution |
|---------|----------|
| `validate_structure.py` fails after init | Check that all four top-level directories exist and each has its manifest (`ANALYSIS_MANIFEST.md`, etc.). Re-run init if needed. |
| Domain conventions conflict with core | Domain conventions take precedence. Update `.living/conventions.md` to document the override. |
| `.living/` directory missing | Run `init` mode to scaffold the living layer. Never create it manually — the script sets up required files. |
| Manifest entry format errors | Check `skills/core/templates/dataset-manifest-entry.yaml` or `skills/core/templates/analysis-manifest-entry.yaml` for the correct format. |
| `ENVIRONMENTS_INSTALLATIONS.md` not found | Run `init` mode or create it manually following `skills/core/references/environment-setup.md`. |
| Crystallize finds no patterns | This is normal for young repos. Continue logging learnings and decisions — patterns emerge over time. |
| Install-convention can't find a domain | Check `network/conventions/` for available packs. File a `new-domain-request` issue if your domain isn't covered. |