docs: establish Core Reset governance

[mohanagy]

Summary

Establish and record the accepted Madar Core Reset governance before any implementation begins.

• add the versioned Core Reset design linked to RFC [RFC]: Madar Core Reset — narrow TypeScript semantic-path engine #577;
• add a machine-readable keep/rebuild/move/delete/defer manifest;
• add the technical and business phase-gate scorecard;
• replace the obsolete version/feature roadmap with one outcome-driven roadmap;
• add one temporary Core Reset work-item form and PR deletion contract;
• replace the hardcoded old-roadmap test instead of extending it;
• route contributors and issue-template navigation through the new source of truth.

Why

Madar's current problem is architectural accumulation: new extraction, retrieval, recovery, proof, and integration paths have been added without consistently retiring their predecessors. The reset must begin with an accepted product contract, dependency order, deletion manifest, and stop gates so it cannot become another compatibility layer.

This PR changes governance and documentation only. It starts no reset implementation.

Testing

• npm run test:run -- tests/unit/core-reset-governance.test.ts tests/unit/launch-checklist-doc.test.ts tests/unit/install.test.ts — 79/79 passed
• npm run typecheck
• npm run build
• git diff --check
• Parsed the removal manifest and both GitHub issue YAML files with the installed yaml package
• Full GitHub Actions matrix passed on acceptance commit e70f6dd (Ubuntu, macOS, and Windows on Node 20 and 22). Local full-suite attempts hit machine-resource timeouts in unrelated benchmark subprocess tests; focused tests pass.

Core Reset contract

• RFC requirement: establish governance and acceptance artifacts before implementation
• Parent issue: [RFC]: Madar Core Reset — narrow TypeScript semantic-path engine #577
• Removal-manifest IDs: all initial disposition entries
• Exit gate: RFC acceptance checklist resolved and this governing PR merged
• Production LOC added: 0
• Production LOC removed: 0
• Net production LOC: 0
• Superseded paths deleted: tests/unit/roadmap-docs.test.ts; obsolete roadmap content replaced

Reset scope checks

• This PR records the accepted RFC and authorizes only scope and baseline after merge
• Obsolete roadmap assertions were replaced rather than retained
• No permanent fallback or parallel implementation was added
• No evaluation-repository-specific production logic was added
• Production does not import development-only evaluation tooling
• The removal manifest and scorecard were added

Checklist

• Documentation updated
• Tests added/updated for changed governance behavior
• No private corpora, secrets, credentials, proprietary prompts, raw logs, or generated artifacts
• PR is limited to Core Reset governance

Related issues

• Governs [RFC]: Madar Core Reset — narrow TypeScript semantic-path engine #577
• Accepted disposition for P0: Cross-layer retrieval returns UI noise and drives agents into broad fallback #565, P0: Codex installer writes project MCP config that Codex CLI never loads #567, P2: madar --help omits the supported generate --spi option #571, and P0: Simplify retrieval to one bounded phase-complete evidence pass #574 is documented and remains dependency-gated

Summary by CodeRabbit

• Documentation
  • Replaced the roadmap with a gated Core Reset roadmap focused on outcomes, validation, and release decisions.
  • Added Core Reset design, removal manifest, and scorecard documents, plus contribution guidance.
  • Updated issue and pull request templates with structured Core Reset governance checklists.
  • Updated the public roadmap link to point to the roadmap documentation.
• Tests
  • Added unit tests to enforce Core Reset governance consistency across roadmap, templates, and manifests.
  • Updated launch checklist documentation tests and removed outdated roadmap test coverage.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds Core Reset governance documentation, a removal manifest, a validation scorecard, contributor templates, roadmap rules, and unit tests covering consistency across these artifacts.

Changes

Core Reset governance

