Parent research track: #20 — Implement P0 IDKGraph repository observatory
Growth Seed: #28 — decompose one research track into 5 claimable microtasks
Architecture: docs/architecture/IDKGRAPH_TASK_AND_EVOLUTION_MODEL.md
Schema: schemas/idkgraph.schema.json
Decision: docs/decisions/ADR-0005-idkgraph-and-guarded-self-evolution.md
Issue #20 is intentionally broad: turn the repository into a deterministic structural/semantic graph, detect repository-health defects, emit a human-readable report, and preserve provenance. This decomposition tests whether that research track can become easier to enter without requiring a newcomer to understand the entire self-evolution architecture.
This document defines exactly five independently claimable microtasks. The first four can proceed in parallel against small fixtures. The fifth is the integration/reporting task and depends on the interfaces produced by the first four.
Existing work such as PR #36 (Repository Homeostasis Engine) and the GitHub collaboration observatory is useful context, but these microtasks do not require contributors to complete or redesign those efforts. The focus here is the missing deterministic P0 repository-graph path from #20.
T1 Stable document + heading identity ----\
T2 Internal-link diagnostics -------------+--> T5 Unified graph/report/replay command
T3 Typed IDKGraph mapping ----------------+
T4 Executable dependency-cycle check -----/
There are no dependency edges among T1–T4. Each can be implemented and reviewed independently with its own fixtures. T5 may begin with fixture/stub inputs before all four predecessors land, but final acceptance requires the four output contracts to be consumable together.
| Task | Best fit | Expected size | Parallel attempts? | Depends on |
|---|---|---|---|---|
| T1 | Python / Markdown parsing | small | yes | none |
| T2 | testing / Markdown links | small | yes | none |
| T3 | schema / docs / graph modeling | small | yes | none |
| T4 | Python / graph algorithms | small | yes | none |
| T5 | integration / CLI / reporting | medium | yes, with fixture inputs | T1–T4 |
IDKGraph needs stable identities so a document or section can be referenced even when other parts of the repository are scanned in a different order. The full IDKGraph architecture is much larger, but this task is only about one deterministic input boundary: Markdown files and headings. A contributor does not need to understand scheduling, AI agents, community growth, or self-evolution to complete it.
Build a deterministic extractor that enumerates repository Markdown documents and headings and assigns reproducible IDs using a documented rule. The rule must not depend on filesystem traversal order, wall-clock time, or random state.
A small standard-library implementation or focused module plus tests/fixtures that emits records containing at least:
If an existing observatory module is the canonical location by implementation time, extend it rather than creating a competing full observatory.
None.
Provide deterministic fixture evidence covering at least:
The PR should state the ID rule explicitly and include the exact test command.
Python, Markdown syntax, deterministic data processing, basic testing.
Yes. Alternative ID rules are useful to compare as long as each attempt documents stability trade-offs. Multiple attempts should not all be merged; they provide evidence for selecting the simplest adequate rule.
A repository becomes difficult to navigate when links silently break. Issue #20 treats broken internal links and missing referenced files as deterministic health defects. This task isolates that behavior from every other graph feature: given Markdown files, determine whether repository-relative links and anchors resolve, and report failures precisely.
Implement or strengthen a repository-internal link checker with explicit diagnostic categories. It should distinguish at least missing files from missing anchors instead of returning only one generic failure count.
A focused link-checking function/module plus a valid fixture tree and a deliberately broken fixture tree. Machine-readable findings should include at least:
error for deterministic broken targets; warnings only when the condition is not provably broken).None. T2 may use its own tiny fixture path/heading index and can later adapt to T1’s interface.
Fixtures must demonstrate observable outcomes for:
The broken fixture must produce non-zero actionable findings with stable ordering.
Testing, Markdown links, path normalization, Python standard library. This is intentionally accessible to contributors who are not familiar with the distributed-agent architecture.
Yes. Parallel attempts can compare conservative parsers or fixture coverage. Prefer the implementation with clearer deterministic behavior over the one that recognizes the most syntax heuristically.
The IDKGraph schema already defines node types such as document, decision, work_unit, artifact, and concept, plus typed relations such as documents, implements, depends_on, and supersedes. What is not yet fully specified is which repository facts can be mapped to those types deterministically without asking an AI model to infer meaning from prose. This task is primarily a modeling/schema exercise and is suitable for a contributor who prefers documentation, data modeling, or research over core implementation.
Define and demonstrate the smallest deterministic mapping from explicit repository structures into valid idkgraph.schema.json nodes/hyperedges.
Add a short mapping specification plus one machine-readable example fixture. The mapping should cover at least:
document node;decision node;work_unit node where the source format exposes a stable identifier;artifact node;The artifact must include a schema-gap table: if the current idkgraph.schema.json cannot represent a required deterministic fact cleanly, document the gap rather than silently inventing an incompatible field.
concept, contradicts, duplicates, or semantic supports relations from arbitrary prose.None. It can use hand-authored fixture records rather than waiting for T1/T2 extraction code.
The contribution is complete when:
JSON Schema, graph/data modeling, technical writing, repository architecture. Coding is optional.
Yes. Competing mapping tables are useful research evidence, especially when they disagree about what can safely be inferred. The review should favor explicit, conservative semantics.
IDKGraph itself is allowed to contain cycles because knowledge can be contradictory or mutually referential. The executable task projection is different: unresolved prerequisite cycles can deadlock work. This task deliberately ignores the rest of the knowledge graph and checks only whether the WorkUnit dependency projection is executable as a DAG for the supported dependency relations.
Implement a deterministic cycle checker for a small IDKGraph/WorkUnit fixture, restricted to executable dependency semantics.
A small graph-checking function/module and fixtures containing:
The checker should emit a stable cycle witness/path rather than only true/false when a cycle exists.
None. Consume a minimal hand-authored graph fixture that already matches the IDKGraph schema or a clearly documented subset.
Tests must prove that:
Graph algorithms, Python, test design. A standard DFS/Kahn-style implementation is sufficient; no advanced graph library is required.
Yes. DFS witness extraction and topological-sort approaches can be compared. Prefer clarity, deterministic diagnostics, and minimal dependencies over algorithmic novelty.
The parent issue is only useful if contributors can run the observatory and understand what it found. This final microtask combines the already-defined deterministic boundaries into one user-facing command and report. It does not add autonomous repair. Its job is to make evidence reproducible: same repository snapshot, same tool version, same graph/report semantics.
Integrate the P0 extraction/check interfaces into one local command that emits both a machine-readable IDKGraph artifact and a human-readable repository-health report with provenance.
A CLI/integration path plus tests that produce at least:
If PR #36’s observatory is the accepted canonical tool by implementation time, extend its interface instead of introducing a second competing repository scanner.
Final acceptance depends on T1, T2, T3, and T4 contracts being consumable together. Implementation can start earlier with fixture/stub outputs.
The integration contribution is complete when one documented command can be run against:
schemas/idkgraph.schema.json, except for any separately reviewed/documented minimal schema extension;The PR must include a short replay section with the exact command(s) and expected high-level result.
CLI design, integration testing, technical writing, Python. Documentation/testing contributors can improve report clarity and replay instructions even if another contributor implements the plumbing.
Yes, before final selection. Competing report layouts or CLI shapes can be tested with newcomers. Only one canonical integration path should ultimately remain.
The five microtasks stop at the deterministic P0 observatory boundary. They intentionally do not include:
ArchiveSuperseded or TaskDecomposition themselves;Those are valid follow-up research areas, but including them here would make the microtasks cease to be newcomer-sized and independently reviewable.
A reviewer unfamiliar with the complete project should pick any one of T1–T4, read only that section plus its immediate links, and answer these questions:
For T5, the reviewer should additionally be able to identify its four predecessor interfaces from the DAG.
If those answers are not obvious, the decomposition should be refined before spawning descendant GitHub issues. The goal of #28 is not to manufacture five more tracker items; it is to reduce the activation energy for five genuinely bounded contributions.