Skip to content
procrastivityPublic

About

Layered Documentation System CLI

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

lds

LDS is a CLI for a Layered Documentation System: engineering documentation alongside Diátaxis user documentation. It has deterministic lds plumbing docs inventory, local-link validation, four-asset rendering, reviewed planning, create-only application, and maintenance assessment reports with reviewer-authored proposals, plus separately reviewed existing-file update planning/application and bounded lds plumbing reconcile evidence scanning, explicit caller-owned journal operations, and an offline lds reconcile report review packet with optional consent-gated assistance. Linux root-only interactive lds reconcile journal record|decide|reconsider hosts guide explicit journal entries directly from clean pinned roots, without authored scan or request JSON. Reconciliation reads clean pinned Git snapshots and does not infer semantic matches or mutate source projects. The report is a private new external file, not a journal decision or applied proof; the deterministic lds plumbing reconcile report is eligible for generated skill projection. lds plumbing reconcile collect captures an original bounded baseline, and lds plumbing reconcile flow --json reads the live preparatory flow. Assisted reports retain reviewer assertions separately from unverified model proposals; no native skill/parity result is claimed. The interactive root lds adopt <root> --facts <facts.json> form uses those deterministic docs operations with an advisory OpenCode Go request and a fresh exact-plan human gate. Generated Claude Code /lds adoption guidance fetches lds plumbing adopt --json live and follows the shared assets/flows/adopt.md procedure; the reader remains preparatory and unavailable for execution, and the guidance does not enforce behavior. S10 was accepted for executor CLI cases and independent offline review, not native skill execution or CLI/skill parity. Neither form authorizes a real pilot or establishes first-release inclusion.

The offline lds init <root> --facts <file> [--json] is a Linux terminal-only host of the same four-file create-only adoption plan and apply, without a provider, key, flow reader or LLM. It requires an existing explicit root and complete approved facts, displays the full plan on stderr and accepts only a freshly typed apply sha256:<exact displayed digest> or decline after review. Collisions or incomplete facts refuse before prompting; no confirmation flag or stdin-pipe bypass exists. See the disposable initialization how-to. This is implemented and verified offline, not release, pilot or native-skill/parity evidence; facts approval is not plan approval.

The offline lds facts helper collects assertions and citations in a Linux terminal. --resume <file> edits selected saved fields and always resets approval to pending; --review <file> validates complete facts and records a named reviewer's fresh exact-digest approval after displaying the entire candidate. All modes emit the existing fact-bundle JSON on stdout without overwriting input. They inspect no project, run no commands and use no provider. Facts approval asserts independent verification; it is not proof of truth or approval of the later init/adopt plan.

The human maintenance workflow lds assess <root> produces model-assisted, review-required proposals in a new report outside the target, after fresh consent to send the complete scoped documentation and selected source contents to OpenCode Go. lds plumbing docs collect prepares the same evidence offline; lds plumbing docs assess also accepts an observed packet with an authored brief. Offline checks do not establish live-provider reliability or installed-skill parity. No assessment edits the target. See the assessment how-to.

The offline lds update <root> --observed <collected.json> --request <edits.json> remains provider-free and unchanged. Explicit lds update <root> --assist --reason <text> --audience <text> --document <relative-existing-markdown> [--document ...] [--source <relative-file> ...] instead collects bounded evidence, discloses the complete model payload for fresh send consent, and returns unverified full-file drafts and questions. No edits is a valid review-required result. Nonempty drafts receive a complete deterministic plan and require a separate freshly typed exact-digest apply decision. The separate lds plumbing docs update-plan / update-apply route remains available. None implicitly accepts assessment advice or alters create-only adoption; no real target or pilot is authorized. See the update how-to.

lds review <root> [--json] is a Linux-only offline, read-only first pass over scoped documentation: file sizes/hashes, supported local-link findings, skips and explicit limitations on stdout. It needs no terminal, credential or authored JSON input and writes no report. Exit 0 means no supported missing local file or supported heading target, not complete or current documentation. Heading checks use a bounded ASCII ATX subset; unsupported syntax remains explicitly skipped. See the review how-to, CI recipe and connected offline maintenance tutorial. The repository CI runs that review after its existing Nix build, preserving findings, explicit skips and actual exit status without a provider.

Built on the toolsmith contract (toolsmith/v1 — the manifest declares it): a single static Go binary that projects itself into agent harnesses as generated, stamped skills.

Install

nix profile install .#default   # from this checkout
lds install                     # project into every detected harness

lds install <harness> targets one harness; lds uninstall <harness> removes exactly what install wrote; lds plumbing doctor reports stale or drifted projections.

Project-local runtime assets (BDS-234 port)

