Skip to content

docs: README documented a layout that no longer exists - #49

Merged
harshuljain13 merged 1 commit into
mainfrom
docs/readme-and-spec
Oct 5, 2026
Merged

harshuljain13 merged 1 commit into
mainfrom
docs/readme-and-spec

Conversation

@harshuljain13

Copy link
Copy Markdown
Owner

The front door was describing the previous two designs.

Stale: examples/ and example-runs/ as paths, "arm" as the word for a policy.

Missing entirely: admitperf demo, admitperf experiments, compare --experiment, the naming fields, the seven reporting items, terminology.

Two sections that never existed

Naming a measurement — experiment, run, notes, provenance, and why grouping is declared rather than inferred from a directory: moving a file should not silently change what a result claims to be.

How it connects to the survey — the seven items with the demo's actual statuses, and why — is neither a pass nor a failure. The survey's finding is that the corpus is silent on these, so silence has to be its own state. Plus the taxonomy axes, and why signal_structure is load-bearing: a dual gate can hold its first signal above threshold all run and never fire, so one signal's range does not establish liveness for it.

Every command named in the README is now verified to exist, and the layout block lists the modules that are actually there.

179 passed, lint clean.

It is the front door and it was describing the previous two designs: `examples/`
and `example-runs/` as paths, "arm" as the word for a policy, and none of
`admitperf demo`, `admitperf experiments`, `compare --experiment`, the naming
fields, the reporting items or the terminology section.

Added, because the README never explained any of it:

  Naming a measurement — experiment, run, notes and provenance, and why grouping
  is declared rather than inferred from a directory. Moving a file should not
  silently change what a result claims to be.

  How it connects to the survey — the seven reporting items with the demo's actual
  statuses, including why `—` is neither a pass nor a failure: the survey's finding
  is that the corpus is SILENT on these, so silence has to be its own state. Plus
  the taxonomy axes, and why signal_structure is load-bearing — a dual gate can
  hold its first signal above threshold all run and never fire.

Every command named in the README is now verified to exist, and the layout block
lists the modules that are actually there.

179 passed, lint clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@harshuljain13 harshuljain13 self-assigned this Oct 5, 2026
@harshuljain13 harshuljain13 added the documentation Improvements or additions to documentation label Oct 5, 2026
@harshuljain13 harshuljain13 added this to the 0.1.0 milestone Oct 5, 2026
@harshuljain13
harshuljain13 merged commit 565182b into main Oct 5, 2026
4 checks passed
@harshuljain13
harshuljain13 deleted the docs/readme-and-spec branch October 5, 2026 10:25
@harshuljain13
harshuljain13 requested a review from tsah20 October 5, 2026 11:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant