A-IForgeEngineDocsShapesScoped Shape Config (Draft)

Scoped Shape Config (Draft)

Scoped Shape Config (Draft)

tu30

APPLIED 2026-07-21

shapeTypeTargetField set to shape in .obsidian/plugins/forge/data.json; both shape notes updated to match field: shape. Requires an Obsidian reload to take effect. Shape Repair remains OFF. Next in-Obsidian steps: Forge: Refine Shape Templates → Forge: Run Vault Lint (expect 0 findings until notes opt in with shape:).

Table of Contents

  1. #1. Problem
  2. #2. Design — opt-in match field
  3. #3. Config changes (Forge data.json)
  4. #4. Shape-note prose updates
  5. #5. Adoption workflow
  6. #6. Verification & expected result
  7. #7. Rollback
  8. #8. Provenance

1. Problem

The current "clean" shape lint is a false positive

Forge's newest run (2026-07-21 20:10) reports 0 errors / 0 warnings across 1,681 notes — but only because A-I/Forge/Templates/ is empty (the Refine Shape Templates step was never run), so lint has nothing to enforce.

Independent replication of the shape_heading_missing rule against the live vault, matching on the broad type field (current shapeTypeTargetField), shows the opposite:

ShapeMatch (type:)Notes matchedFail (≥1 required heading missing)
Project Shapeproject3635
Reference Shapereference474474
510509

Root cause: type: project and type: reference are broad classification values applied to people notes, transcripts, READMEs, plans, obituaries — none authored to the shapes' heading trees. Matching shapes to classification over-fires. The fix is to match shapes to explicit opt-in, not to type.

1A. Value derivation & shape-note gate (confirmed from main.js)

Two hard rules read straight from the engine source

  1. A shape note MUST carry frontmatter type: shape (or no type at all). Refine skips any shape whose type is something else: if (noteTypeText && noteTypeText.toLowerCase() !== "shape") return skipped(...). Shapes filed as type: reference never generate a template — the silent-lint trap.
  2. The match value is the shape's filename, lowercased — spaces, not hyphens, and no Shape suffix. The engine splits the basename on [-_ ], Title-cases, and the lint key is templateFileToShapeName(...).toLowerCase(). So Slot Doc.md → a note needs shape: slot doc (NOT slot-doc); Decision.md → shape: decision. There is no hyphen-slug.

All 12 shapes were normalised to this: type: shape, filenames without the Shape suffix, match values = filename lowercased (Slot Doc → slot doc, Reference Note → reference note, etc.).

2. Design — opt-in match field

Decouple shape-matching from classification

Change the global match field from type to a dedicated frontmatter field shape. A note is shape-linted only when it explicitly declares an opt-in value like shape: slot doc (or shape: decision, shape: meeting, …). Classification (type:, node_type:) is untouched.

Legacy shapes retired 2026-07-21

The original generic Project and Reference shapes were retired — Slot Doc and Reference Note are their grounded replacements (they match what real slot docs / (Reference) notes actually contain). The generic structures survive read-only as Engine/Examples/shapes/.

  • Target value is the shape filename, lowercased (Slot Doc → slot doc, Decision → decision) — see §1A.
  • Match field becomes shape (global shapeTypeTargetField).
  • Zero existing notes carry a shape: field → lint is clean on day one; every future match is a deliberate opt-in.
  • Adoption is incremental and reversible — add shape: to a note only once it actually follows the structure.

Opt-in note frontmatter:

---
type: project        # classification — unchanged, owns node_type/type rules
shape: slot doc      # opt-in — THIS is what shape lint matches on (Slot Doc shape)
---

3. Config changes (Forge data.json)

Path: .obsidian/plugins/forge/data.json (requires an Obsidian reload to take effect).

KeyCurrentProposedWhy
shapeTypeTargetFieldtypeshapeMatch on opt-in field, not broad classification
shapeRepairEnabledfalsefalse (keep off)Never auto-mutate during rollout
shapeLintStrictModefalsefalse (keep)Order/extra stay soft while adopting
shapeLintFolders[][] (optional)Opt-in field already scopes; add folders only if a second narrowing is wanted
Only one field actually changes: shapeTypeTargetField: "type" → "shape"

Everything else stays as-is. Repair remains OFF — validation only.

4. Shape-note prose updates

Update the match-field line in both live shapes so the docs match the config:

  • A-I/Forge/Shapes/Project Shape.md A note with type: project matches this shape (match field: type). → A note with shape: project matches this shape (match field: shape).
  • A-I/Forge/Shapes/Reference Shape.md A note with type: reference matches this shape (match field: type). → A note with shape: reference matches this shape (match field: shape).
Superseded — these two shapes were retired 2026-07-21

Project Shape.md / Reference Shape.md were renamed to Project.md / Reference.md (the Shape suffix leaks into the match value, §1A), then retired in favor of the grounded Slot Doc and Reference Note shapes. The live shape set is now 10.

5. Adoption workflow

Incremental, dry-run-gated

  1. Flip shapeTypeTargetField → shape in data.json; reload Obsidian.
  2. Run Forge: Refine Shape Templates (generates templates into A-I/Forge/Templates/).
  3. Run Forge: Run Vault Lint → expect 0 findings (no note carries shape: yet).
  4. Pick one genuine pilot note per shape, author it to the heading tree, add its opt-in value (e.g. shape: slot doc, shape: decision).
  5. Re-lint → confirm the pilot passes; only then opt in more notes.
  6. Keep Shape Repair OFF until a dry run on a real opt-in set looks right.

6. Verification & expected result

ScenarioMatched notesShape-lint failures
Before (broad type)510509
After (opt-in shape)00

Simulated 2026-07-21: grep '^shape:' across the live vault (excl. .git/.trash/.claude/worktrees/A-I/Forge) returns 0 notes — the scoped config lints clean immediately, with no vacuous-template caveat.

7. Rollback

One-line revert

Set shapeTypeTargetField back to type in data.json and reload. No note content changes are required to roll back (opt-in shape: fields are inert under any other match field). Delete generated A-I/Forge/Templates/ if reverting fully.

8. Provenance

This draft was created 2026-07-21 in TAC-GKOS by Claude (Claude Opus 4.8) as the "option 1 — scoped shape config" follow-up to the Forge relocation commit (76e0fec) and the shape-lint verification that found the vault would fail 509/510 notes under the broad type match. It proposes a single Forge data.json change (shapeTypeTargetField: type → shape) plus matching shape-note prose edits, so shape lint becomes an explicit opt-in system rather than firing on the vault-wide classification field. Applied 2026-07-21 (shapeTypeTargetField → shape), then followed by the shape-note correction (type: shape, Shape-suffix rename) and the retirement of the two legacy generic shapes (Project, Reference) in favor of the grounded Slot Doc and Reference Note. The live shape set is now 10.

Part of the k-a system · TOE.KNEE.SEE

Built with LogoFlowershow