LDS accepts an explicit global --project-root PATH for runtime asset reads. For a known shipped asset name, it tries <canonical-root>/.lds/assets/<shipped-relative-name> before the existing user-XDG → installed → embedded chain. For example, selecting /work/acme lets adoption render use /work/acme/.lds/assets/templates/adoption/docs/README.md; the flag is not inferred from the current directory, Git, environment, an init/adoption/assessment/update target, or reconciliation pair roots. A missing project file falls through for that asset only; unsafe or unreadable selected paths refuse rather than fall back. See the command reference and safety boundaries.

The selection applies to adoption templates (including root init) and the live adoption, assessment, update and reconciliation flows where their runtime readers opt in. Init reads templates only, not a flow. It does not change manifest/projection-digest identity, configuration, install, uninstall, doctor or generated installed skill bytes. A generated skill must carry an explicitly human-selected root to its live flow and template plumbing calls, not embed repository content at installation time. Existing consent, plan approval and freshness gates still apply; this is a local integration, not a pilot, provider test, native skill/parity finding or contract-reconciliation claim.

Use LDS

Start with the user documentation for an offline inspection tutorial, adoption and reconciliation how-tos, command reference, and the current safety boundaries. The initialization how-to uses disposable test-only facts for offline terminal review and create-only application; it authorizes no real target. The assessment how-to collects evidence and proposed text outside the target without editing it. The reconciliation how-to includes a disposable offline report example using an empty review brief and the guided journal route, plus bounded assisted and external-artifact examples without a provider call. Recording a claim does not verify it or execute a transfer. The update how-to distinguishes the provider-free collect/request route, consent-gated assisted drafting and the separate manual plumbing plan/apply route. None selects a pilot or authorizes unattended edits. The review how-to demonstrates a broken local link and explains why repairing it is not semantic validation.

Develop

direnv allow      # or: nix develop
make check        # lint + test
make fuzz         # bounded parser mutation smoke tests
make hooks        # pre-commit, both stages

On Linux, make test also executes the connected maintenance tutorial's exact shell blocks with the built CLI, isolated fixtures and test-only PTY decisions. The Nix development shell supplies Bash, Coreutils and Python 3. This replay guards guide/CLI drift; it is not real-target approval or pilot evidence.

CI also runs make fuzz: three 10-second campaigns, two workers each, with inputs capped at 4 KiB and a one-minute test timeout per target. They exercise strict fact bundles, untrusted model update drafts, and Markdown/link/heading review in disposable trees. JSON checks cover exact content, malformed shapes, and scope refusals; review checks retain known findings/skips and unchanged target bytes. Ordinary tests replay the seeds. These short campaigns supplement the larger-input boundary tests; they are not exhaustive parser verification. The test job also runs go test -race -count=1 ./... as a separate, ten-minute-bounded step; ordinary tests and fuzzing remain separate gates. GitHub Actions pins receive monthly Dependabot update proposals for review.

Version stamps come from release tags (git describe --match 'v[0-9]*'); pushing an annotated vX.Y.Z tag is the only human release action. CHANGELOG.md is generated per release, never committed. An initial v0.0.0 is supported when requested explicitly; --patch with no previous release instead selects v0.0.1. A packaging rehearsal may override Make's VERSION, COMMIT and DATE in disposable build output without creating a tag or publishing. Such a stamp does not establish a release. Release artifacts target Linux/amd64 and Darwin/arm64; the documentation inspection, facts, initialization and update workflows remain Linux-only. Cross-compiling Darwin does not verify native execution or add that support.

Design of record

The engineering documentation is the design of record, starting with the adoption decision, source-repository map, and roadmap. The runtime handoff documents supported lds plumbing docs behavior and its limits; the flow/plumbing map records the root form's boundaries. The S10 preparation record sets out the reduced-scope acceptance and evidence limits; the BDS-251 engineering handoff records offline regressions and remaining limits. No real project has been authorized as an adoption pilot. The initialization contract bounds the offline root host, exact in-memory plan review and existing create-only apply, with disposable verification and explicit safety limits. The maintenance-workflow design records the accepted assessment/report boundary and implemented deterministic authored-brief report. Its human-facing assessment workflow adds scoped collection and model-authored proposals. The separate existing-file update contract defines reviewed replacement and the assisted update boundary; assessment itself still cannot edit files. Generated Claude Code guidance reads the live preparatory lds plumbing update --json flow rather than owning another sequence. This does not establish native execution or CLI/skill parity.

The BDS-252 engineering handoff documents the reconciliation plumbing, bounded runtime evidence, and limits; it does not authorize a real-pair pilot or source transfer. The reconciliation workflow records the implemented offline and assisted report and guided journal slices; none is a full facilitator or real-pair authority decision. The GitHub CI workflow runs; the generated release workflow has not been exercised yet.

About

Layered Documentation System CLI

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages