diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md new file mode 100644 index 0000000..bdc8e72 --- /dev/null +++ b/WORK-RECORDS.md @@ -0,0 +1,22 @@ +# Work Records — evidence-binder + +> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record +> stage 3). Do not edit by hand — edit the source file/block listed for +> each record and re-run fix-consistency to refresh this index. Archived +> workplans are omitted; closed decisions/intakes/engagements stay listed +> so recently-resolved work is still visible. [auto] + +| Kind | ID | Status | Lane | Source | +| --- | --- | --- | --- | --- | +| workplan | EBIND-WP-0001 | finished | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| workplan | EBIND-WP-0002 | active | — | workplans/EBIND-WP-0002-capability-index-repair.md | +| task | EBIND-WP-0001-T01 | done | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| task | EBIND-WP-0001-T02 | done | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| task | EBIND-WP-0001-T03 | done | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| task | EBIND-WP-0001-T04 | done | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| task | EBIND-WP-0001-T05 | done | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| task | EBIND-WP-0001-T06 | done | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| task | EBIND-WP-0001-T07 | done | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| task | EBIND-WP-0001-T08 | done | — | workplans/EBIND-WP-0001-intent-placeholder.md | +| task | EBIND-WP-0002-T01 | done | — | workplans/EBIND-WP-0002-capability-index-repair.md | +| task | EBIND-WP-0002-T02 | wait | — | workplans/EBIND-WP-0002-capability-index-repair.md | diff --git a/registry/capabilities/capability.evidence.binding.md b/registry/capabilities/capability.evidence.binding.md new file mode 100644 index 0000000..7550afd --- /dev/null +++ b/registry/capabilities/capability.evidence.binding.md @@ -0,0 +1,184 @@ +--- +id: capability.evidence.binding +name: Evidence-to-Target Binding +summary: >- + Links evidence items to structured targets with relation, status, and + confidence metadata, bidirectional queries, active-state coordination, and + canonical engine events. +owner: evidence-binder +status: draft +domain: infotech +tags: + - evidence + - binding + - evidence-link + - form-field + - citation-evidence + +maturity: + discovery: + current: D3 + target: D5 + confidence: high + rationale: >- + INTENT.md, SCOPE.md, the extraction inventory, shared contracts, and the + reference-UI ADR define the boundary, neighboring systems, contract + deltas, and obvious risks. The capability has not yet been grounded in a + systematic cross-domain use-case catalogue. + availability: + current: A2 + target: A2 + confidence: high + rationale: >- + The private TypeScript package exports its binding service, in-memory + repository, active-state flow, and React provider and is source-linked by + the citation-evidence umbrella. A source library is its natural delivery + level; no CLI or service surface is intended. + +external_evidence: + completeness: + level: C3 + confidence: medium + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - create, update, remove, and query evidence links in both directions + - coordinate active target, evidence item, and annotation state + - emit the canonical engine event vocabulary + - support the umbrella form-field binding path end to end + broken_expectations: + - non-form target kinds are defined by contract but not exercised by the current umbrella consumer + - target adapters and evidence-sufficiency helpers remain narrower than the aspirational INTENT + out_of_scope_expectations: + - durable persistence implementation + - source ingestion, selector resolution, and host-application composition + reliability: + level: R3 + confidence: medium + basis: consumer_quality_signals + evidence: + tests: + suites: + - src/services/bindings.test.ts + - src/state/active.test.ts + - src/FormRenderer.dom.test.tsx + integration: + consumer: citation-evidence + mode: source-linked internal package + known_reliability_risks: + - reliability evidence comes from one internal consumer rather than diverse independent consumers + - the bundled repository is in-memory and host persistence glue must restore links correctly + +discovery: + intent: >- + Turn collected evidence into inspectable relationships with structured + targets while keeping the binding layer target-neutral and independent of + ingestion, anchoring, and workspace composition. + includes: + - evidence-link lifecycle operations and bidirectional queries + - active target, evidence-item, and annotation coordination + - canonical event-bus emission + - a target-neutral reference form renderer + excludes: + - document ingestion and selector resolution + - evidence-source capture workflows + - review-workspace and umbrella application composition + - durable persistence implementation details + assumptions: + - citation-engine remains authoritative for shared types and event vocabulary + - host applications provide persistence and compose source and work surfaces + use_cases: + - attach source evidence to a structured form field + - list all evidence for a target and all targets for an evidence item + - activate a target and its supporting evidence for coordinated navigation + research_memos: [] + +availability: + current_level: A2 + target_level: A2 + current_artifacts: + - src/services/bindings.ts + - src/repos/in-memory-links.ts + - src/state/active.ts + - src/BinderProvider.tsx + - src/FormRenderer.tsx + target_artifacts: [] + consumption_modes: + - source module + - React provider + +relations: + depends_on: [] + supports: [] + related_to: [] + +evidence: + documentation: + - README.md + - SCOPE.md + - INTENT.md + - docs/extraction-inventory.md + - docs/adr/ADR-0001-reference-ui-surface.md + tests: + - src/services/bindings.test.ts + - src/state/active.test.ts + - src/FormRenderer.dom.test.tsx + consumer_feedback: + - citation-evidence consumes the package through its sibling-checkout alias + bug_reports: [] + incidents: [] + +consumer_guidance: + recommended_for: + - internal TypeScript and React workflows that bind evidence to structured targets + - form-oriented consumers using citation-engine contracts + not_recommended_for: + - consumers needing a published package, remote API, or built-in durable storage + - applications that need document ingestion or selector resolution + known_limitations: + - only the form-field target path is exercised by the current umbrella consumer + - package distribution is a private sibling-checkout link + +promotion_history: [] +--- + +# Evidence-to-Target Binding + +## Overview + +This capability owns the relationship and interaction layer between evidence +items and structured targets. It provides evidence-link lifecycle operations, +queries in both directions, active-state coordination, canonical engine-event +emission, and the reference form integration used by the umbrella workspace. + +## Assessment notes + +### Discovery + +The package boundary and contract deltas are documented and implemented, which +supports D3. Promotion to D5 needs an explicit catalogue of actors, target-type +variants, and prioritization beyond the current form-field workflow. + +### Availability + +The capability is directly consumable as source code through the private +TypeScript package and React exports. A2 is both current and the natural target. + +### Completeness + +The main form-field evidence-binding flow works end to end. Broader target +adapters and evidence-sufficiency behavior described in INTENT remain future +scope, so the assessment stays at C3. + +### Reliability + +Unit and DOM tests cover the service, state flow, and reference renderer, and +the umbrella application consumes the package. That supports R3 for normal +internal use, with medium confidence until more consumers provide evidence. + +## Promotion checklist + +- [x] ID follows the capability identifier pattern +- [x] Maturity enums match the capability maturity standard +- [x] External evidence is separate from internal maturity +- [x] Relations reference no unresolved capability IDs +- [x] Index entry points to this file diff --git a/registry/capabilities/capability.evidence.rect-registry.md b/registry/capabilities/capability.evidence.rect-registry.md new file mode 100644 index 0000000..fcc6528 --- /dev/null +++ b/registry/capabilities/capability.evidence.rect-registry.md @@ -0,0 +1,184 @@ +--- +id: capability.evidence.rect-registry +name: Visual-Guide Rect Registry +summary: >- + Coordinates field, evidence-card, and highlight rectangles from independent + renderers so an SVG overlay can draw the active visual guide without polling. +owner: evidence-binder +status: draft +domain: infotech +tags: + - rect-registry + - visual-guide + - overlay + - active-state + - citation-evidence + +maturity: + discovery: + current: D3 + target: D5 + confidence: high + rationale: >- + SharedContracts section 7, SCOPE.md, the extraction inventory, and the + reference-UI ADR define the cross-renderer contract, ownership boundary, + invalidation model, and coupling risk. Systematic use-case and alternative + research beyond the citation workspace has not been recorded. + availability: + current: A2 + target: A2 + confidence: high + rationale: >- + The TypeScript package exports the rect registry, event pump, React hooks, + and SVG overlay as source modules consumed by the citation-evidence + umbrella. The capability is naturally a library rather than a CLI or + service. + +external_evidence: + completeness: + level: C3 + confidence: medium + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - register and resolve field, evidence-card, and highlight rectangles + - notify consumers on registration, removal, and explicit invalidation + - throttle viewport change pumps with requestAnimationFrame + - draw the active field-to-card-to-highlight guide through the SVG overlay + broken_expectations: + - broader renderer and layout variants have not been exercised outside the umbrella workspace + out_of_scope_expectations: + - document highlight resolution + - evidence-card and viewer rendering ownership + - polling-based geometry ownership inside the overlay + reliability: + level: R3 + confidence: medium + basis: consumer_quality_signals + evidence: + tests: + suites: + - src/visual-guide/rect-registry.test.ts + - src/visual-guide/react-hooks.dom.test.tsx + - src/visual-guide/Overlay.dom.test.tsx + integration: + consumer: citation-evidence + mode: form, evidence-card, and highlight bridges + known_reliability_risks: + - reliability evidence comes from one browser application and its automated DOM tests + - unusual transforms and multi-window layouts are not represented in current evidence + +discovery: + intent: >- + Decouple independently rendered fields, evidence cards, and document + highlights by giving them one invalidation-aware geometry registry for the + active visual guide. + includes: + - rectangle registration and lookup for the three canonical rect kinds + - change subscriptions and explicit invalidation + - viewport event pumps and React registration hooks + - SVG overlay rendering for the active triple + excludes: + - source selector resolution and scrolling + - ownership of evidence-card or viewer components + - application-level active-state persistence + assumptions: + - each renderer can supply a current DOMRect through a callback + - the host mounts one registry shared by participating renderers + - the host drives active target, evidence, and annotation state + use_cases: + - connect an active form field to its evidence card and source highlight + - redraw guide geometry after scroll, resize, focus, or explicit invalidation + - let renderer bridges publish geometry without importing each other + research_memos: [] + +availability: + current_level: A2 + target_level: A2 + current_artifacts: + - src/visual-guide/rect-registry.ts + - src/visual-guide/events.ts + - src/visual-guide/react-hooks.ts + - src/visual-guide/Overlay.tsx + target_artifacts: [] + consumption_modes: + - source module + - React hook + - React component + +relations: + depends_on: [] + supports: [] + related_to: + - capability.evidence.binding + +evidence: + documentation: + - README.md + - SCOPE.md + - docs/extraction-inventory.md + - docs/adr/ADR-0001-reference-ui-surface.md + - ../citation-evidence/wiki/SharedContracts.md + tests: + - src/visual-guide/rect-registry.test.ts + - src/visual-guide/react-hooks.dom.test.tsx + - src/visual-guide/Overlay.dom.test.tsx + consumer_feedback: + - citation-evidence composes field, evidence-card, and highlight bridges through this registry + bug_reports: [] + incidents: [] + +consumer_guidance: + recommended_for: + - React applications drawing active relationships across independently rendered panes + - citation-evidence consumers using the canonical field, evidence-card, and highlight rect kinds + not_recommended_for: + - non-DOM renderers without a DOMRect-compatible adapter + - applications expecting the registry to resolve selectors or own scrolling + known_limitations: + - evidence is limited to one internal browser application + - transformed and multi-window layout behavior is not explicitly tested + +promotion_history: [] +--- + +# Visual-Guide Rect Registry + +## Overview + +This capability provides the shared geometry contract for the visual guide. +Independent field, evidence-card, and highlight renderers publish callbacks into +one registry; hooks and event pumps invalidate it, and the overlay draws the +active relationship without owning those renderers or polling their geometry. + +## Assessment notes + +### Discovery + +The contract and the coupling problem it solves are explicit and implemented, +supporting D3. Promotion to D5 requires a broader, prioritized use-case and +layout-variant catalogue. + +### Availability + +The registry, hooks, and overlay are directly consumable TypeScript and React +source modules. A2 is the natural target for this embedded UI capability. + +### Completeness + +The canonical three-leg visual-guide path works and has focused coverage. The +assessment remains C3 because only the umbrella layout and browser context have +supplied consumer evidence. + +### Reliability + +Registry, event-pump, hook, and overlay tests plus the umbrella integration +support R3 for normal internal use. Confidence remains medium until independent +consumers or broader layout evidence exist. + +## Promotion checklist + +- [x] ID follows the capability identifier pattern +- [x] Maturity enums match the capability maturity standard +- [x] External evidence is separate from internal maturity +- [x] Relations reference an indexed capability ID +- [x] Index entry points to this file diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml index e5340f7..5d09471 100644 --- a/registry/indexes/capabilities.yaml +++ b/registry/indexes/capabilities.yaml @@ -1,18 +1,30 @@ version: 1 -updated: '2026-07-08' +updated: '2026-08-21' domain: helix_forge capabilities: - - type: library - title: Evidence-to-target binding - description: >- - Links evidence items to structured targets (form fields, claims, - requirements) with relation/status/confidence and two query directions, - emitting canonical engine bus events. - keywords: [evidence, binding, evidence-link, form-field, citation-evidence] - - type: library - title: Visual-guide rect registry - description: >- - The SharedContracts §7 rect-registry contract — independent renderers - publish field/evidence-card/highlight rects into one registry; an SVG - overlay draws the active-triple guide without polling. - keywords: [rect-registry, visual-guide, overlay, active-state, citation-evidence] + - id: capability.evidence.binding + name: Evidence-to-Target Binding + summary: >- + Links evidence items to structured targets with relation, status, and + confidence metadata, bidirectional queries, active-state coordination, + and canonical engine events. + vector: D3 / A2 / C3 / R3 + domain: infotech + status: draft + owner: evidence-binder + path: registry/capabilities/capability.evidence.binding.md + tags: [evidence, binding, evidence-link, form-field, citation-evidence] + consumption_modes: [source module, React provider] + - id: capability.evidence.rect-registry + name: Visual-Guide Rect Registry + summary: >- + Coordinates field, evidence-card, and highlight rectangles from + independent renderers so an SVG overlay can draw the active visual guide + without polling. + vector: D3 / A2 / C3 / R3 + domain: infotech + status: draft + owner: evidence-binder + path: registry/capabilities/capability.evidence.rect-registry.md + tags: [rect-registry, visual-guide, overlay, active-state, citation-evidence] + consumption_modes: [source module, React component] diff --git a/src/FormRenderer.tsx b/src/FormRenderer.tsx index 0460907..6697d5c 100644 --- a/src/FormRenderer.tsx +++ b/src/FormRenderer.tsx @@ -24,7 +24,6 @@ import { serializeSomeOfValue, typeNeedsOptions, type AttributeOption, - type AttributeValueType, type FormFieldSchema, type FormSchema, } from "./attribute-types"; diff --git a/workplans/EBIND-WP-0001-intent-placeholder.md b/workplans/EBIND-WP-0001-intent-placeholder.md index cb371eb..98dd5cc 100644 --- a/workplans/EBIND-WP-0001-intent-placeholder.md +++ b/workplans/EBIND-WP-0001-intent-placeholder.md @@ -4,7 +4,7 @@ type: workplan title: "Extract evidence-binder from citation-evidence" domain: infotech repo: evidence-binder -status: done +status: finished owner: codex topic_slug: citation_evidence_mvp created: "2026-06-21" diff --git a/workplans/EBIND-WP-0002-capability-index-repair.md b/workplans/EBIND-WP-0002-capability-index-repair.md new file mode 100644 index 0000000..f19f3cb --- /dev/null +++ b/workplans/EBIND-WP-0002-capability-index-repair.md @@ -0,0 +1,69 @@ +--- +id: EBIND-WP-0002 +type: workplan +title: "Repair capability registry federation metadata" +domain: infotech +repo: evidence-binder +status: active +owner: codex +topic_slug: capability_registry_federation +created: "2026-08-21" +updated: "2026-08-21" +--- + +# EBIND-WP-0002 — Repair capability registry federation metadata + +Restore `evidence-binder` to the reuse-surface federation after its capability +index was found to contain `SCOPE.md` advertisement blocks instead of validated +registry rows. Preserve the valid SCOPE advertisements, add resolvable registry +entries, and assess maturity from current repository evidence. + +## Repair and document the capability entries + +```task +id: EBIND-WP-0002-T01 +status: done +priority: high +``` + +Translate both index rows to the federation contract and add their backing +Markdown entries. Use repository evidence, current consumer integration, and +the reuse-surface maturity standard to choose defensible D/A/C/R vectors. + +Acceptance: + +- both rows expose all required federation fields and stable capability IDs +- both `path` values resolve to schema-valid Markdown entries +- maturity rationale distinguishes source availability from completeness and + reliability evidence + +## Validate, synchronize, and request federation re-enable + +```task +id: EBIND-WP-0002-T02 +status: wait +priority: high +blocking_reason: validated repair must be published to Forgejo and indexed by the production registrar +``` + +Run the reuse-surface validator and the repository quality checks, synchronize +the workplan with State Hub, and send non-secret completion evidence to the +reuse-surface owner so its federation source can be re-enabled. + +Acceptance: + +- registry validation passes without index-drift warnings +- tests, typecheck, lint, and repository diff checks pass +- State Hub records the completed work and reuse-surface receives the repair + summary and maturity vectors + +Local implementation completed 2026-08-21. The checked-out reuse-surface +validator accepted both entries with warnings treated as failures. Repository +verification passed 43 tests plus typecheck, lint, and `git diff --check`. The +quality pass also found and removed a stale `AttributeValueType` import that had +been failing both typecheck and lint. + +Closeout is waiting on two external-state changes: publication of the validated +working-tree repair to Forgejo, after which reuse-surface can re-enable the +member source, and production-registrar assignment of State Hub identifiers for +this new workplan and its tasks.