@flood-md/agent 0.2.9 → 0.2.10

package/references/record-decisions.md

@@ -0,0 +1,25 @@
+# Record metadata decisions
+
+Use with the records workflow. These cases demonstrate different outcomes for
+similar fields; they are not templates or a forbidden-word list.
+
+| Situation | Decision | Reason |
+| --- | --- | --- |
+| Browsing suggestions; title/summary identify the item, status guides opening | Keep identity/summary together; a stable trailing state is useful; consider category/date near the copy | Four unrelated trailing values should not dictate the summary width |
+| A support queue is triaged by state, priority, assignee and due time | Keep those attributes in named comparison columns | Moving priority into details would obstruct the actual task |
+| A suggestion's category is Error but its state is In progress | Use category treatment and lifecycle StatusIndicator; name category in ambiguous details | Classification is not a failed save or error announcement |
+| A low-priority item and high-priority item have the same state | Preserve priority if comparing urgency matters; accent only the meaningful distinction | Urgency and lifecycle are separate dimensions, not competing dots |
+| A file list must compare format, size and transfer progress | Reuse FileMeta, StatusIndicator and Progress within the file owners | Generic text or a row of handmade chips would duplicate existing primitives |
+| An invoice register is used to compare due amounts and payment states | Use named columns, retain units and relevant dates | These fields are core comparisons rather than optional decoration |
+| Created and updated render the same day in a casual browsing detail | Consider one date if the second event adds no decision value | A short screen need not repeat equivalent visible information |
+| An audit detail needs exact creation and modification times on the same day | Keep both named events with sufficient precision/timezone context | Equal formatted dates do not establish identical events |
+| A first-use collection has an empty-state title and a visible create action | Omit a redundant zero counter unless another task needs it | Repeating emptiness does not help the next action |
+| Filters reduce an existing collection to zero | Show the no-results state and a relevant reset; preserve needed result announcements | This is a recoverable query state, not first-use onboarding |
+| Several short records align in an example but long statuses shift other values | Establish shared columns or change the record composition | Equal Inline gaps do not create common scan positions |
+| An inspector flags a priority/date as unowned supporting copy | Evaluate its selection, triage or history purpose | Neither automatic removal nor semantic wrappers prove useful content |
+
+A compact browsing row might place category and recency with its copy and keep
+one state at the trailing edge. A comparison table may need several such attributes
+visible together. Decide from the task before choosing presentation. Do not fix
+crowding by hiding a required field, replacing Flood components or modifying user
+record content. Record these choices in development notes, not as extra UI captions.

package/references/rendered-review.md

