diff --git a/roadmap/infospace-s3-closeout/PLAN.md b/roadmap/infospace-s3-closeout/PLAN.md new file mode 100644 index 00000000..397badbe --- /dev/null +++ b/roadmap/infospace-s3-closeout/PLAN.md @@ -0,0 +1,172 @@ +# Infospace Tooling — Stage 3 Close-out + +## Context + +Stages 1 and 2 of the infospace tooling roadmap are complete. Stage 3 used the +Wealth of Nations / VSM example to validate the tooling end-to-end. Most of S3 +is done; this workstream finishes the remaining tasks, addresses deferred cleanup, +and formally closes the roadmap. + +**Parent roadmap:** `roadmap/infospace-tooling/PLAN.md` +**Example location:** `examples/infospace-with-history/` + +### State at workstream open (2026-02-26) + +| Item | Status | +|------|--------| +| S3.1 Migrate example to infospace config | ✅ Done | +| S3.3 Per-entity eval batch | ✅ 985/988 complete; metrics.yaml updated | +| S3.4 Tutorial rewrite | ✅ Done | +| S3.5 Supply-chain-vsm composition demo | ✅ Done | +| S3.2 Clean per-chapter git history | ⏳ Deferred — included here | +| 3 missing evaluations | ⏳ Outstanding | +| 4 follow-up items (commit b055c8d7) | ⏳ Outstanding | + +--- + +## Tasks + +### C.1 — Complete the 3 missing entity evaluations + +985 of 988 entities have evaluation files. Identify and evaluate the remaining 3. + +```bash +cd examples/infospace-with-history +# Identify missing slugs +comm -23 \ + <(ls output/entities/*.md | xargs -I{} basename {} .md | sort) \ + <(ls output/evaluations/*.md | xargs -I{} basename {} .md | sort) +# Evaluate each missing entity individually +markitect infospace evaluate --entity --provider openrouter +``` + +**Acceptance:** `ls output/evaluations/*.md | wc -l` returns 988. + +--- + +### C.2 — Run eval-summary and verify viability + +Run the aggregation command to update per_entity_mean from all 988 evaluations, +then check all 6 viability gates pass. + +```bash +cd examples/infospace-with-history +unset OPENROUTER_API_KEY # stale env var guard +markitect infospace eval-summary --update-metrics +markitect infospace viability +``` + +Current sample reading (985 entities): `per_entity_mean = 3.956` against threshold 3.5. +Expected: all 6 metrics pass. + +**Acceptance:** `markitect infospace viability` exits 0 and shows 6/6 PASS. + +--- + +### C.3 — Refresh the metrics report + +The metrics report was generated from chapters 1–4 only. Regenerate it from +the full 988-entity set. + +```bash +cd examples/infospace-with-history +markitect infospace check --provider openrouter # or reuse existing check outputs +markitect infospace history # confirm snapshot recorded +``` + +**Acceptance:** `output/metrics/metrics.yaml` reflects all 988 entities; a dated +snapshot exists in the metrics history. + +--- + +### C.4 — Document advanced usage patterns + +Write `examples/infospace-with-history/docs/advanced-usage.md` covering: + +- Incremental evaluation (adding entities after initial run, skip-if-exists behaviour) +- Re-evaluating after guideline changes (`--force` flag) +- Interpreting per-entity score distributions and identifying outliers +- Using `markitect infospace entities --sort-by score` to triage low scorers +- Reading and acting on collection check outputs (redundancy pairs, coverage gaps) + +**Acceptance:** File exists with ≥ 4 documented patterns, each with a worked command example. + +--- + +### C.5 — Add composition examples to documentation + +Document how the supply-chain-vsm example (`examples/supply-chain-vsm/`) demonstrates +composition. Add a `docs/composition-guide.md` covering: + +- What composition means (discipline binding) +- How supply-chain-vsm binds WoN as a discipline +- How to create a new infospace that uses an existing one as a discipline +- Viability requirement: the discipline must pass its own thresholds before binding + +Reference `examples/supply-chain-vsm/` throughout. + +**Acceptance:** `docs/composition-guide.md` exists and links to supply-chain-vsm. + +--- + +### C.6 — Performance benchmarking note + +Rather than a full benchmarking guide (out of scope for a 988-entity example), +record observed timings in a `docs/performance-notes.md`: + +- Eval batch duration (~4 hrs for 988 entities via OpenRouter) +- Tokens per entity (rough estimate from usage logs) +- Embedding cache hit rate after first run +- Recommendation: provider choice (OpenRouter vs Gemini) for different dataset sizes + +**Acceptance:** File exists with at least 4 concrete measurements or estimates. + +--- + +### C.7 — S3.2: Clean per-chapter git history (deferred cleanup) + +Create a clean branch where each of the 35 processed chapters has its own commit. +Chapters 1–8 are already done on branch `clean-example-history`; 27 remain. + +This is a cosmetic/archival task — it does not change output files. + +```bash +git checkout clean-example-history +# For each remaining chapter (9–35): +# cherry-pick or re-commit the chapter output files with a per-chapter message +git log --oneline clean-example-history # verify 35 chapter commits +``` + +**Acceptance:** Branch `clean-example-history` has exactly 35 chapter commits +(one per chapter), rebased onto current main. + +**Note:** This task can be done independently of C.1–C.6. Low urgency — do last. + +--- + +### C.8 — Formally close the S3 roadmap + +Update `roadmap/infospace-tooling/PLAN.md` to mark all S3 tasks as complete. +Add a close-out summary at the top of the file with final metrics and date. +Commit with a `docs(roadmap)` message. + +**Acceptance:** PLAN.md header shows all stages complete; committed to main. + +--- + +## Task order + +``` +C.1 → C.2 → C.3 + ↓ + C.4, C.5, C.6 (parallel) + ↓ + C.8 +C.7 (independent, do last) +``` + +## Out of scope + +- Adding new entities or chapters (the WoN example is complete at 988 entities) +- Re-running collection checks from scratch (existing results are valid) +- Publishing the example as a standalone dataset diff --git a/roadmap/testdrive-jsui-publication/PLAN.md b/roadmap/testdrive-jsui-publication/PLAN.md new file mode 100644 index 00000000..c4f8940c --- /dev/null +++ b/roadmap/testdrive-jsui-publication/PLAN.md @@ -0,0 +1,176 @@ +# TestDrive-JSUI — npm Publication + +## Context + +TestDrive-JSUI is a JavaScript-first markdown editor library living at +`capabilities/testdrive-jsui/`. Phases 1–6 (build system, bundling, testing, +migration) are complete. 84 tests pass (68 JS + 15 Python + 1 fixes). +Single source of truth: `capabilities/testdrive-jsui/js/`. + +This workstream covers the remaining work to publish the library to npm and +close out the capability. + +**Source:** `capabilities/testdrive-jsui/TODO.md` (Phases 7–9) +**Package name:** `testdrive-jsui` (to be confirmed in P.1) +**Current version:** 1.0.0 + +--- + +## Tasks + +### P.1 — Pre-publication: decide repository structure + +The library currently lives inside the markitect monorepo. Before publishing to +npm, decide whether it ships from here or from a dedicated repo. + +**Options:** +- A: Publish directly from `capabilities/testdrive-jsui/` — simpler, no repo split +- B: Extract to a standalone `testdrive-jsui` repo — cleaner for npm consumers + +Record the decision and proceed accordingly. + +**Acceptance:** Decision recorded; if B, standalone repo created and code copied. + +--- + +### P.2 — Pre-publication: verify Markitect integration + +Confirm the main Markitect application still works correctly with the current +capability code before publishing. + +```bash +cd /home/worsch/markitect_project +make testdrive-jsui-test-all # 84 tests must pass +# Manually verify view and edit modes in the running Markitect app +``` + +**Acceptance:** All 84 tests pass; view and edit modes confirmed working. + +--- + +### P.3 — Pre-publication: decide STANDALONE_PLAN.md + +`STANDALONE_PLAN.md` exists in the capability but its status is unclear. Either: +- Implement it (if it describes meaningful standalone work) +- Explicitly archive it with a note that the standalone use case is covered by the npm package + +**Acceptance:** File updated with a clear status note; or deleted if obsolete. + +--- + +### P.4 — Pre-publication: pack and dry-run + +Run the full pre-publish checklist. + +```bash +cd capabilities/testdrive-jsui +npm run lint # zero errors +npm test # all 84 tests pass +npm run build:prod # clean production build +npm pack # creates testdrive-jsui-1.0.0.tgz +npm install ./testdrive-jsui-1.0.0.tgz --dry-run # verify install +npm publish --dry-run # verify what will be published +``` + +Review `--dry-run` output: confirm only intended files are included (check +`.npmignore` or `files` field in `package.json`). + +**Acceptance:** `npm publish --dry-run` succeeds with expected file list; no +test files, source maps, or internal docs included unintentionally. + +--- + +### P.5 — Pre-publication: create release tag + +```bash +git tag -a v1.0.0 -m "Release testdrive-jsui v1.0.0" +# (push tag to remote when ready) +``` + +**Acceptance:** Tag `v1.0.0` exists on main; CHANGELOG.md entry present for 1.0.0. + +--- + +### P.6 — Publication: publish to npm + +```bash +cd capabilities/testdrive-jsui +npm login # if not already logged in +npm publish +``` + +Then verify: +- Package visible at `https://www.npmjs.com/package/testdrive-jsui` +- Wait 5–10 minutes, then check CDN availability: + - `https://cdn.jsdelivr.net/npm/testdrive-jsui@1.0.0/dist/testdrive-jsui.min.js` + - `https://unpkg.com/testdrive-jsui@1.0.0/dist/testdrive-jsui.min.js` + +**Acceptance:** Package installable via `npm install testdrive-jsui`. + +--- + +### P.7 — Publication: fresh install test + +In a clean temporary directory, install from npm and verify the library works +with a minimal HTML file. + +```bash +mkdir /tmp/testdrive-test && cd /tmp/testdrive-test +npm install testdrive-jsui marked +# Open standalone.html equivalent, confirm editor initialises +``` + +**Acceptance:** `new TestDriveJSUI({...})` works in a fresh install with no +reference to the capability source directory. + +--- + +### P.8 — Publication: GitHub release + +Create a GitHub release from the v1.0.0 tag with: +- Release notes (summary from CHANGELOG.md 1.0.0 entry) +- Link to npm package +- Link to CDN URLs (jsdelivr, unpkg) + +**Acceptance:** GitHub release published and visible. + +--- + +### P.9 — Post-publication: README badges and monitoring + +Add npm badges to `capabilities/testdrive-jsui/README.md`: + +```markdown +[![npm version](https://badge.fury.io/js/testdrive-jsui.svg)](...) +[![npm downloads](https://img.shields.io/npm/dm/testdrive-jsui.svg)](...) +``` + +Set a reminder to check download stats after 1 week. +Demo page and GitHub Pages are optional — do only if there's a specific audience +to point at it. + +**Acceptance:** README has version and download count badges; committed. + +--- + +## Task order + +``` +P.1 (repo decision) +P.2 (Markitect integration check) ← can run in parallel with P.1 +P.3 (STANDALONE_PLAN decision) ← can run in parallel + ↓ +P.4 (pack + dry-run) ← needs P.1, P.2, P.3 all done +P.5 (release tag) ← can run with P.4 + ↓ +P.6 (publish) +P.7 (fresh install test) +P.8 (GitHub release) +P.9 (badges + monitoring) +``` + +## Out of scope + +- Adding new features before publication (ship what's there) +- Ruby or Java adapters (optional integrations, not blocking publication) +- Paid npm features (keep on free tier)