Layer / File(s)	Summary
Reset proposal and scope contract docs/designs/2026-07-19-core-reset.md, docs/core-reset/removal-manifest.yml	Defines reset architecture, dependency-ordered dispositions, production boundaries, delivery constraints, and deferred capabilities.
Roadmap and release evidence docs/roadmap.md, docs/core-reset/scorecard.md	Defines authorized phases, acceptance gates, evidence requirements, validation tracks, release criteria, and post-validation scope.
Contributor and review contracts .github/ISSUE_TEMPLATE/*, .github/pull_request_template.md, CONTRIBUTING.md	Adds structured work-item fields, pull-request checks, contribution guidance, and roadmap routing.
Governance consistency tests tests/unit/core-reset-governance.test.ts, tests/unit/launch-checklist-doc.test.ts	Validates governance links, manifest structure, template content, and launch-checklist documentation scope.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• mohanagy/madar#268: Modifies the roadmap and related roadmap assertions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely reflects the main change: establishing Core Reset governance.
Description check	✅ Passed	The description matches the template with Summary, Testing, Checklist, and Related issues, and includes substantive details.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/core-reset-governance

---

_{Comment @coderabbitai help to get the list of available commands.}

[mohanagy]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

tests/unit/core-reset-governance.test.ts (1)

69-79: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover the temporary Core Reset work-item form.

This test does not read .github/ISSUE_TEMPLATE/core_reset_work_item.yml, so that required contributor entry point can regress while the governance suite remains green. Add assertions for the form’s required reset fields, or add a dedicated test for it.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/unit/core-reset-governance.test.ts` around lines 69 - 79, Add coverage
for .github/ISSUE_TEMPLATE/core_reset_work_item.yml in the governance tests,
either within routes contributors through the reset contract or a dedicated
test. Read the form and assert that its required Core Reset work-item fields are
present, using the field labels or symbols defined by the form, while preserving
the existing issue-config and pull-request-template assertions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/core-reset/removal-manifest.yml`:
- Around line 93-99: Update the non-code-and-other-language-ingest entry in
removal-manifest.yml so every value under sources is a resolvable glob or
concrete file path; replace the descriptive extraction-path label with the
relevant paths, or move that description into a notes field while preserving the
manifest’s intended scope.

In `@tests/unit/core-reset-governance.test.ts`:
- Line 25: Broaden the roadmap assertion in the governance test so it rejects
any versioned or feature-style roadmap headings, rather than only the literal
“## v0.26” heading. Update the expectation around roadmap to use a pattern or
equivalent assertion covering all such heading formats while preserving the
existing failure behavior for obsolete roadmap content.
- Around line 56-64: Update the manifest validation in the item loop to reject
empty or whitespace-only values: trim each item.id before uniqueness validation,
and trim item.exit_gate plus conditional item.remove_when before checking they
are non-empty. Preserve the existing disposition and status validation, and
ensure uniqueness is evaluated on the trimmed IDs.

---

Nitpick comments:
In `@tests/unit/core-reset-governance.test.ts`:
- Around line 69-79: Add coverage for
.github/ISSUE_TEMPLATE/core_reset_work_item.yml in the governance tests, either
within routes contributors through the reset contract or a dedicated test. Read
the form and assert that its required Core Reset work-item fields are present,
using the field labels or symbols defined by the form, while preserving the
existing issue-config and pull-request-template assertions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 5d4040f3-8dba-441c-8101-bfeb19287832

📥 Commits

Reviewing files that changed from the base of the PR and between 754a806 and 976493a.

📒 Files selected for processing (11)

• .github/ISSUE_TEMPLATE/config.yml
• .github/ISSUE_TEMPLATE/core_reset_work_item.yml
• .github/pull_request_template.md
• CONTRIBUTING.md
• docs/core-reset/removal-manifest.yml
• docs/core-reset/scorecard.md
• docs/designs/2026-07-19-core-reset.md
• docs/roadmap.md
• tests/unit/core-reset-governance.test.ts
• tests/unit/launch-checklist-doc.test.ts
• tests/unit/roadmap-docs.test.ts

💤 Files with no reviewable changes (2)

• tests/unit/roadmap-docs.test.ts
• tests/unit/launch-checklist-doc.test.ts

[mohanagy]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.