@@ -0,0 +1,97 @@
+# Review the rendered interface
+
+The optional `@flood-md/agent/inspect` export provides a self-contained, read-only
+DOM observer for local browser tooling. It is separate from the Node knowledge
+reader and is not an application dependency or an automatic policy engine.
+
+With Playwright running against your local host:
+
+```js
+import {inspectRenderedUI} from '@flood-md/agent/inspect';
+await page.evaluate(() => document.fonts.ready);
+const observations = await page.evaluate(inspectRenderedUI, {});
+```
+
+Before accepting owner selection, also review host-owned source with
+`inspectSourceUI` from the same entry:
+
+```js
+import {inspectSourceUI} from '@flood-md/agent/inspect';
+const jsxReview = inspectSourceUI(jsxText);
+const cssReview = inspectSourceUI(cssText, {format: 'css'});
+```
+
+The caller supplies local text; the function performs no file access, execution
+or network requests. It points at native dialog calls, selected raw JSX controls
+and custom grid/flex layout declarations for owner review. Read each source
+location: comments, strings, examples and legitimate shell CSS can match, while
+aliases, dynamic types and indirect calls can be missed. This is not an AST,
+import audit or automatic ban. Use it on host source, not the implementation of
+Flood itself. Inputs are limited to 500000 UTF-16 units and maxFindings defaults
+to 50 (maximum 500); split larger files deliberately. Retain contextual decisions
+outside the product. An empty result does not establish component reuse.
+Rem-based min-width/min-inline-size declarations are also surfaced for review:
+a local dense table can need one, while a whole-page floor can defeat enlarged
+text. Confirm the selector and actual 24px-root desktop geometry.
+
+Inspect representative pages and actual interaction states, including a populated
+editable row and an open date/selection popup. Set rootSelector only when that
+scope is intended; a popup portalled elsewhere will then be excluded. The function
+does not open controls or wait for layout on your behalf. It traverses the current
+document, not iframes or shadow roots. It performs no network requests or writes.
+Keep reports local: labels and copy inventories may contain the host's user data.
+
+Observations include likely text glyphs used as button icons, unslotted SVGs,
+passive cells offset from neighbouring input centres and complete cell blocks in
+record/action rows, supporting copy echoing a visible action label, a copy inventory
+and field/group rectangles. They are review findings with selectors/labels and
+measured offsets, not proof of a defect in every context. Arithmetic labels or
+custom artwork can be intentional; explain exceptions rather than deleting data
+to obtain an empty report. maxElements bounds each selected category (default 500,
+maximum 2000) and the total findings list; truncated means coverage is incomplete.
+
+forms.track-drift compares stacked multi-column form grids with the same outer
+frame. Different gutters or track counts need review against the grouping plan;
+some different contexts can legitimately use different tracks. Tables and nested
+ancestor/descendant grids are excluded. It is an observable geometry check, not
+an automatic judgement of semantic hierarchy.
+
+forms.content-track-drift compares actual Flood field-owner rectangles across
+stacked grids in the same form, even when nested Surface padding makes their
+outer Grid frames differ. It requires matching overall content edges and one
+consistent field width per track. Tables, ancestor/descendant grids and ambiguous
+spanning arrangements are excluded; this is selected coverage, not proof that
+all form alignment is correct. Review the reported offset in context.
+
+copy.unowned-support asks for review of supporting text outside a field, actual
+operation state, navigation or structured document. This intentionally includes
+free-standing implementation captions. Potential usefulness is not a reason to
+keep one: name the user's current decision or recovery need. Actual storage errors
+and deletion confirmations are different contexts from a static storage footer.
+Contextual exceptions are possible. Never change font size, ARIA roles or wrapper
+markup just to hide a finding; review the information itself.
+
+table.word-fragment uses Intl.Segmenter and rendered text ranges to identify
+words split across table lines. It is bounded by maxElements word segments,
+skips words longer than 200 UTF-16 units, code/pre and cells explicitly marked
+data-wrap="anywhere". If Intl.Segmenter is unavailable, that coverage is reported
+as absent. Localized line-breaking conventions can justify an exception. Preserve
+meaningful intrinsic column widths and use local scrolling before accepting
+single-letter fragments in statuses or dates.
+
+For icon actions use real artwork in IconSlot and an accessible name on the
+action. Table now centres cells by default; use cellVerticalAlign="top" only for
+a deliberate prose-table layout. Action-echo findings need contextual review:
+a necessary instruction can legitimately repeat a button label.
+
+An empty issues array does not pass the interface. Separately review necessary
+copy using the interface-content workflow and coherent grouping using the forms
+workflow. Inspect copy in screen order and field edges against common layout
+tracks. Check populated, empty, error and changed-content states in task scope.
+Record actual decisions and remaining limits; a successful screenshot capture
+does not mean its contents were reviewed successfully.
+
+layout.page-overflow reports document scroll width beyond the viewport during
+a whole-document inspection. It does not run for a selected rootSelector or
+report correctly contained local scrolling. Review the actual cause and task
+context rather than hiding overflow to silence the finding.

package/references/routing.md

@@ -6,6 +6,7 @@ override user authority or grant permission for unrelated operations.
 
 | Question / when | Audience | Prerequisite | Source of truth | Verify with |
 | --- | --- | --- | --- | --- |
+| What needs saying? New or edited interface copy and reference adaptation | Designer / developer / agent | User task, product vocabulary and actual capabilities | flood-interface-content/SKILL.md | Contextual keep/rewrite/move/remove decisions; meaningful hierarchy; preserved recovery and accessible names |
 | Which primitive owns this role? Component/composite UI work | Developer / agent / reviewer | Matching catalog and component anatomy | flood-composition/SKILL.md | Reuse existing primitives; extend small capabilities first |
 | Which API can I import? Every component edit | Developer / agent | Installed exact versions | Installed @flood-md/react declarations; flood.json | Type-check host imports; CLI doctor for alignment |
 | What does this release mean? Setup / upgrade | Developer / agent | Matching guide | flood/DESIGN.md, package changelog | Compare version and declarations; preserve host edits |

package/rules.json

@@ -39,7 +39,9 @@
         "Intrinsic actions and responsive form parent",
         "Close choice label and independent group spacing",
         "Reuse shared atoms while preserving specialized native semantics",
-        "Container/grid/media geometry at320px and enlarged RTL text",
+        "Selected role owners and their installed contracts recorded before JSX",
+        "Actual date/selection popup checked against the selected component",
+        "Container/grid/media geometry at the host's declared viewport and text targets",
         "No invisible focusable content without reveal behavior"
       ]
     },
@@ -179,7 +181,8 @@
         "Measure visible gaps and row pitch, including padding and minimum height",
         "Check wrapping and enlarged text",
         "Check fine/coarse pointers and nonoverlapping interactive targets",
-        "Preserve keyboard focus and label activation"
+        "Preserve keyboard focus and label activation",
+        "Peer form grids sharing an outer frame use coherent tracks and gutters, or have an explicit contextual reason"
       ]
     },
     {
@@ -505,6 +508,153 @@
         "Existing coverage distinguished from checks run for this revision",
         "Failures, source/host ownership and remaining limits recorded"
       ]
