STE-Code REPOSITORY v1.0.0

STE-Code REPOSITORY v1.0.0

Tag family. v1.0.0 is the full first release. It is accompanied by two
companion tags that slice the same content along a different axis:
STANDARD-1.0.0 carries the ASD-STE100 → code-documentation adaptation (the
rules, categories, dictionary, and level prompts), and FLAVOR-1.0.0 carries
the linguistic extension layer. Neither companion tag changes the other; they
are parallel views of one release, and v1.0.0 bundles both.

Tag, commit, and how to read these numbers

This note describes the first public release of the STE-Code standard. Every
measurement in it was taken at the release tag commit 0cf59e4 (tagged
v1.0.0), not at any later HEAD. Post-tag commits are explicitly out of
scope; we do not mix tag facts with working-tree facts.

Item	Value
First commit in range	bb1b29a - "chore: Initialize clean repository - fully anonymized, generalized"
Release tip (this note)	0cf59e4 - the tip commit's subject reads "roadmap: 6-phase master integration plan …", but that commit actually adds a 7-phase roadmap (Phase 0-6); see "Contradictions in the original published note"
Full release tag	v1.0.0 = 0cf59e4
Companion standard tag	STANDARD-1.0.0 = 7e20b0d (earlier than v1.0.0)
Companion flavor tag	FLAVOR-1.0.0 (linguistic layer extension)

Measurement rule. All file, line, commit, and content counts below are
measured at 0cf59e4. They are not re-derived from HEAD, and they do not
reflect any later patch.

Headline stats (all at 0cf59e4)

This is the initial repository import plus the first release, so the line
counts are dominated by file creation, not churn. The +113,800 is the volume
of new content introduced across the range; the −34,521 is in-range
refactoring and shaping of that new content, not deletion of a pre-existing
product. Read it as a founding footprint, not as edit activity.

Metric	Value
Files changed (bb1b29a..0cf59e4)	1,850
Lines	+113,800 / −34,521 (creation-dominant, not churn)
Commits	159 total (148 non-merge + 11 merge)
ste-code/ impact	961 files, +45,079 / −10,518
Adapted rule units	55 (51 writing rules + 4 grammar recommendations)
Code-domain categories	22
Dictionary entries adapted	560 (from ~2,149 source ASD-STE100 words)
Level system prompts	4 assembled (~1.2K-45K tokens) + level-5 full specification (~100K)
FLAVOR checking layers	12 specified, 5 enforced by reference linter
FLAVOR workflows	17
Benchmark	59 tests / 14 categories
Quality markers	0 FIXME (substance verified), 0 CRLF
Quality sweeps	2 passes over 65 files
Control-group pass rate	11.9% (committed, verifiable)

This is a standard release

There is no prior standard to correct, deprecate, or supersede - this is the
first one. v1.0.0 ships the STE-Code adaptation of ASD-STE100 Issue 9
(January 2025, ASD Europe) tailored to code documentation, the companion
FLAVOR-1.0.0 linguistic layer, and a benchmark that measures how well the
adaptation holds up.

What actually shipped:

• STANDARD-1.0.0 - the adaptation itself: 51 writing rules + 4 grammar
  recommendations, 22 code-domain categories, a controlled dictionary of 560
  adapted entries, and 4 deployable level system prompts plus a level-5 full
  specification.
• FLAVOR-1.0.0 - the linguistic layer: 12 specified checking layers
  (semantic roles, single referent, epistemic marking, quantifier precision,
  register profiles, and beyond), 17 workflows, and a reference linter.
• Benchmark - 59 tests across 14 categories, with a committed control-group
  baseline at 11.9% pass.

Because it is the first release, the framing throughout is "here is what we
built and how we know it is true," not "here is what changed." Where the
original published note drifted into marketing claims, these notes replace each
with a verified fact and name the source.

The central theme: a faithful, auditable adaptation

The whole point of v1.0.0 is that someone took a real, published industry
standard - ASD-STE100 Issue 9 - and adapted it, rule by rule, for the specific
job of writing code documentation. The work was not invention; it was
translation under discipline. The theme that runs through every chapter is
fidelity with evidence: each rule, category, and dictionary entry can be
traced back to its source, and each claim about the release can be checked
against the tree at 0cf59e4.

Concretely, the adaptation produced:

• 51 writing rules drawn from ASD-STE100's sections 1-9, reshaped for
  code-domain use (comments, error messages, config files, identifiers, and so
  on).
• 4 grammar recommendations (the "GR" units) carried over as guidance rather
  than hard rules.
• 22 code-domain categories - the controlled vocabulary is organized into 22
  noun categories drawn from the source standard's part-of-speech taxonomy.
• A controlled dictionary of 560 adapted entries, sampled and reshaped from
  roughly 2,149 source ASD-STE100 words.
• 5 deployable writing depths - 4 assembled level system prompts plus a
  level-5 full specification - so the same standard can be applied at anything
  from a tight inline-comment budget to specification-grade documentation.
• A linguistic FLAVOR layer that extends the base standard with semantic and
  epistemic checks, and a benchmark to measure whether the adaptation
  actually improves writing.

