Replace hard-coded heuristic seeds and route special-casing with metadata

[devin-ai-integration]

Objective

Replace hard-coded node IDs and question-pattern matching in query-engine.ts with metadata-driven configuration. The query engine should be spec-content-agnostic so that ID changes in FPF-spec.md no longer require code changes.

Problem areas:

1. addHeuristicSeeds() (line ~600) and heuristicInitialNodeIds() (line ~646) contain hard-coded node IDs ('C.17', 'C.18', 'A.1.1', etc.) tied to specific question phrasings
2. buildRouteAnswer() (line ~1247) has a hard-coded check for route.name === 'project alignment' with route-specific constraints

Proposed fix for seeds: Drive seed rules from spec metadata — add seed_hints to PatternRecord, tag patterns with semantic categories, or move heuristic seed rules into a declarative config file.

Proposed fix for route special-casing: Add an optional constraints field to RouteRecord, parse route-level constraints during compilation, use route.constraints generically.

"Done" looks like: No hard-coded FPF node IDs or route names remain in query-engine.ts; all such knowledge lives in compiled metadata.

Kind

refactor

Affected area

src/runtime/ (compiler & query engine)

Acceptance criteria

• No hard-coded FPF node IDs in query-engine.ts heuristic methods
• No route-name string checks in buildRouteAnswer()
• Seed rules driven from compiled metadata or declarative config
• Route constraints stored in RouteRecord metadata
• All existing tests pass

Agent-delegable?

partially — needs human review

Additional context

• src/runtime/query-engine.ts lines ~600–646 (heuristic seeds), line ~1247 (route special-case)
• src/runtime/types.ts: PatternRecord.queries (already exists but underused), RouteRecord (no constraints field yet)

FPF grounding:

• A.7 (Strict Distinction / Clarity Lattice, Stable): Hard-coded node IDs in the query engine conflate design-time knowledge (which IDs exist in the spec) with run-time behavior (how queries are routed). Per A.7:5.3, a MethodDescription (the compiled index describing the spec) must not be confused with the Method (the retrieval algorithm) or the Work (a specific query execution).
• A.15 (Role–Method–Work Alignment, Stable): The query engine's Method should be spec-content-agnostic. Content knowledge belongs in compiled metadata (a MethodDescription), not baked into the engine code. Hard-coding IDs is the "recipe-as-evidence" anti-pattern (A.15:8).
• A.1.1 (U.BoundedContext, Stable): Hard-coded IDs break the semantic boundary between the query engine (a system) and the spec content (an episteme). The engine should not "know" specific FPF IDs — that knowledge should be mediated through the compiled index, respecting bounded context separation.

Measurable impact

Metric	Before	After (target)	How to measure
Hard-coded node IDs in query-engine.ts heuristic methods	6 lines	0	grep -Ec "'C\.[0-9]|'A\.[0-9]|'B\.[0-9]|'F\.[0-9]" src/runtime/query-engine.ts
Hard-coded route name checks in query-engine.ts	1 ('project alignment')	0	grep -c "'project alignment'" src/runtime/query-engine.ts
Seed rules in compiled metadata or config	0	≥1 (declarative config or PatternRecord.seed_hints)	grep -Ec 'seed_hints|seedRules' src/runtime/types.ts src/runtime/*.ts
Route constraints in RouteRecord metadata	0	≥1 (constraints field)	grep -c 'constraints' src/runtime/types.ts
Existing test pass rate	all pass	all pass (no regressions)	bun run test

[venikman]

Take on the premise

Agree with the problem. The proposed fix as written only half-solves it.

The A.7 / A.15 grounding is right: hard-coded node IDs in query-engine.ts conflate the Method (retrieval algorithm) with the MethodDescription (which IDs exist in the spec). When FPF-spec.md renames C.17, the query engine silently breaks without any spec-to-code link making that visible. That's a real bounded-context violation.

But the proposed solution is thin.

Issue proposal: "move heuristic rules to declarative config or PatternRecord.seed_hints".

If the rules still live as TypeScript code in the repo (see PR #28: buildHeuristicSeedRules() hardcodes the same IDs it was supposed to remove from query-engine.ts), the A.15 violation is just moved from one file to another. The Method is still baked with spec content.

What would actually solve this (per the grounding):

• Seed hints live in FPF-spec.md itself — e.g., pattern front-matter: seed_hints: creativity, open-ended, search — so the compiler extracts them as metadata
• buildHeuristicSeedRules() becomes a pure derivation from compiled pattern metadata, with zero literal IDs
• When a pattern is renamed in the spec, the seed rule travels with it automatically

The grep-count metric ("hardcoded node IDs in query-engine.ts = 0") is satisfiable without satisfying the goal — #28 will hit 0 in query-engine.ts while preserving all the hardcoded IDs in compiler.ts. The metric doesn't measure the thing the grounding cares about.

Sharpen the acceptance criteria:

• No hardcoded FPF node IDs anywhere in src/ outside of tests and docs (stronger grep)
• Seed rule inputs come from spec annotations / pattern metadata
• Renaming a pattern ID in FPF-spec.md does not require any TS edit to preserve behavior

Problem is genuine; issue should be reframed before the PR that claims to solve it is merged. Also — PR #28 looks like it drops the project-alignment route constraints (F.11, F.9, F.17) in the process. Verify before merge.

[devin-ai-integration]

Merger plan update

Status: PR #28 — needs investigation before merge

Incorporating venikman's feedback from this issue:

1. "Fix only half-solves it — hardcoded IDs moved from query-engine.ts to compiler.ts" — Valid concern. PR refactor: extract inline heuristic seeds and route constraints to snapshot-attached rules #28 extracts seed rules to a dedicated function but the IDs remain hardcoded in TypeScript. The full solution (spec-derived seed hints via pattern front-matter) is a larger effort. Plan: verify this is an incremental improvement, keep the issue open for the full solution.

2. "PR refactor: extract inline heuristic seeds and route constraints to snapshot-attached rules #28 may drop project-alignment route constraints (F.11, F.9, F.17)" — This is the critical concern. I will investigate whether the route constraints are preserved or lost in PR refactor: extract inline heuristic seeds and route constraints to snapshot-attached rules #28 before proceeding with merge.

3. "No hardcoded FPF node IDs anywhere in src/ outside tests" — The sharper acceptance criteria is noted. PR refactor: extract inline heuristic seeds and route constraints to snapshot-attached rules #28 doesn't fully satisfy this, but it's a step in the right direction.

4. Coordinated batch: Per venikman's comment on issue Split query-engine.ts into retrieval stages #2, PRs refactor: extract inline heuristic seeds and route constraints to snapshot-attached rules #28 + refactor: split query-engine.ts into retrieval stages #31 + test: add stage-local contract tests for compiler and query pipelines #32 should land together so boundary redefinition, data, and tests are coherent.

Merge order: PR #28 merges as part of the #28/#31/#32 batch, after route constraint investigation.