+    },
+    {
+      "id": "knowledge.versioned",
+      "when": "Discovering or extending Flood knowledge",
+      "for": [
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "Matching package/configuration/guide versions",
+        "Host instructions"
+      ],
+      "sourceOfTruth": "Installed catalog and selected canonical or customized material",
+      "guide": "references/knowledge.md",
+      "verify": [
+        "Read scope and version before selecting material",
+        "Finish selected instruction pages",
+        "Run growth and clean-consumer checks for source changes"
+      ]
+    },
+    {
+      "id": "content.necessary",
+      "when": "Introducing or editing visible interface copy and hierarchy",
+      "for": [
+        "designer",
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "User task and scope",
+        "Existing product vocabulary"
+      ],
+      "sourceOfTruth": "Actual user decisions and current interface context",
+      "guide": "references/flood-interface-content/SKILL.md",
+      "verify": [
+        "Changed copy has a necessary role or is removed",
+        "Titles, subtitles and hints do not repeat obvious context",
+        "Accessible names, needed constraints and recovery remain available",
+        "Each supporting sentence serves a specific decision or recovery need in the current state, not a hypothetical future risk",
+        "No standing implementation/storage caption merely because the data has a retention limitation",
+        "Prototype provenance stays in README/test handoff unless it changes a current record/choice/action; no automatic permanent environment badge"
+      ]
+    },
+    {
+      "id": "content.accurate",
+      "when": "Writing state, export, storage or completion messages",
+      "for": [
+        "designer",
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "Actual operation and completed outcome"
+      ],
+      "sourceOfTruth": "Host behavior and confirmed product facts",
+      "guide": "references/flood-interface-content/SKILL.md",
+      "verify": [
+        "No invented capabilities, expert verification or delivery claims",
+        "Error explains the applicable failure and supported recovery",
+        "Technical details appear only when they affect a user decision"
+      ]
+    },
+    {
+      "id": "content.reference",
+      "when": "Adapting content from another product or reference",
+      "for": [
+        "designer",
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "Reference purpose",
+        "Host objects, actions and states"
+      ],
+      "sourceOfTruth": "Host capability and user vocabulary",
+      "guide": "references/flood-interface-content/SKILL.md",
+      "verify": [
+        "Reference pattern is mapped to the host question it answers",
+        "Competitor workflows, promises and marketing language are not transplanted without matching behavior"
+      ]
+    },
+    {
+      "id": "layout.hierarchy",
+      "when": "Composing or reviewing task titles, group legends, named fields and shared form tracks",
+      "for": [
+        "designer",
+        "developer",
+        "agent",
+        "reviewer"
+      ],
+      "requires": [
+        "Installed component and token contracts",
+        "Task reading order and actual rendered host"
+      ],
+      "sourceOfTruth": "Installed hierarchy recipes and host content requirements",
+      "guide": "references/flood-hierarchy/SKILL.md",
+      "verify": [
+        "Task, group and field roles are distinguishable without redundant headings",
+        "Label is closer to its control than independent fields/groups",
+        "Related rows share measured control edges; width exceptions have a content reason",
+        "Dialog title/body inset is owned once; actions remain reachable at enlarged text",
+        "Calendar content remains readable inside viewport collision limits"
+      ]
+    },
+    {
+      "id": "records.scan",
+      "when": "Composing record lists, detail views or several row metadata values",
+      "for": [
+        "designer",
+        "developer",
+        "agent",
+        "reviewer"
+      ],
+      "requires": [
+        "Current recognition/comparison/action task",
+        "Installed record component contracts",
+        "Rendered sibling records with varied content"
+      ],
+      "sourceOfTruth": "Task information needs and installed record contracts",
+      "guide": "references/flood-records/SKILL.md",
+      "verify": [
+        "Field to decision and list/detail placement choices recorded outside UI",
+        "Identity and summary remain readable with long and missing metadata",
+        "Stable scan positions or real named comparison columns, not drifting pseudo-columns",
+        "List, details, first-use and filtered empty states reviewed separately"
+      ]
+    },
+    {
+      "id": "records.meaning",
+      "when": "Presenting category, lifecycle status, priority, timestamps or collection counts",
+      "for": [
+        "designer",
+        "developer",
+        "agent",
+        "reviewer"
+      ],
+      "requires": [
+        "Actual field semantics and current user decision"
+      ],
+      "sourceOfTruth": "Host data meanings and corresponding Flood primitive contract",
+      "guide": "references/flood-records/SKILL.md",
+      "verify": [
+        "Category/state/urgency distinguished with names where needed, not color alone",
+        "Essential triage/comparison fields retained; optional attributes do not compete equally",
+        "Dates identify useful events with suitable precision; formatted equality is not event equality",
+        "Counts and supporting text add current value; necessary announcements remain"
+      ]
     }
   ],
   "guideResolution": "Match guide to source in manifest.files; use its target relative to the host project root."

package/workflows.json

