The thesis: knowledge first, then a tight loop
01 · What I understand
Knowledge first.
Then a tight loop.
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.
Basis: repository instructions, manifests, and source · open references
- AGENTS.md:5 · thesis and intended scope
- CLI main.ts:13 · command roots
- next.ts:45 · one task handout
Turn context and intent
into a reviewable record.
02 · Product model
Remember the project
Curated Markdown pages explain systems, rules, and decisions. Source references connect claims to repository files.
treadle know search / read
Bound the next change
A specpack connects questions, requirements, decisions, designs, tasks, and review verdicts in one versioned record.
treadle do next / record
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
- AGENTS.md:22 · intended project scope
- model.ts:1 · internal pack objects
- OKF_SPEC_v0.2.md · knowledge format
One runtime. Two independent engines.
03 · Architecture from package imports
do → core and web · know → knowledge · init harness → installer
Parse · links · validate · search · findings · fingerprints · freshness
Knowledge bundle · OKF 0.2 · YAML dependencyNormalize · emit · admission · derive · handout · pins · closure
Specpack · canonical bytes · Node standard libraryRoom 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
- cli/package.json · CLI dependencies
- knowledge/package.json and core/package.json · engine boundaries
- tsconfig.base.json · strict compiler flags
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
- fresh-harness.json, guided-loop.json, stitch-ui.json, install-paths.json · status and task inventory
- save.ts:10 · derive, canonical emit, fsync, rename
The wiki supplies context.
The engine checks its shape.
05 · The know plane
Curate concepts from repository evidence. Source extraction is external.
Markdown, frontmatter, links, and source references.
Weighted search and a budgeted read of linked neighbors.
Validate format and links. Report anchor drift and freshness.
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
- search.ts:1 · ranking and deterministic order
- findings.ts:122 · dedupe and declined-key behavior
- validate.ts:238 · advisory trust tier; line 298 · attested admission
Each skill narrows the next action.
06 · Spec-driven development, or SDD
Understand
Find the current knowledge and inspect its sources.
Bound
Produce one useful artifact. Record unknowns and assumptions.
Connect
Link designs and decisions to tasks with observable verification.
Execute
Work one frozen task slice. Run its verification and record the result.
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
- analyze/SKILL.md, plan/SKILL.md, implement/SKILL.md · bounded work contracts
- next.ts:82 · drift gate; line 115 · slice closure
- review/SKILL.md:14 · current verification and traceability
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
- admission.ts:25 · human prefix check
- record.ts:62 · accepted command results; do.ts:145 · agent or human evidence actor; line 189 · alignment check
- close.ts:20 · closure conditions; know.ts:133 · finding resolution has no actor argument
Two browser surfaces serve the loop.
08 · Room and library
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>
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
- install.sh:24 · clone, build, and global link; install-paths/research.md · recorded mechanism evidence
- plan.ts:103 · compiled installer plan; apply.ts:80 · apply and state record
- harness.json · four destinations and per-host wiring
The corpus passes.
The full check currently fails.
10 · Observed in this session
| Check | Result | What the result establishes |
|---|---|---|
pnpm corpus:check | PASS | 78 generated golden files reproduce exactly across 44 case directories. |
pnpm brand:check | PASS | The runtime brand fence is clean. |
pnpm check | FAIL | Types, lint, and format pass. Tests: 110 pass; 1 fails. |
pnpm coverage | FAIL | The same test fails. Current coverage floors remain unverified. |
| Wiki session close | LIMITED | Fresh 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
- evidence.md · commands, exits, counts, and limits
- where.test.ts:180 · state-dependent self-witness
- corpus-check.mjs:13 · regenerate and compare committed bytes
The freshness story has two gaps.
11 · Observed implementation gaps
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.
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
- fingerprints.ts:54 · Python-only scan; line 155 · untracked verdict
- stamp.ts:68 · freshness compares HEAD
- know.ts:158 · untracked does not count as review-needed; DEBT.md:27 · commit-stamp debt
Other gaps have different causes.
12 · Observed drift and declared deferrals
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.
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.
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
- treadle/README.md:13, sdd-harness-architecture.md:49, DEBT.md:47 · stale descriptions
- ci.yml:28 · configured CI checks; corpus.test.ts:5 · case discovery test
- DEBT.md:12 · attested execution; line 25 · library parity; line 46 · test typecheck
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
- DEBT.md:12 · execution trigger; line 45 · license choice
- AGENTS.md:22 · intended repository scope; ci.yml:13 · declared platform matrix
- evidence.md · scope of this investigation
Three bounded follow-ups.
14 · Suggestions for owner review
Restore repeatable checks
Replace the live-wave test assumption with stable fixtures.
Observable result: checks pass with zero open initiatives.
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.
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
- where.test.ts:174 · fixture-dependent gap
- fingerprints.ts:54 and stamp.ts:77 · drift and stamp gaps
- sdd-harness-architecture.md · architecture to supersede