docs: adopt Linked Literate Programming (LLP) — waves 0–2#81
Draft
philcunliffe wants to merge 9 commits into
Draft
docs: adopt Linked Literate Programming (LLP) — waves 0–2#81philcunliffe wants to merge 9 commits into
philcunliffe wants to merge 9 commits into
Conversation
Stand up an LLP documentation system: numbered, Systems-tagged, living design docs under llp/ that code can @ref into at section granularity. Wave 0 — foundation - llp/ + llp/tombstones/; LLP 0000 root explainer with subsystem map - LLP 0001 adoption plan (this rollout); LLP 0002 V1 scope & cutover decisions (lifted from finish-v1's live Decisions, which diverge from the design doc and must stay active rather than be tombstoned) - AGENTS.md: new "Design docs (LLP)" section (read-before-change, @ref policy, /ref-check) Wave 1 — Sources exemplar - LLP 0012 Sources spec - 4 real @ref annotations in src/core/registry/sources.js (register/start/reload), validated by /ref-check (0 broken) Wave 2 — bulk decomposition - LLP 0003–0017 from hypaware-design.md's Design Decisions - Monolithic docs tombstoned: 0018 impl-plan, 0019 finish-v1, 0020 design (decomposed) - Repointed README + kernel-types.d.ts links to the LLP corpus Validation: 72 inter-LLP links/anchors resolve; all code @ref anchors resolve. 18 active LLPs (0000–0017) + 3 tombstones.
Commit the LLP toolset under .claude/skills/ so every clone (teammates, CI, cloud sessions) gets the slash commands, not just this machine's global skills dir: - llp-init, llp-init-retrofit, llp-create, llp-list, llp-review - ref-check, ref-story - llp-grill — new: stress-tests a plan against the LLP corpus and Systems vocabulary, capturing decisions inline (the LLP-aware counterpart to grill-with-docs) AGENTS.md now points at .claude/skills/ as the in-repo home of the tooling.
Fill the one subsystem gap from the decomposition: src/core/observability (~1.8k LOC) had no governing LLP. Captures the load-bearing decisions: - dual exporter strategy (JSONL dev vs OTLP) and the self-loop guard (!devTelemetry && otlpEndpoint) behind the otel_self_loop_guard smoke - the normalized, queryable attribute contract (Attr.* + buildAttrs: snake_case keys, fixed status vocabulary, bounded cardinality) - withSpan/runRoot as the sanctioned lifecycle-instrumentation wrappers - secret-safety policy and shutdown/flush semantics Adds Observability to the Systems vocabulary and the LLP 0000 map. No @ref annotations yet — those land with the separate Wave 3 pass.
Link the self-instrumentation code to its governing spec, upgrading the informal "Phase 0 contract" / "self-instrumentation contract" prose to real @ref annotations: - tracer.js: exporter-selection strategy + the self-loop guard (!devTelemetry && otlpEndpoint) as [constrained-by] - attrs.js: buildAttrs + Attr vocabulary -> the-attribute-contract - span_helpers.js: withSpan/runRoot -> span-helpers - index.js: idempotent install + reverse-order shutdown/flush - jsonl_exporters.js: lazy-open file mechanics + flatten-for-queryability - meter.js: mirrored exporter strategy + kernel instrument set /ref-check src/core/observability: 12 refs, 0 broken. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Link the kernel registries to their governing specs: - sinks.js: export-targets framing, the blob/table-format/request instantiation shapes (bytes-flow-down), and the writer+destination intersection that makes a sink queryable (0014) - datasets.js: core registers zero datasets; plugins contribute all (0015) - query/sql.js: core-owned read-only SQL, IO only via storage service (0015) - commands.js: core owns dispatch, plugins only register (0009) - capabilities.js: requireCapability as the sole cross-plugin channel and semver range travelling with the require, not the name (0006) /ref-check src/core/registry src/core/query: 13 refs, 0 broken. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Link activation, paths, and the config model to their specs (and retire the "Phase 2 contract in hypaware-implementation-plan.md" pointer, now in the tombstoned 0018): - paths.js: kernel-owned scoped per-plugin dirs (0004#state-directories) - activation.js: the per-plugin activation context, and the capability facade that pins the activating plugin's identity (0004, 0006) - config/schema.js: v2 shape with no mode field, the blob-vs-request sink shapes, per-plugin section validation (0010, 0014) - config/validate.js: cross-plugin validation after manifests load, the writer/destination blob-store check, and 5-field-cron-only schedules /ref-check src/core/runtime src/core/config: 9 refs, 0 broken. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…0017
Link the remaining V1 subsystems to their decisions, and retire stale
pointers into the now-tombstoned finish-v1 / implementation plans:
- cache: retention as the central tradeoff (permanent per-dataset
eviction) and the parsed-but-unwired wait_for_sink_ack open question;
the kernel-owned cache write path (0013)
- plugin_install: the single resolution precedence and the git-artifact
install that never runs npm install on the user's machine (0007)
- daemon: the primary daemon loop, and launchd/systemd install pointed at
the stable global binary; dropped finish-v1.md §Phase 4 pointers (0017)
- cli: the interactive picker, autodetect-only-seeds-checkbox, config
composition with no role labels, and the non-interactive init path
(0011, 0002)
/ref-check src/core/{cache,plugin_install,daemon,cli}: 15 refs, 0 broken.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…0008 Link the plugin layer and representative smokes to the category decisions they realize and exercise: - plugins: ai-gateway knows nothing about Claude/Codex; claude/codex are adapters that require the gateway capability (and contribute walkthrough skills); otel is an OTLP source; local-fs/s3 provide hypaware.blob-store with format kept separable; format-parquet's encoder declares queryable - runtime/loader.js: plugins load only through their single manifest entrypoint — the pure-JS, no-npm-install consequence (0008) - smokes (daemon, otel, parquet sink, attach, config validate, cache roundtrip): tagged [tests] against the decision each one proves /ref-check src + hypaware-core: 64 refs, 0 broken, across 14 active LLPs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two active specs had no code annotation. Both have a clean home: - manifest.js validateManifest -> LLP 0005#declarative: one manifest shape declares requires/provides/contributes; plugin category is emergent. - activation.js createKernelRuntime -> LLP 0003#intrinsic-not-plugin-provided: query + storage are wired in as intrinsic services, not contributions. Leaves only 0000 (root map) and 0001 (LLP-adoption plan) unreferenced — both meta docs with no subsystem code to annotate. 66 refs, 0 broken. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stands up a Linked Literate Programming documentation system in HypAware: numbered,
Systems-tagged, living design docs underllp/that code can@refinto at section granularity. Humans stay in markdown; AI writes/reviews code against the referenced decisions.This is the planned adoption plan first retrofit (see
llp/0001-adopting-llp.plan.md), executed in three waves.Wave 0 — foundation
llp/+llp/tombstones/; LLP 0000 root explainer with the subsystem map and cross-cutting invariants.Active).finish-v1.md's## Decisionsare live, as-shipped reality (publish ashypaware, bundled first-party plugins, central/gascity out of scope) and diverge from the design doc, so they became a liveDecisionrather than getting tombstoned.AGENTS.mdgains a## Design docs (LLP)section: read-before-change,@refpolicy,/ref-check.Wave 1 — Sources exemplar (the dogfood test)
CONTEXT.mdglossary).@refannotations insrc/core/registry/sources.js(register/start/reload), upgrading the file's pre-existing informal§Sourcesmention into machine-readable links with[implements]/[constrained-by]relations./ref-check→ 4 references, 0 broken, exit 0.Wave 2 — bulk decomposition
hypaware-design.md's Design Decisions (core surface, activation/paths, manifest, deps/capabilities, install/lock, runtime deps, CLI, config, onboarding, cache, sinks, query+collect, AI gateway, daemon).README.mdandcollectivus-plugin-kernel-types.d.tsto the LLP corpus.Validation
@refanchors resolve.Reviewing
Good entry points:
llp/0000-hypaware.explainer.md, the@refs insrc/core/registry/sources.js,llp/0002-v1-scope.decision.md.Notes / follow-ups
finish-v1.md §Phase 3— not broken (prose, not links), but the natural Wave 3 boy-scout@refconversion targets.🤖 Generated with Claude Code