@@ -2,15 +2,151 @@
   "schemaVersion": 1,
   "scope": "Task routing for the existing Flood dark base; applicability is not test evidence",
   "workflows": [
-    { "id": "composition", "guide": "references/flood-composition/SKILL.md", "all": true },
-    { "id": "spacing", "guide": "references/flood-spacing/SKILL.md", "all": true },
-    { "id": "foundations", "guide": "references/flood-foundations/SKILL.md", "all": true },
-    { "id": "accessibility", "guide": "references/flood-accessibility/SKILL.md", "all": true },
-    { "id": "forms", "guide": "references/flood-forms/SKILL.md", "groups": ["forms"], "components": ["Button", "Label", "Fieldset", "ErrorSummary"] },
-    { "id": "overlays", "guide": "references/flood-overlays/SKILL.md", "groups": ["overlays"], "components": ["Select", "Combobox", "MultiSelect", "TreeSelect", "DatePicker", "DateRangePicker", "TimePicker", "DateTimePicker", "DateTimeRangePicker"] },
-    { "id": "navigation", "guide": "references/flood-navigation/SKILL.md", "groups": ["navigation"], "components": ["Tree", "TreeSelect", "Toolbar", "CommandList", "ListBox", "ToggleGroup", "SegmentedControl", "Accordion", "Collapsible"] },
-    { "id": "data-display", "guide": "references/flood-data-display/SKILL.md", "groups": ["content"], "components": ["UploadItem", "UploadList", "EmptyState", "ScrollArea"] },
-    { "id": "feedback", "guide": "references/flood-feedback/SKILL.md", "groups": ["feedback"], "components": ["Field", "Fieldset", "Input", "Textarea", "Select", "ListBox", "CopyButton", "Badge", "UploadItem", "UploadList"] },
-    { "id": "verification", "guide": "references/flood-verification/SKILL.md", "all": true }
+    {
+      "id": "composition",
+      "guide": "references/flood-composition/SKILL.md",
+      "all": true
+    },
+    {
+      "id": "interface-content",
+      "guide": "references/flood-interface-content/SKILL.md",
+      "all": true
+    },
+    {
+      "id": "hierarchy",
+      "guide": "references/flood-hierarchy/SKILL.md",
+      "groups": [
+        "forms",
+        "overlays",
+        "layout",
+        "typography"
+      ],
+      "components": [
+        "Card",
+        "Section",
+        "EmptyState"
+      ]
+    },
+    {
+      "id": "spacing",
+      "guide": "references/flood-spacing/SKILL.md",
+      "all": true
+    },
+    {
+      "id": "foundations",
+      "guide": "references/flood-foundations/SKILL.md",
+      "all": true
+    },
+    {
+      "id": "accessibility",
+      "guide": "references/flood-accessibility/SKILL.md",
+      "all": true
+    },
+    {
+      "id": "forms",
+      "guide": "references/flood-forms/SKILL.md",
+      "groups": [
+        "forms"
+      ],
+      "components": [
+        "Button",
+        "Label",
+        "Fieldset",
+        "ErrorSummary"
+      ]
+    },
+    {
+      "id": "overlays",
+      "guide": "references/flood-overlays/SKILL.md",
+      "groups": [
+        "overlays"
+      ],
+      "components": [
+        "Select",
+        "Combobox",
+        "MultiSelect",
+        "TreeSelect",
+        "DatePicker",
+        "DateRangePicker",
+        "TimePicker",
+        "DateTimePicker",
+        "DateTimeRangePicker"
+      ]
+    },
+    {
+      "id": "navigation",
+      "guide": "references/flood-navigation/SKILL.md",
+      "groups": [
+        "navigation"
+      ],
+      "components": [
+        "Tree",
+        "TreeSelect",
+        "Toolbar",
+        "CommandList",
+        "ListBox",
+        "ToggleGroup",
+        "SegmentedControl",
+        "Accordion",
+        "Collapsible"
+      ]
+    },
+    {
+      "id": "data-display",
+      "guide": "references/flood-data-display/SKILL.md",
+      "groups": [
+        "content"
+      ],
+      "components": [
+        "UploadItem",
+        "UploadList",
+        "EmptyState",
+        "ScrollArea"
+      ]
+    },
+    {
+      "id": "records",
+      "guide": "references/flood-records/SKILL.md",
+      "components": [
+        "DataList",
+        "DataListItem",
+        "Table",
+        "DataTable",
+        "DescriptionList",
+        "Card",
+        "Section",
+        "StatusIndicator",
+        "Badge",
+        "FileItem",
+        "FileList",
+        "UploadItem",
+        "UploadList",
+        "EmptyState"
+      ]
+    },
+    {
+      "id": "feedback",
+      "guide": "references/flood-feedback/SKILL.md",
+      "groups": [
+        "feedback"
+      ],
+      "components": [
+        "Field",
+        "Fieldset",
+        "Input",
+        "Textarea",
+        "Select",
+        "ListBox",
+        "CopyButton",
+        "Badge",
+        "UploadItem",
+        "UploadList"
+      ]
+    },
+    {
+      "id": "verification",
+      "guide": "references/flood-verification/SKILL.md",
+      "all": true
+    }
   ]
 }