Battam1111/Myco

Cleanup + discipline-enforcement release. Grows the lint surface from 11 → 25 dimensions, lands four foundation helpers (atomic writes, trust sanitisation, skip-dirs, write-surface), wires R6 ("write only to allowed surface") into every substrate-mutating verb, and closes 13+ concrete audit-surfaced bugs.

Highlights

14 new lint dimensions (11 → 25)

• Plugin purity: MP2 (companion to MP1 for .myco/plugins/)
• Documentation hygiene: DC1-DC4 (module / function / class / doctrine-link docstrings)
• Contract health: CS1 (fixable HIGH — synced_contract_version drift)
• Substrate invariants: FR1 (HIGH/MEDIUM — fresh-substrate dirs), PA1 (MEDIUM — write_surface coverage)
• Graph integrity: SE3 (LOW — self-cycle), CG1/CG2 (LOW — code ↔ doctrine link)
• Backlog + rules: MB3 (fixable HIGH — raw-notes ≥ 50), RL1 (LOW — R1-R7 referenced)
• Discipline: DI1 (MEDIUM — .claude/hooks.json present)

Four foundation helpers under src/myco/core/

• io_atomic.py — atomic_utf8_write (temp + fsync + os.replace), bounded_read_text, bounded_read_bytes (10 MB default cap)
• trust.py — strip_controls, flatten_newlines, safe_frontmatter_field, markdown_inline_safe
• skip_dirs.py — canonical DEFAULT_SKIP_DIRS + should_skip_dir / should_skip_path (unifies 3 divergent lists)
• write_surface.py — is_path_allowed, guarded_write, check_write_allowed, unsafe_bypass_enabled, WriteSurfaceViolation

R6 mechanical enforcement

Every verb that mutates substrate content now routes through check_write_allowed or guarded_write:

• eat → notes/raw/
• sporulate → notes/distilled/
• digest / assimilate → notes/integrated/ + _canon.yaml
• fruit → docs/primordia/
• ramify → src/ or .myco/plugins/
• boot_brief → entry point
• molt → _canon.yaml + docs/contract_changelog.md

Misplaced writes raise WriteSurfaceViolation (exit 3) with a diagnostic, respecting the MYCO_ALLOW_UNSAFE_WRITE env bypass.

13+ audit-driven fixes

• Lens 6 (security): .env removed from text adapter; credential filename denylist (*.env, id_rsa*, *.pem, .npmrc, etc.); adapter size caps at 10 MB; SSRF guard + response byte-cap in url_fetcher (scheme allowlist, resolves loopback/link-local/private hosts to a refusal, redirect targets re-validated)
• Lens 7: forage walker prunes skip-dirs mid-DFS + short-circuits at MAX_ITEMS (5.5-6.4s → <400 ms on Myco self)
• Lens 10: LF-only line endings at every write_text site; POSIX source normalisation in adapters; .gitattributes committed; .pre-commit-config.yaml, src/myco/py.typed shipped
• Lens 11: MCP pulse canon cache (mtime-keyed) so repeated tool calls share the parsed canon; pulse scalars sanitised via safe_frontmatter_field
• Lens 13: symlink cycle guard in _walk_py + fingerprint walker; fresh substrates pre-create notes/raw/ + notes/integrated/
• Lens 16: SE1 switched from per-edge stat(2) to edge.dst in graph.nodes (2400× speedup on Myco self)
• Concurrency: eat.append_note uses os.open(O_EXCL) in a retry loop (TOCTOU fix)
• YAML injection: _render_note switched to yaml.safe_dump + field-level trust sanitisation
• Windows: reserved-name guard on germinate's substrate_id / entry_point; explicit encoding="utf-8" on subprocess.run(..., text=True) for cp936 locale
• Migration: _ContractVersionDescriptor reads myco.__version__ at call time (was stale constant); molt increments waves.current monotonically

Exit-code differentiation

All stay in the ≥3 operational-failure band (contract-compliant):

• SubstrateNotFound.exit_code: 3 → 4
• CanonSchemaError.exit_code: 3 → 5

Scripts checking exit != 0 are unaffected; scripts special-casing == 3 for substrate/canon failures get a more precise signal.

Bitter-lesson refactors

• clients.py: 7 near-identical JSON installers → one JsonClientSpec data table. New host = 1 row, not 5 lines.
• MP1 BLACKLIST: audited + extended with 17 providers (14 → 31): langchain integrations, Together, Fireworks, Groq, DeepSeek, Zhipu, Replicate, HuggingFace Hub, LiteLLM, AISuite, PortkeyAI, Instructor, Guidance, DSPy.

Tests

• 613 → 755 (+142)
• 4 dedicated foundation-helper test modules (test_io_atomic, test_trust, test_write_surface, test_skip_dirs)
• 14 new dimension test modules (one per new dim)
• Property tests: atomicity (interleaved read-never-torn), encoding round-trip, bypass env truthy/falsy parsing, sample-path coverage for PA1

Upgrading from v0.5.7

Fully backwards-compatible in the common path. Two notes for operators whose substrate deviates from defaults:

1. Exit codes: if you shelled out to Myco and special-cased exit == 3 for substrate-not-found / canon-schema errors, update to accept 4 / 5. Scripts checking exit != 0 need no change.
2. Write surface: if your _canon.yaml::system.write_surface.allowed does NOT cover a path a verb wants to write to, the verb now fails cleanly instead of silently writing. Run myco immune → PA1 will tell you which samples aren't covered. Add the missing pattern(s) or set MYCO_ALLOW_UNSAFE_WRITE=1 to override per-invocation.

Governing crafts

• docs/primordia/v0_5_8_discipline_enforcement_craft_2026-04-21.md (14-dim expansion + foundation helpers design)
• docs/primordia/v0_5_8_release_craft_2026-04-21.md (release closure)

Gate status at release

• 755/755 pytest
• ruff / ruff format / mypy: all clean
• myco immune (default CI gate): exit 0
• myco immune --exit-on=high: exit 0 (all findings LOW)
• myco hunger: clean (no drift, no backlog, no reflex signals)
• python -m build + twine check: PASSED for both wheel + sdist