docs: reframe ARK as a concept-complete reference/idea repo - #24
Merged
Conversation
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
force-pushed
the
chore/idea-repo-reframe
branch
from
July 25, 2026 01:39
56c479b to
258a1b9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)
## Status & scopesection: Implemented (concept-complete) / ideas it demonstrates / Out of scope.Initial Target Users→Who might find it useful; descriptionproducts→runtimes.② Runnable example (
examples/pipeline)sanitize → classify → policy → report, wired topnpm demo.③ Stale-noise gate — honestly scoped out
recentWindowtimestamp docs in@ark/coreand the schema so they no longer claim stale-noise detection exists.④ Fixed contradictions the reframe exposed in adjacent docs
@ark/*npm releases (fixes goes tomain).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 demoruns and matches its documented output.