The "auditable" half of the theme is why this note names the tag commit on every
page and why it keeps separating verified facts from reported ones.

What the standard contains

Using the corrected counts verified at 0cf59e4:

• 55 adapted rule units - 51 writing rules + 4 grammar recommendations. This
  is the canonical v1.0.0 number. (Trajectory note: rules 2.3, 6.6, and
  8.7 were added after v1.0.0, in the v1.1.0 line, bringing that release to
  54 + 4 = 58 units. So the standard is 55 at first release, 58 by v1.1.0 -
  the counts are not portable across releases; measure each tag directly.)
• 22 categories - verified by counting ## Category headings in
  a-categories.md (Category 1 "Official Parts Information" … Category 22
  "Animals, Plants, and Other Life Forms").
• 560 adapted dictionary entries - counted from ## WORD (pos) headings in
  the dictionary file; 452 approved and 108 marked UNNAPROVED (a persistent
  source-file typo). These are adapted from ~2,149 source ASD-STE100 words
  (the source dictionary's approved + unapproved counts). The dictionary does
  not contain 2,149 entries - that figure describes the source surveyed,
  not what was adapted.
• 4 assembled level system prompts plus a level-5 specification:
  • Level 1 - level1/system-prompt.txt, 4,473 bytes (~1.2K tokens)
  • Level 2 - level2/system-prompt.txt, 17,884 bytes (~4.5K tokens)
  • Level 3 - level3/system-prompt.txt, 31,160 bytes (~8K tokens)
  • Level 4 - level4/system-prompt.txt, 126,528 bytes (~45K tokens)
  • Level 5 - a full specification (~100K tokens) delivered as 51 per-rule
    summary.md directories rather than a single assembled prompt file; a
    standalone ste-code-level5-max.txt (228,903 bytes) also exists.

The level prompts are deliberately sized so a consumer can pick the depth that
fits their budget - from an ultra-tight level-1 prompt for inline use up to the
specification-grade level-5 material.

The FLAVOR linguistic layer

FLAVOR-1.0.0 adds a linguistic extension on top of the base standard. The
layer stack in FLAVOR.md specifies 12 checking layers:

1. Epistemic Marking
2. Actor Model
3. Single Referent Rule
4. Semantic Roles
5. Verb Frames
6. Negation Control
7. Scope Bracketing
8. Discourse / Anaphora
9. Quantifier Table
10. Register Profiles
11. Lifecycle States
12. Definition Discipline

Be precise about enforcement. The reference linter, ste_code_lint.py,
implements 5 of the 12 layers: semantic_roles, single_referent,
epistemic, quantifiers, and register. The remaining 7 are specified but
not yet enforced by the shipped tool.

Be precise about documentation, too. Layers 6 (Negation Control), 7 (Scope
Bracketing), 8 (Discourse / Anaphora), and 12 (Definition Discipline) point
their spec anchors at a SPECIFICATION.md that does not exist - not at the
tag, and not at HEAD. So 4 of the 12 advertised layers have no backing
specification document, in addition to not being linted. This is a live repo
inconsistency (see "Known limitations"), not a claim of this note.

The benchmark

The release ships a benchmark of 59 tests across 14 categories (five files
of 5 tests, five of 4, two of 3, two of 4 - summing to 59). Verified at the tag:
the run directory results-v2/original-20260730-145213/ contains exactly 59
prompt files and 59 output files, so the run genuinely executed all 59 tests.
The benchmark records its evidence in those per-test prompt/output pairs.

Two results are reported for the benchmark, and they sit on very different
footing:

• Control group - 11.9% pass (7/59), avg correctness 0.471. This is
  committed and verifiable:
  results-control/run-20260730-010032/ aggregate-results.json records
  total_tests: 59, passed: 7, pass_rate_pct: 11.9, avg_correctness: 0.471.
  Cite it freely; the artifact is in the tree.
• STE-Code group - 96.6% (57/59), avg score 0.919. This is a reported
  result, not an independently reproducible one at this tag. The STE-Code run
  directory contains the 59 prompts and 59 outputs but no committed
  per-test-results.json and no aggregate-report.json - the scoring step
  (rescore.py) was never committed. The 96.6% figure lives only as prose in
  ste-code/README.md and .agents/AGENTS.md. Present it as reported, and
  flag that the aggregate was not committed. The raw 59-test run itself is real
  and citable; only its score is unverified at the tag.

To keep the scientific boundary honest: the benchmark is a set of deterministic,
model-scored cases. It demonstrates the adaptation's intent and gives a
committed control baseline, but it is not a paired control-vs-candidate
experiment with a captured, scored candidate run, and it is not proof of
end-to-end live behaviour.

Agent-agnostic tooling

The tooling is genuinely backend-agnostic in architecture, but it is
pre-configured for Hermes and nothing else ships working out of the box. At
the tag, .agents/config/agents.yaml declares default_agent: hermes only.
Claude, Codex, and a generic backend exist strictly as commented-out stub
blocks under the header "Stub backends (uncomment and configure when ready)."
The runner will use them once uncommented and configured, but they are not live
at v1.0.0.

So the honest framing is: pre-configured for Hermes; Claude, Codex, and custom
backends supported via ready-to-uncomment stubs - not "supports Claude/Codex
out of the box."

Quality and provenance

Three quality claims were checked against the tree at 0cf59e4, and they hold:

• 0 FIXME markers (in substance). git grep FIXME returns 6 hits, but none
  is an unresolved placeholder - they are the quality claim itself, legitimate
  content vocabulary, and a teaching example. This is corroborated by the sweep
  log, which records 11 leftover FIXME placeholders removed in a prior pass. The
  cleanup really happened.
• 0 CRLF. Every .md/.txt/.json/.py blob under ste-code/ at the tag was
  scanned for carriage returns: zero files with CRLF endings.
• 2 quality sweep passes over 65 files. Five batch reports, each processing
  13 files, sum to 65. Two passes are evidenced by two distinct report sets
  (pass 1 and pass 2).

All three are verified, not asserted.

Known limitations / internal doc inconsistencies

These are live inconsistencies inside the v1.0.0 repository itself - they
are not errors in this release note, but a reader who follows the notes into the
repo will hit them, so they are stated here to prevent being misled:

• artifacts/README.md says 19 categories; the standard has 22. The actual
  a-categories.md has 22, and ste-code/README.md agrees. The artifacts
  README is stale at the tag. (The note's "22" is correct.)
• ste-code/README.md says "53 rules" in its quality block, while the same
  file's Stage 4 box says "51 rules + 4 GR." 53 matches neither 51 nor 55. Do
  not propagate the 53.
• artifacts/sweep-report.md is referenced but missing. git cat-file at
  the tag confirms it does not exist; the real reports live under
  .agents/tmp/sweep/.
• SPECIFICATION.md is missing at the tag and at HEAD. Four FLAVOR layers
  (6, 7, 8, 12) anchor their specs there, so those layers have no backing spec
  document.
• The reference linter enforces 5 of 12 FLAVOR layers (see "The FLAVOR
  linguistic layer"). The other 7 are specified but not enforced.

Contradictions resolved (repository view)

The original published v1.0.0 note was a flat, marketing-style draft. Where it
stated a number that the verified tree contradicts, this note uses the verified
value. Each correction is RESOLVED:

#	Original claim	Verified correction	Status
1	"2,149 dictionary entries"	560 adapted entries from ~2,149 source ASD-STE100 words	RESOLVED
2	"18 workflows"	17 workflows (WORKFLOWS.md)	RESOLVED
3	"5 level system prompts (1.2K-45K)"	4 assembled prompts (~1.2K-45K) + level-5 full specification (~100K)	RESOLVED
4	"supports Claude, Codex … out of the box"	pre-configured for Hermes; Claude/Codex/custom via ready-to-uncomment stubs	RESOLVED
5	"6-phase roadmap"	7-phase roadmap (Phase 0-6)	RESOLVED
6	implied 55 rules stable	55 at first release, 58 by v1.1.0 (rules 2.3, 6.6, 8.7 added later)	RESOLVED

Note that "55 adapted rules" in the original was correct for v1.0.0 - the
error was only in the dictionary count, the workflow count, the level-prompt
count, the agent-support claim, and the roadmap phase count.

Migration / Quick Start

The original Quick Start commands are valid at this tag (0cf59e4). They
are reproduced verbatim because the paths exist at the tag even where later
refactors moved them:

# Use Level 1 prompt (~1.2K tokens) with any LLM
cat ste-code/artifacts/level1/system-prompt.txt

# Run the linguistic linter
python3 ste-code/linguistics/ste_code_lint.py sample-doc.md

# List available agent backends
python3 .agents/tools/agent-runner.py --list

Two path caveats worth knowing before you follow the notes into HEAD:

• The agent-runner at this tag lives at .agents/tools/agent-runner.py. It
  later moved to .agents/tools/lib/agent-runner.py, so HEAD's AGENTS.md
  shows the newer path - but the v1.0.0 note above is correct for its own tag.
• The linter enforces only 5 of 12 FLAVOR layers (see "The FLAVOR linguistic
  layer"); the rest are specified, not checked.

Version boundary

• v1.0.0 (0cf59e4) is the first full release - the initial repo
  import plus the standard, flavor, and benchmark, bundled together.
• STANDARD-1.0.0 (7e20b0d) and FLAVOR-1.0.0 are the companion
  standard/flavor tags that slice the same release along the standard vs.
  linguistic-layer axis.
• The next standard increment is v1.1.0, which adds rules 2.3, 6.6,
  and 8.7 (bringing the count to 54 + 4 = 58 units). When reading later
  release notes, remember that "54 rules" describes v1.1.0 onward, not the
  v1.0.0 first release.

---

Adapted from ASD-STE100 Issue 9 (January 2025), ASD Europe. All counts verified
at tag 0cf59e4; post-tag commits are out of scope. See ste-code/README.md
for full Credits & References.