treadle repository replay

10 October 2026 · main · b4dd870

The thesis: knowledge first, then a tight loop

01 · What I understand

A spec-driven development harness that preserves context and admits work through explicit evidence.

The wiki holds what we know.

The specpack holds what we intend and what happened.

The human accepts. The agent proposes and executes.

6TypeScript packages
2data planes
5core loop skills
1task per handout
Basis: repository instructions, manifests, and source · open references

Turn context and intent
into a reviewable record.

02 · Product model

01

Remember the project

Curated Markdown pages explain systems, rules, and decisions. Source references connect claims to repository files.

treadle know search / read

02

Bound the next change

A specpack connects questions, requirements, decisions, designs, tasks, and review verdicts in one versioned record.

treadle do next / record

03

Keep acceptance explicit

The human answers and accepts. The agent works a frozen slice. Review checks the work before closure.

treadle do approve / close

My interpretation: the product provides a durable work record and repeatable agent workflow.

The intended audience is a team with a full-stack services repository, or a small set of repositories.

Sources · product scope and data contracts

One runtime. Two independent engines.

03 · Architecture from package imports

@treadle/cli

do → core and web   ·   know → knowledge   ·   init harness → installer

@treadle/knowledge

Parse · links · validate · search · findings · fingerprints · freshness

Knowledge bundle · OKF 0.2 · YAML dependency
@treadle/core

Normalize · emit · admission · derive · handout · pins · closure

Specpack · canonical bytes · Node standard library
web → core + brand
Room and library; plain HTML and JavaScript.
conformance → both engines
Golden cases and the runner.
brand → presentation
Central name tokens for CLI and web.

Node ≥22 · pnpm 9 · strict TypeScript · core and knowledge do not import each other

Sources · dependency direction is observed

The durable state lives in files.

04 · Repository map

treadle/
  packages/       engines, CLI, web, corpus, brand
  conformance/    TypeScript golden generator
wiki/             curated project knowledge
docs/product/     format contracts
docs/specs/       current initiative records
docs/research/    design research
docs/archive/     retired code-era records
docs/guide/       standalone user guide

Four completed initiatives

  • fresh-harness: installable agent harness
  • guided-loop: recall and knowledge conformance
  • stitch-ui: room and library experience
  • install-paths: proven install mechanism

All four packs say complete and delivered. All 29 tasks are marked done.

Limit: this inventory does not re-verify their historical task evidence.

Sources · current records and canonical writes

The wiki supplies context.
The engine checks its shape.

05 · The know plane

01 · Source

Curate concepts from repository evidence. Source extraction is external.

02 · Bundle

Markdown, frontmatter, links, and source references.

03 · Retrieve

Weighted search and a budgeted read of linked neighbors.

04 · Check

Validate format and links. Report anchor drift and freshness.

05 · Propose

Normative findings enter a ledger. Declined keys cannot rise again.

What is implemented

Search is deterministic: title matches rank above body matches. Ties sort by concept ID.

Trust tiers are advisory. Format validation includes Attested Computation fields.

What requires an agent

The engine cannot decide whether prose is true or whether a source supports a claim.

A curator must inspect changed sources and update the affected knowledge.

Sources · retrieval, findings, and validation

Each skill narrows the next action.

06 · Spec-driven development, or SDD

build-kb

Understand

Find the current knowledge and inspect its sources.

analyze

Bound

Produce one useful artifact. Record unknowns and assumptions.

plan

Connect

Link designs and decisions to tasks with observable verification.

implement

Execute

Work one frozen task slice. Run its verification and record the result.

review

Recheck

Re-run expectations. Check scope, traceability, and evidence currency.

The handout is more than a task title.

It carries related requirements, designs, accepted decisions, a plan prelude, and a digest. File drift can return needs_rebase.

The skills supply the workflow.
The engines supply deterministic operations.

Sources · skill contracts and frozen context

Trust has a precise local boundary.

07 · Policy versus enforcement

Human acceptance

Answers, approval, decision acceptance, and closure require a human: claim.

The claim checks a string prefix. It does not authenticate a person.

Recorded evidence

A passing task needs at least one recorded command and zero exits. Evidence can come from an agent.

do record accepts supplied results. It does not execute the command.

Closure and review

Closure checks tasks, evidence presence, decisions, questions, and a PACK PASS verdict.

do check checks alignment. The review skill requires the actual re-runs.

Documentation overstates the scope of the claim gate.

“Every write needs human:” does not match proposal creation, task handouts, evidence records, or knowledge-ledger resolution.

Sources · the exact enforcement boundary

Two browser surfaces serve the loop.

08 · Room and library

Room

A spec’s approval ceremony

Focus on one pack. Answer open questions, select options, and approve through core admission.

The CLI waits for approval, then stops the server and returns to the loop.

treadle do interview <packDir>

Library

A standing view of the records

Browse packs under one root. Inspect phases, artifacts, questions, and review information.

