script/fmt ran prettier with default settings over root-level *.md and
*.json, swallowing every failure with `|| true`, while script/fmt-check
checked gofmt only. The formatter and the gate therefore disagreed
silently: `make fmt` rewrote markdown that `make check` never looked at,
including REPO_POLICIES.md, which is a verbatim copy of an authoritative
upstream document that local tooling must not touch.
Configuration:
- .prettierrc pins the two policy deviations from prettier defaults,
four-space indents and proseWrap: always. Nothing else.
- .prettierignore excludes REPO_POLICIES.md so no local run can drift it
from upstream again, plus .golangci.yml (user-owned, and listed even
though the current file set does not reach it) and node_modules,
vendor, bin.
One canonical file set:
- New script/prettier takes --write or --check and applies the same
patterns in both modes, so script/fmt and script/fmt-check cannot
drift apart by construction. The patterns are repo-wide (**/*.md,
**/*.json) rather than root-only, so markdown in subdirectories such
as a future docs/ is covered.
- No `|| true` anywhere, and no --no-error-on-unmatched-pattern: both
patterns always match tracked files, so an empty match means the glob
broke and prettier should say so instead of passing vacuously. A
missing prettier is a hard error naming script/bootstrap, not a
silent skip.
Pinned prettier:
- package.json/yarn.lock pin prettier 3.9.6; the lockfile carries the
integrity hash, and --frozen-lockfile enforces it. script/prettier
prefers node_modules/.bin/prettier and warns on stderr when it has to
fall back to a PATH prettier of unknown version.
- script/bootstrap now installs node, yarn, and the locked JS deps. Its
NODE_VERSION and YARN_VERSION pins already existed.
Docker gate:
- The golangci-lint image has no node, so the lint stage runs the new
script/fmt-check-go (the Go half of fmt-check, extracted) instead of
the whole thing.
- The markdown half gets its own stage on a digest-pinned node image
shipping exactly the node and yarn versions bootstrap pins. The
builder stage takes a COPY --from dependency on it, so BuildKit cannot
skip it and a markdown violation fails `docker build .` rather than
being skipped somewhere nobody looks.
Markdown files other than REPO_POLICIES.md are reformatted here for the
first time under the policy settings.
## Summary
Performs a design and status review of the codebase and adds a comprehensive TODO section to `README.md` listing remaining work for a 1.0 release.
### What changed
- **README.md**: Added a `TODO: Remaining Work for 1.0` section covering:
- **7 design questions** requiring @sneak's input before implementation (manifest type export, Go module path, GPG vs pure-Go crypto, format framing, etc.) — each with an answer field for inline decisions
- **Implementation tasks** organized by category: repo infrastructure, format & correctness, library, CLI, testing & robustness, documentation, and release checklist
- Updated build status section (removed stale Drone CI badge, replaced with description of current Docker-based CI)
- **TODO.md**: Removed — items integrated into README TODO section
- **AGENTS.md**: Updated reference from `TODO.md` to README TODO section
### Design review findings
**What works well:**
- Core library (Builder, Scanner, Checker) is solid with good test coverage
- Format specification is well-designed (protobuf + zstd, multihash, deterministic serialization)
- CLI covers all major operations (gen, check, list, export, freshen, fetch)
- Test suite is thorough — builder, scanner, checker, GPG, CLI integration, corruption detection
- afero abstraction enables clean testing without filesystem side effects
**Key gaps for 1.0:**
- Missing repo infrastructure (`.golangci.yml`, `.editorconfig`, CI workflow)
- `manifest` type is unexported — consumers can't use it in their own type declarations
- GPG signing shells out to `gpg` subprocess — fragile and may not be installed
- Go module path inconsistency between `go.mod` and proto `go_package`
- `fetch` command lacks retry logic and has no HTTP timeout
- Missing fuzz tests for untrusted input deserialization
- Freshen CLI command has incomplete integration test coverage
closes#47closes#50
Co-authored-by: user <user@Mac.lan guest wan>
Co-authored-by: clawbot <clawbot@noreply.git.eeqj.de>
Co-authored-by: Jeffrey Paul <sneak@noreply.example.org>
Reviewed-on: #54
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>
