implementation-todo.md

title	Implementation Todo
type	todo
status	active
updated	2026-04-28
tags	todo implementation roadmap
links	[[development-plan]] [[architecture-v2]] [[implementation-status]] [[system-analysis]]

Implementation Todo

Linked from: [[development-plan]], [[architecture-v2]]

Legend:

• done
• not done
• [~] in progress

Status note (2026-04-28)

v1 foundation завершено (schema, vault, templates, validator, indexer, installer, обидва adapter-и). Pilot на Курсова-2 і Курсова-К показав: документи створюються коректно, але граф розпадається на ізольовані зірки. Лінки односторонні, sparse, кластери не з'єднані. Подальша робота переміщається в v2: Connected Memory Graph — див. architecture-v2.md.

v1-блоки нижче залишаються як історія (всі завершені, окрім pilot). Активна робота — секція v2 Graph Evolution.

Baseline

• Create raw concept note in idea.md
• Create system analysis document
• Create development roadmap document
• Initialize local Git repository
• Set default branch to main
• Add remote origin for GitHub repository

Foundation

• Define memory document types
• Define merge vs create via write gate
• Define canonical document policy
• Define lifecycle and status policy
• Define retrieval policy for v1
• Define consolidation policy
• Define naming convention for IDs and files
• Create skills/core/mem-entity-memory-core.md
• Add machine-readable schema v1
• Add schema_version
• Freeze exact links structure
• Freeze exact provenance structure
• Define final task state model: todo, in-progress, blocked, done

Vault Layout

• Create memory/concepts/
• Create memory/contexts/
• Create memory/decisions/
• Create memory/entities/
• Create memory/indexes/
• Create memory/notes/
• Create memory/summaries/
• Create memory/tasks/
• Create memory/indexes/mem-index-vault.md
• Add initial Memory Core entry to vault-index
• Create first canonical concept doc for memory-system
• Create first retrieval policy decision doc
• Create first vault structure context doc
• Create first task doc for validator/indexer work
• Expand vault-index with real canonical memory nodes
• Create first cluster index doc for bootstrap navigation

Templates and Standards

• Create concept template
• Create decision template
• Create entity template
• Create context template
• Create task template
• Create note template
• Create index template
• Add real examples for core canonical document types
• Add anti-pattern notes for bad write behavior
• Add migration rules for future schema changes

Skills and Adapters

• Create Codex skill
• Create Claude skill
• Define retrieval flow in both skills
• Define write/update flow in both skills
• Extract shared adapter contract into dedicated doc or checklist
• Document real Codex vs Claude behavior differences
• Define exact rule for updating mem-index-vault.md
• Define boundary between normal write and consolidation pass

Validation and Indexing

• Create validator spec for frontmatter and required fields
• Implement validator
• Create lightweight indexer spec
• Implement lightweight indexer
• Implement orphan detection
• Implement duplicate detection
• Add installer/bootstrap workflow for installing memory-system into target repos

Packaging and Installer

• Add memory_tool install
• Support clean and examples content modes
• Copy .memory-system/skills/ and .memory-system/tooling/
• Create generated .memory-system/memory/ scaffold for clean installs
• Create wrapper scripts/memory-tool
• Create install-manifest.json
• Update target .gitignore
• Update target README.md if present
• Create target MEMORY-SYSTEM.md
• Verify install via post-install validate/index
• Add upgrade path beyond fresh-install only

Repo Docs

• Create implementation status document
• Create README.md as repository entrypoint
• Add reading order for repo docs
• Add short current-state section for newcomers

Pilot and Metrics

• Choose 1-2 real projects for pilot
• Define retrieval hit-rate target
• Define duplicate-rate target
• Define orphan-doc threshold
• Define stale-doc threshold
• Define acceptable level of manual cleanup after agent writes
• Run first pilot pass
• Capture pilot report requirements in dedicated readiness doc
• Add pilot report template

v1 Current Focus (closed)

• Close formal foundation gaps: schema, task states, links, provenance
• Fill memory/ with first canonical docs
• Prepare validator and indexer specs
• Stabilize adapter contract before pilot
• Implement validator and lightweight indexer
• Add remaining example docs for entity and note
• Add consolidation checklist and rollback policy
• Add adapter verification note
• Add packaging/installer workflow
• Run first pilot (Курсова-2, Курсова-К) — exposed graph sparsity problem

v2 Graph Evolution

Goal: щільніший і traversable граф через pre-write retrieval pass, computed graph index і shared core замість cross-project bridges. Повна архітектура у architecture-v2.md.

Відкинуто після review (не реалізовувати):

• incoming_links у frontmatter — race conditions, write amplification
• similar_to link type і cross-project install scan — нереалістичний, не machine-checkable
• Hard-minimum 2 links як блокуюче правило — Goodhart effect

Phase A. Tools first

• Implement memory_tool index --graph — full regeneration of mem-index-graph.md
• Implement memory_tool graph stats — read-only graph statistics
• Add computed as allowed provenance.source in schema-v1.md
• Define root-node whitelist in schema-v1.md (vault-index, graph-index, global concept)
• Add new cross-field rules to schema: ERROR on 0 links non-root, WARNING on 1 link or all-same-type
• Extend memory_tool validate with soft warnings and root whitelist check
• Add pre-commit hook setup to memory_tool install (index --graph on commit)
• Add unittest coverage for --graph, graph stats, updated validate

Phase B. Graph index bootstrapping

• Run memory_tool index --graph on core memory — generate first mem-index-graph.md
• Review output: orphans, broken links, components
• Manually enrich docs with obvious missing links (not forced — opportunistic)
• Add graph-index entry to mem-index-vault.md
• Document graph-index lifecycle (regenerate, never edit) in vault-index-rules.md

Phase C. Adapter updates

• Update adapter-contract.md: add Phase 0 pre-write retrieval pass
• Update adapter-contract.md: expand write gate with Phase 2 soft quality check
• Update retrieval sequence: add graph-index as secondary source for backlink/impact queries
• Document traversal intent patterns (outbound vs inbound semantics) in adapter contract
• Update skills/claude/skill.md with v2 write gate and retrieval
• Update skills/codex/skill.md with v2 write gate and retrieval
• Update adapter-differences.md for v2 nuances

Phase D. Shared core migration

• Identify duplicate docs between Курсова-2 and Курсова-К (commit-policy, formatting-rules)
• Create canonical versions in core memory (project: memory-system)
• Add implements / derived_from links in project-specific docs pointing to core
• Update installer: show list of canonical core docs during project bootstrap
• Run memory_tool index --graph and verify core bridges appear

Phase E. Pilot v2

• Run write scenarios with Phase 0 pre-write retrieval pass in Курсова-2
• Run write scenarios with Phase 0 pre-write retrieval pass in Курсова-К
• Measure avg links per doc before/after
• Identify third project for fresh v2 install
• Write pilot-report-v2.md with real metrics (calibrate targets from data)

Phase F. Validation

• Zero true orphan nodes (memory_tool validate 0 errors)
• mem-index-graph.md exists, computed_at < 7 days
• Avg outbound links >= 3.5 (measured after pilot, not enforced)
• Agent can retrieve backlinks for any doc via graph-index in 1 read
• Shared knowledge from Курсова-2 / Курсова-К lives in core, not duplicated
• Migration checklist done for both existing pilot projects
• Sign off in new v2-readiness.md

v2 Active Now

• Phase A: implement memory_tool index --graph
• Phase A in parallel: add computed source and root whitelist to schema + validator