docs(roadmap): add workplans for infospace S3 close-out and JSUI publication
infospace-s3-closeout: 8 tasks (C.1-C.8) covering 3 missing evals, viability sign-off, docs (advanced usage, composition, perf), deferred git history cleanup, and formal roadmap closure. testdrive-jsui-publication: 9 tasks (P.1-P.9) covering repo structure decision, Markitect integration gate, pack/dry-run, npm publish, CDN verify, fresh install test, GitHub release, and badges. Both registered as workstreams in Custodian State Hub. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
172
roadmap/infospace-s3-closeout/PLAN.md
Normal file
172
roadmap/infospace-s3-closeout/PLAN.md
Normal file
@@ -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 <slug> --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
|
||||
176
roadmap/testdrive-jsui-publication/PLAN.md
Normal file
176
roadmap/testdrive-jsui-publication/PLAN.md
Normal file
@@ -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
|
||||
[](...)
|
||||
[](...)
|
||||
```
|
||||
|
||||
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)
|
||||
Reference in New Issue
Block a user