Skip to content

Separate the published tree from internal planning material - #68

Merged
HackTuah merged 4 commits into
mainfrom
chore/public-repo-posture
Sep 23, 2026
Merged

HackTuah merged 4 commits into
mainfrom
chore/public-repo-posture

Conversation

@HackTuah

Copy link
Copy Markdown
Member

The repository is public and is read by people evaluating the project for adoption. This change
separates what those readers need from what is internal to building it.

What moved out of the published tree

Per-increment specifications and working notes (159 files), the forward roadmap, the process
templates, the internal process document and the process checker. They were the largest non-code
directory in the repository and described how the work is organised rather than what the software
is or what it guarantees. They are retained by the maintainers.

What replaces them, so the public record is not weaker

  • CHANGELOG.md, derived from the tags rather than written from memory, recording what each
    increment delivered and how it was verified.
  • docs/03-conventions.md gains two sections lifted from the internal contract and rewritten
    as project standards: the engineering rules (modularity behind behaviours, compiled architectural
    boundaries, OTP supervision, no runtime evaluation of model output, pinned dependency versions,
    tests that do not reach the network) and the rules of evidence (a failing test before the fix,
    populations derived by command, verification naming its exit code, records appended not
    rewritten, deferrals carrying an owner and a lift condition).
  • README.md gains an assurance posture table stating the properties the build enforces and
    what enforces each: memory safety by language choice, architectural integrity by a compile-time
    boundary check, least privilege for effects through the permission gate and the separation of
    identity from authority, auditability through an Ed25519 signed receipt chain, untrusted-content
    handling at the boundary, approved cryptography measured on a FIPS-mode CI leg, supply-chain and
    licence audits on every commit, DCO provenance enforced twice, and the standards register's rule
    that no public claim is made without a row and an evidence path.

Verification

mix gate exits 0: formatting, compile with warnings as errors, boundary check, release build
check, Credo strict, Sobelow, dependency and licence audits, 561 tests, coverage floor.

The gate keeps every check that applies to published code and drops only the internal process
check. Three tests asserting the shape of an internal document moved with it. The gate alias test
previously asserted that the process checker was the final step; it now asserts the release check
is present exactly once, which is the property that actually protects the build.

The repository is public and is read by people evaluating the project for
adoption. Internal planning material - per-increment specifications, working
notes, the forward roadmap, the process templates and the process checker -
is not useful to that reader and crowded out the material that is: the
architecture, the security model, the standards register and the decision
records. It moves out of the published tree and is retained by the maintainers.

What replaces it, so the public record is not weaker:

- CHANGELOG.md, derived from the tags, records what each increment delivered
  and how it was verified.
- docs/03-conventions.md gains the engineering rules and the rules of evidence
  that governed every change, written as project standards rather than as
  instructions to a contributor.
- README.md gains an assurance posture section stating the properties the build
  enforces - memory safety, compiled architectural boundaries, least privilege
  for effects, a signed receipt chain, untrusted-content handling, the FIPS leg,
  supply-chain audits, DCO provenance and the claim discipline of the standards
  register - each naming what enforces it.

The gate keeps every check that applies to published code and drops only the
internal process check. Three tests asserting the shape of an internal document
move with it; the gate alias test now asserts the release check instead.

Signed-off-by: Ayla Croft <aylacroft@proton.me>
…ndency advisory

Two gaps against the OpenSSF Best Practices passing criteria, which the Linux
Foundation requires at its Incubation stage:

- SECURITY.md published a reporting address but no timeframe. It now states a
  14-day acknowledgement target, says plainly that a single maintainer makes it
  a target rather than a commitment, and asks for coordinated disclosure.
- The one open advisory is recorded rather than left implicit. GHSA-wrw7-89jp-8q8g
  against glib 0.18.5 is transitive through the GTK 0.18 stack Tauri 2.11.5
  requires on Linux, so it is fixed by a Tauri release built on gtk-rs 0.20 and
  not by a direct bump. Its scope is stated and checkable: the headless release
  is steps: [:assemble] with no Burrito and no src-tauri, so a server deployment
  does not ship the dependency at all. The row carries an owner and the condition
  that lifts it.

Signed-off-by: Ayla Croft <aylacroft@proton.me>
The FIPS image tag is a hash of the files that define the image, so any change
to them - including a comment - names an image that must be built before it can
be pulled. The fips job takes that image as its container, which GitHub pulls
before the job's first step, so the job cannot retry the pull itself: it fails
with 'manifest unknown' and no output. The fips-image workflow builds on the
same event, so the two race and this job always loses, producing a red check on
a pull request for a change that is correct.

fips-tag, which already gates the fips job, now waits for the manifest to
appear, polling for up to 30 minutes. The image is a function of its inputs, so
the image it waits for is exactly the one the commit needs. A timeout fails with
the reason and where to look, because 'still building' and 'will never exist'
need different responses from the person reading it.

Signed-off-by: Ayla Croft <aylacroft@proton.me>
Scorecard measures the repository against the OpenSSF's own checks - branch
protection, pinned dependencies, dangerous workflow patterns, token permissions,
signed releases, maintenance - and publishes the result, so that someone
evaluating this project can read its posture without being asked to trust a
claim made in the README. It runs weekly and on pushes to main, and uploads to
the code-scanning dashboard so a regression appears beside code findings.

test/workflows_test.exs restores a property that left with the internal process
checker and adds one. Every workflow and the Dependabot configuration must parse
as YAML, because GitHub reports a malformed workflow on its own page rather than
on the pull request, which is the wrong place to discover it. And every
third-party action must be pinned to a full commit hash rather than a tag, since
a tag can be moved to point at different code after it was reviewed; that is
Scorecard's Pinned-Dependencies check, held here rather than waited for. The
population is git ls-files .github, so a workflow added without either property
is caught by its own existence.

Signed-off-by: Ayla Croft <aylacroft@proton.me>
@HackTuah
HackTuah merged commit 0841059 into main Sep 23, 2026
8 checks passed
@HackTuah
HackTuah deleted the chore/public-repo-posture branch September 23, 2026 13:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant