Skip to content

docs: reframe ARK as a concept-complete reference/idea repo - #24

Merged
mikim merged 1 commit into
mainfrom
chore/idea-repo-reframe
Jul 25, 2026
Merged

docs: reframe ARK as a concept-complete reference/idea repo#24
mikim merged 1 commit into
mainfrom
chore/idea-repo-reframe

Conversation

@mikim

@mikim mikim commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

Repositions ARK honestly as a reference implementation / idea repo (concept-complete) rather than a product in progress, and adds a runnable example so the concept is verifiable from a checkout. No package behavior changes.

① Honest framing (README)

  • New top status callout: reference implementation, not published to npm, product-scale work deliberately out of scope.
  • Multi-phase Roadmap + Success Metrics → one ## Status & scope section: Implemented (concept-complete) / ideas it demonstrates / Out of scope.
  • Quickstart no longer implies an npm release; Initial Target UsersWho might find it useful; description productsruntimes.

② Runnable example (examples/pipeline)

  • Deterministic end-to-end demo sanitize → classify → policy → report, wired to pnpm demo.
  • Its README "Expected output" matches the actual run byte-for-byte (verified); typechecked by the root tsconfig so it can't silently rot.

③ Stale-noise gate — honestly scoped out

  • The dangling "stale-noise (time-based) gate still pending" is declared out of scope (the burst gate already demonstrates noise suppression; a time-based gate would add speculative, non-deterministic-leaning behavior).
  • Aligned the earmarked-but-unused recentWindow timestamp docs in @ark/core and the schema so they no longer claim stale-noise detection exists.

④ Fixed contradictions the reframe exposed in adjacent docs

  • SECURITY.md no longer asserts published @ark/* npm releases (fixes goes to main).
  • CONTRIBUTING.md / ARCHITECTURE.md frame the release tooling as configured-but-dormant.

Rigor

Built with two agent passes: a pre-write codebase read (to ground every claim) and a post-write adversarial verification (docs-vs-code accuracy, framing consistency, example faithfulness). Verdict commit_after_minor_fixes; the one must-fix (SECURITY.md) and the sensible nice-to-haves are included here.

pnpm check (typecheck + lint + schema + tests) green; pnpm demo runs and matches its documented output.

Position ARK honestly as a reference implementation rather than a product in
progress, and add a runnable example so the concept is verifiable from a
checkout. No package behavior changes.

- README: add a top "reference implementation / idea repo" status callout;
  replace the multi-phase Roadmap + Success Metrics with one "Status & scope"
  section (implemented / ideas demonstrated / explicitly out of scope);
  Quickstart no longer implies an npm release; "Initial Target Users" ->
  "Who might find it useful".
- examples/pipeline: a runnable, deterministic end-to-end demo
  (sanitize -> classify -> policy -> report) wired to `pnpm demo`; its README
  output matches the actual run byte-for-byte.
- Declare the time-based stale-noise gate out of scope (the burst gate already
  demonstrates noise suppression) and align the earmarked-but-unused
  recentWindow timestamp docs in @ark/core and the schema so they no longer
  claim stale-noise detection is implemented.
- Resolve framing contradictions the reframe exposed in adjacent docs:
  SECURITY.md no longer asserts published @ark/* npm releases; CONTRIBUTING.md
  and ARCHITECTURE.md frame the release tooling as configured-but-dormant.

Verified: `pnpm check` (typecheck + lint + schema + tests) green; `pnpm demo`
runs and matches its documented output.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@mikim
mikim force-pushed the chore/idea-repo-reframe branch from 56c479b to 258a1b9 Compare July 25, 2026 01:39
@mikim
mikim merged commit 1956492 into main Jul 25, 2026
4 checks passed
@mikim
mikim deleted the chore/idea-repo-reframe branch July 25, 2026 01:40
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