It remains available while the owner examines and acts on records.

treadle do library <specsRoot>

Current posture: both servers bind to 127.0.0.1. Assets are local. Authentication is absent by design.

Markdown comes from trusted disk content and is rendered without HTML sanitization. CSP permits inline scripts and styles.

Sources · server behavior and declared threat model
  • do.ts:212 · interview lifecycle; line 242 · standing library
  • servers.ts:64 · content security policy; lines 189 and 311 · loopback binding
  • SECURITY.md:12 · trusted-disk Markdown and absent authentication

The harness ships with the runtime.

09 · Distribution and agent adapters

Install the CLI

install.sh clones the repository, installs the locked pnpm workspace, builds it, and links the CLI globally.

The closed install-paths record explains why ordinary npm remote installs failed on the workspace protocol.

This session inspected the mechanism. It did not re-run a clean remote installation.

Install the agent workflow

treadle init harness compiles an inspectable plan before it writes skills, agents, and supported hooks.

Destinations cover pi, Claude Code, Codex, and Copilot. A recorded install supports removal.

Hook wiring differs by host. Copilot’s manifest has no hook wiring.

Versioned interfaces: harness/0.1, specpack/0.3, and OKF 0.2.

The brand package centralizes runtime names. Rebranding preserves these format identifiers.

Sources · install path and adapter capabilities

The corpus passes.
The full check currently fails.

10 · Observed in this session

Repository verification results on 10 October 2026
CheckResultWhat the result establishes
pnpm corpus:checkPASS78 generated golden files reproduce exactly across 44 case directories.
pnpm brand:checkPASSThe runtime brand fence is clean.
pnpm checkFAILTypes, lint, and format pass. Tests: 110 pass; 1 fails.
pnpm coverageFAILThe same test fails. Current coverage floors remain unverified.
Wiki session closeLIMITEDFresh stamp; 0 errors and warnings; 0 broken anchors. Active sources remain untracked.

The failing test assumes a live initiative.

where.test.ts:180 expects an open pack and then expects install-paths. All four current packs are delivered.

Sources · actual command results and test location

The freshness story has two gaps.

11 · Observed implementation gaps

01

The scanner still selects Python files.

fingerprints.ts:54 includes only .py. TypeScript and Markdown sources remain untracked.

Implication: active-source drift lacks a stored hash. The anchor count treats “untracked” as report-only.

02

The bundle stamp compares Git HEAD.

It does not examine uncommitted edits. Committing the stamp also makes its recorded HEAD one commit old.

Implication: “fresh” is a narrow session state. It does not prove that every claim is current.

Format health, source coverage, and prose truth
need separate evidence.

Sources · exact selectors and freshness comparison

Other gaps have different causes.

12 · Observed drift and declared deferrals

OBSERVED

Documentation drift

The workspace README still says “scaffold.” The architecture wiki retains Python commands and obsolete paths.

The debt ledger says Python retirement is pending, while the generator is already TypeScript.

OBSERVED

The CI gate differs

CI runs the conformance tests. Its workflow has no explicit pnpm corpus:check step.

The generator-and-zero-diff gate passed locally. This review did not inspect remote CI runs.

DECLARED

Capabilities deferred

Code indexing belongs to external tools. Attested Computation has admission checks, with execution deferred.

The library lacks do where multi-root parity. Test files are outside the composite typecheck.

Sources · distinguish stale text from a deliberate scope boundary

What I still do not know.

13 · Uncertainty, recorded explicitly

Product evidence

  • Which measured team outcome defines success?
  • What adoption evidence exists beyond this repository’s own use?
  • Who owns the external indexer handoff for a new user?

I did not locate a current validation study or a measured outcome baseline in the material reviewed.

Next boundaries

  • Will the product remain a trusted, single-user localhost tool?
  • Which consumer triggers executable attestation?
  • Which license will apply before publication?

The license and attestation trigger are already open in the debt ledger. These questions do not block this replay.

Confidence: high in package boundaries and the operations inspected; lower in complete cross-platform adapter behavior and user adoption.

The original Python implementation, a clean remote install, and the six-platform CI matrix were not re-run here.

Sources · declared uncertainty and investigation limits

Three bounded follow-ups.

14 · Suggestions for owner review

01

Restore repeatable checks

Replace the live-wave test assumption with stable fixtures.

Observable result: checks pass with zero open initiatives.

02

Make source drift visible

Design fingerprints for active source types and a freshness policy that accounts for changed files.

Observable result: a TypeScript edit causes the affected source anchor to report drift.

03

Refresh the current map

Supersede Python-era architecture claims and align documentation with current contracts.

Observable result: a new engineer can trace each current claim to a live source.

I understand the architecture.
The largest gaps concern the evidence
that keeps its knowledge current.

Open the existing user guide · the product’s install and usage walkthrough

Open the evidence record · source revision, checks, limits, and deck verification

Sources · these are proposals, not accepted decisions