Skip to content

Reconcile FEATURES.md and PROJECT-MAP.md with the current generator - #91

Merged
Jason-Vaughan merged 1 commit into
mainfrom
docs/reconcile-generated-maps
Aug 1, 2026
Merged

Reconcile FEATURES.md and PROJECT-MAP.md with the current generator#91
Jason-Vaughan merged 1 commit into
mainfrom
docs/reconcile-generated-maps

Conversation

@Jason-Vaughan

Copy link
Copy Markdown
Owner

What

  • FEATURES.md: restore the current scaffold — stable file.js#symbolName anchor format, section named Governance / Engines.
  • PROJECT-MAP.md: add the missing Tangle-Shared doc group.
  • Resolve the three auto-stubbed TBD entries and fill every <!-- describe --> placeholder in both files.
  • CHANGELOG under ### Internal.

Why

Both files were committed in the 2026-07-06 wrap (#84) from a superseded TangleClaw scaffold, while newer regenerated copies sat untracked in the working tree — they collided on the next git pull.

Rather than guess which side won, I checked the generator: TangleClaw/lib/projects.js (FEATURE_INDEX_TEMPLATE) emits exactly the untracked copies. The committed ones are stale in two specific ways:

  • FEATURES.md documented the file.js:line pointer format, which the generator has since abandoned in favor of stable file.js#symbolName anchors — the template's own reasoning is that line pointers rot because nothing re-verifies them. A map instructing future sessions to write rotting pointers is worse than no map.
  • PROJECT-MAP.md predated the Tangle-Shared group (created 2026-07-29, 5 members — confirmed live against the TangleClaw groups API, not inferred from the file).

Notes on judgment calls

  • The ARCHITECTURE.md stub gets no feature entry. It is a design document, not a feature; it was stubbed only because a PR touched the file. Inventing a feature to clear a checkbox would put a wrong entry in the index permanently.
  • FEATURES.md is still sparseServer / API and Governance / Engines are empty. That is the pre-existing state, not something this PR removed; the serve endpoint and delegate MCP server have no entries yet. Filling the index properly is separate work and I did not smuggle it in here.
  • The generator seeds these files but never overwrites them, so this drift would not have self-corrected.

Test plan

  • Both files diffed against FEATURE_INDEX_TEMPLATE in TangleClaw/lib/projects.js — headers and section names now match.
  • Tangle-Shared verified as a real, live group via the TangleClaw API before adding it.
  • No <!-- describe --> or TBD markers remain in either file.
  • Suite green: 495 tests, 17 skipped (docs-only change; run as a regression check).

Both files were committed in the 2026-07-06 wrap (#84) from a superseded
TangleClaw scaffold, while newer regenerated copies sat untracked in the working
tree. Verified which was current against the generator itself
(TangleClaw/lib/projects.js): the untracked copies match it, the committed ones
do not.

FEATURES.md documented the abandoned `file.js:line` pointer format — the
generator now mandates stable `file.js#symbolName` anchors, precisely because
line pointers rot with nothing re-verifying them — and named its third section
"Methodologies / Engines" instead of "Governance / Engines".

PROJECT-MAP.md predated the Tangle-Shared doc group (created 2026-07-29,
confirmed live via the TangleClaw groups API), so it listed only AI Inference.

Also resolves what the reconciliation would otherwise have dropped or carried
forward unread: the three auto-stubbed TBD entries and every `<!-- describe -->`
placeholder are filled in. The ARCHITECTURE.md stub gets no feature entry — it
is a design document, not a feature, and was stubbed only because a PR touched
it.

FEATURES.md is still sparse: Server / API and Governance / Engines are empty.
Nothing was removed to make them so.
@cursor

cursor Bot commented Aug 1, 2026

Copy link
Copy Markdown

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

@Jason-Vaughan
Jason-Vaughan enabled auto-merge (squash) August 1, 2026 19:15
@Jason-Vaughan
Jason-Vaughan merged commit 9cdd57e into main Aug 1, 2026
3 checks passed
@Jason-Vaughan
Jason-Vaughan deleted the docs/reconcile-generated-maps branch August 1, 2026 19:15
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