Weaveback

Status: archived failed experiment.

Weaveback was an experiment in bidirectional literate programming for the age of coding agents. It tried to make annotated source documents the source of truth while still allowing generated files to be traced, queried, edited, and patched back into the literate source.

The experiment produced useful components, especially the strict macro language and the forward noweb-style tangling pipeline. But the complete system became too complex for the value it provided.

The simplified continuation is:

giannifer7/reweave

Reweave keeps the useful forward path:

Markdown input
  -> optional macro expansion
  -> chunk expansion
  -> direct file writes

and removes the systems that made Weaveback hard to reason about:

• the SQLite provenance database;

• source-map query tooling as a core requirement;

• apply-back and reverse editing;

• generated-file reconciliation;

• dogfooding the implementation through literate sources;

• documentation rendering and distribution machinery.

Why Weaveback Is Considered A Failure

The core hypothesis was reasonable: coding agents make code generation cheap, so the scarce resource becomes intent, traceability, and reviewability. Weaveback attempted to preserve that intent by connecting generated code back to prose and chunks.

The problem is that the reverse path dominated the project.

Forward generation is understandable:

source document -> macro expansion -> chunk assembly -> generated files

Reverse editing is not:

generated edit
  -> provenance lookup
  -> source-map interpretation
  -> macro/chunk reconstruction
  -> source patch synthesis
  -> retangle verification

That second pipeline required persistent state, path normalization rules, database locking behavior, source maps, generated-file guards, apply-back heuristics, and specialized agent workflows. It made simple work expensive.

The result violated a useful engineering rule:

If the implementation is hard to explain, it is probably the wrong design.

Weaveback also suffered from dogfooding pressure. Deciding what should be literate and what should remain ordinary source became an extra design problem on top of every real task. Large literate files and generated Rust drift made the implementation harder, not easier, for humans and agents to maintain.

In short:

• the forward macro+tangle model was useful;

• the bidirectional/provenance/apply-back model was too fragile;

• the workflow was too unfamiliar;

• the self-documentation did not compensate for the added complexity.

That is why Weaveback is archived as a failed experiment rather than presented as an unfinished product.

What Survived

The lessons and reusable ideas were carried into Reweave:

• strict %def / %redef macro bindings;

• explicit verbatim blocks;

• strict variable and parameter behavior;

• Markdown as the authoring format;

• ordinary Rust source instead of dogfooded literate implementation;

• forward-only noweb-style chunk expansion;

• high test coverage as a guardrail.

See:

• Reweave repository

• Literate programming lessons from Weaveback

Historical Material

The rest of this repository is kept for reference. It contains experiments in:

• macro language design;

• chunk syntax;

• source tracing;

• database-backed provenance;

• MCP and LSP integrations;

• generated documentation;

• agent-oriented editing workflows.

These are historical artifacts, not recommended starting points for new work.

If you want the practical successor, start with Reweave:

https://github.com/giannifer7/reweave