@amityco/social-plus-vise 0.4.0

package/dist/tools/resolve.js

@@ -0,0 +1,120 @@
+import { classifyOutcome, getOutcomeDefinition } from "../outcomes.js";
+import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
+import { harnessControlsFor } from "./harness.js";
+import { inspectProject } from "./project.js";
+export const resolveRequestTool = {
+    name: "resolve_request",
+    description: "Resolve a natural-language social.plus integration request into a support level and next tools.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            request: { type: "string" },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath", "request"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const request = stringField(args, "request");
+        const inspection = await inspectProject(repoPath, optionalStringField(args, "surfacePath"));
+        const outcome = classifyOutcome(request);
+        const supportLevel = supportFor(outcome, inspection.platforms);
+        return textResult({
+            outcome,
+            supportLevel,
+            surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
+            availableSurfaces: inspection.surfaces.map((surface) => ({ path: surface.path, platforms: surface.platforms })),
+            targetPlatforms: inspection.platforms,
+            nextTools: nextToolsFor(outcome, supportLevel),
+            harness: harnessControlsFor(outcome, inspection.platforms),
+            notes: notesFor(outcome, supportLevel, inspection.platforms),
+        });
+    },
+};
+export const suggestPatchTool = {
+    name: "suggest_patch",
+    description: "Deprecated compatibility tool. Prefer plan_integration for grounded implementation planning. This tool does not write files.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: { type: "string" },
+            request: { type: "string" },
+        },
+        required: ["repoPath", "request"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const request = stringField(args, "request");
+        const inspection = await inspectProject(repoPath);
+        const outcome = classifyOutcome(request);
+        return textResult({
+            deprecated: true,
+            replacement: "plan_integration",
+            writes: [],
+            outcome,
+            targetPlatforms: inspection.platforms,
+            plan: planFor(outcome, inspection.platforms),
+            harness: harnessControlsFor(outcome, inspection.platforms),
+            verification: verificationFor(outcome, inspection.platforms),
+            safety: "Read-only v1: no files were modified.",
+        });
+    },
+};
+function supportFor(outcome, platforms) {
+    if (outcome === "unknown") {
+        return "unsupported";
+    }
+    if (platforms.length === 0) {
+        return "guided";
+    }
+    if (platforms.some((platform) => ["android", "flutter", "typescript", "react-native"].includes(platform))) {
+        return "supported";
+    }
+    if (platforms.includes("ios")) {
+        return "guided";
+    }
+    return "guided";
+}
+function nextToolsFor(outcome, supportLevel) {
+    if (supportLevel === "unsupported") {
+        return ["search_docs"];
+    }
+    if (outcome === "troubleshoot") {
+        return ["inspect_project", "search_docs", "get_doc_page", "validate_setup"];
+    }
+    return ["plan_harness", "plan_integration", "inspect_project", "search_docs", "get_doc_page", "validate_setup", "run_sensors"];
+}
+function notesFor(outcome, supportLevel, platforms) {
+    const notes = [];
+    if (platforms.length === 0) {
+        notes.push("No platform was detected. Ask for the app framework or point repoPath at the project root.");
+    }
+    if (platforms.includes("ios")) {
+        notes.push("iOS should be treated as guided until setup validation rules are expanded.");
+    }
+    if (supportLevel === "unsupported") {
+        notes.push("The request does not map to a known Vise outcome.");
+    }
+    notes.push(...getOutcomeDefinition(outcome).resolveNotes(platforms));
+    return notes;
+}
+function planFor(outcome, platforms) {
+    const platform = platforms[0] ?? "unknown";
+    return getOutcomeDefinition(outcome).resolvePlan(platform);
+}
+function verificationFor(outcome, platforms) {
+    const checks = ["Run the app's normal build or typecheck command."];
+    checks.push(...getOutcomeDefinition(outcome).resolveVerification(platforms[0] ?? "unknown"));
+    if (platforms.includes("android")) {
+        checks.push("For Android, confirm INTERNET permission exists in AndroidManifest.xml.");
+    }
+    return checks;
+}

package/dist/tools/sensors.js

@@ -0,0 +1,185 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { objectInput, optionalNumberField, optionalStringField, stringField, textResult } from "../types.js";
+import { detectCommandSensors } from "./harness.js";
+import { inspectProject } from "./project.js";
+export const runSensorsTool = {
+    name: "run_sensors",
+    description: "Run detected project command sensors, such as build/typecheck/test, with a timeout and structured results.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            repoPath: {
+                type: "string",
+                description: "Absolute or relative path to the customer repository root.",
+            },
+            request: {
+                type: "string",
+                description: "Natural-language integration request. Used for traceability; command sensors are detected from the project.",
+            },
+            include: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional list of sensor names to run. If omitted, all detected command sensors run.",
+            },
+            timeoutMs: {
+                type: "number",
+                default: 120000,
+                description: "Per-command timeout in milliseconds.",
+            },
+            dryRun: {
+                type: "boolean",
+                default: false,
+                description: "If true, return detected sensors without executing commands.",
+            },
+            surfacePath: {
+                type: "string",
+                description: "Optional app/workspace path inside repoPath, such as apps/web or apps/mobile.",
+            },
+        },
+        required: ["repoPath"],
+        additionalProperties: false,
+    },
+    async call(input) {
+        const args = objectInput(input);
+        const repoPath = stringField(args, "repoPath");
+        const timeoutMs = Math.max(1000, Math.min(optionalNumberField(args, "timeoutMs", 120000), 600000));
+        const dryRun = args.dryRun === true;
+        const include = stringArrayField(args, "include");
+        const root = path.resolve(repoPath);
+        const inspection = await inspectProject(root, optionalStringField(args, "surfacePath"));
+        const detectedSensors = await detectCommandSensors(inspection.effectiveRoot, inspection.platforms);
+        const selectedSensors = include.length > 0 ? detectedSensors.filter((sensor) => include.includes(sensor.name)) : detectedSensors;
+        if (dryRun) {
+            return textResult({
+                status: "dry-run",
+                surfacePath: inspection.selectedSurface?.path,
+                targetPlatforms: inspection.platforms,
+                sensors: selectedSensors,
+            });
+        }
+        const results = [];
+        for (const sensor of selectedSensors) {
+            results.push(await runSensor(inspection.effectiveRoot, sensor, timeoutMs));
+        }
+        return textResult({
+            status: aggregateStatus(results),
+            surfacePath: inspection.selectedSurface?.path,
+            targetPlatforms: inspection.platforms,
+            results,
+            skipped: skippedSensors(detectedSensors, selectedSensors, include),
+        });
+    },
+};
+async function runSensor(cwd, sensor, timeoutMs) {
+    const startedAt = Date.now();
+    const [command, ...args] = sensor.command;
+    if (!command) {
+        return {
+            name: sensor.name,
+            command: sensor.command,
+            status: "skipped",
+            reason: "Sensor command is empty.",
+        };
+    }
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const child = spawn(command, args, {
+            cwd,
+            shell: false,
+            env: process.env,
+        });
+        const timeout = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            child.kill("SIGTERM");
+            resolve({
+                name: sensor.name,
+                command: sensor.command,
+                status: "timed-out",
+                durationMs: Date.now() - startedAt,
+                stdout: truncate(stdout),
+                stderr: truncate(stderr),
+                reason: `Timed out after ${timeoutMs}ms.`,
+            });
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve({
+                name: sensor.name,
+                command: sensor.command,
+                status: "failed",
+                durationMs: Date.now() - startedAt,
+                stderr: truncate(error.message),
+                reason: "Failed to start sensor command.",
+            });
+        });
+        child.on("close", (exitCode) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve({
+                name: sensor.name,
+                command: sensor.command,
+                status: exitCode === 0 ? "passed" : "failed",
+                exitCode,
+                durationMs: Date.now() - startedAt,
+                stdout: truncate(stdout),
+                stderr: truncate(stderr),
+            });
+        });
+    });
+}
+function aggregateStatus(results) {
+    if (results.length === 0) {
+        return "no-sensors";
+    }
+    if (results.some((result) => result.status === "timed-out")) {
+        return "timed-out";
+    }
+    if (results.some((result) => result.status === "failed")) {
+        return "failed";
+    }
+    return "passed";
+}
+function skippedSensors(detectedSensors, selectedSensors, include) {
+    const selectedNames = new Set(selectedSensors.map((sensor) => sensor.name));
+    const skipped = detectedSensors
+        .filter((sensor) => !selectedNames.has(sensor.name))
+        .map((sensor) => ({ name: sensor.name, reason: "Not selected by include filter." }));
+    for (const requestedName of include) {
+        if (!detectedSensors.some((sensor) => sensor.name === requestedName)) {
+            skipped.push({ name: requestedName, reason: "No detected sensor matched this include name." });
+        }
+    }
+    return skipped;
+}
+function stringArrayField(input, field) {
+    const value = input[field];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string" && item.trim() !== "");
+}
+function truncate(value, maxLength = 8000) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength)}\n[truncated ${value.length - maxLength} chars]`;
+}

package/dist/types.js

@@ -0,0 +1,31 @@
+export function textResult(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+export function objectInput(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        return {};
+    }
+    return input;
+}
+export function stringField(input, field) {
+    const value = input[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`Missing required string field: ${field}`);
+    }
+    return value;
+}
+export function optionalStringField(input, field) {
+    const value = input[field];
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+export function optionalNumberField(input, field, fallback) {
+    const value = input[field];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}

package/dist/version.js

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function readPackageMetadata() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const packageJsonPath = path.resolve(moduleDir, "..", "package.json");
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (typeof parsed.name !== "string" || typeof parsed.version !== "string") {
+        throw new Error(`Invalid package metadata in ${packageJsonPath}.`);
+    }
+    return {
+        name: parsed.name,
+        version: parsed.version,
+    };
+}
+const packageMetadata = readPackageMetadata();
+export const packageName = packageMetadata.name;
+export const packageVersion = packageMetadata.version;
+export const packageUserAgent = `social-plus-vise/${packageVersion}`;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@amityco/social-plus-vise",
+  "version": "0.4.0",
+  "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AmityCo/social-plus-foundry.git"
+  },
+  "homepage": "https://github.com/AmityCo/social-plus-foundry#readme",
+  "bugs": {
+    "url": "https://github.com/AmityCo/social-plus-foundry/issues"
+  },
+  "keywords": [
+    "social-plus",
+    "mcp",
+    "model-context-protocol",
+    "sdk",
+    "ai-coding"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "vise": "dist/server.js",
+    "spf": "dist/server.js",
+    "social-plus-vise": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "rules",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "postbuild": "chmod +x dist/server.js",
+    "pack:check": "npm pack --dry-run --cache /private/tmp/social-plus-foundry-npm-cache",
+    "publish:check": "npm run validate && npm publish --dry-run --access public --cache /private/tmp/social-plus-foundry-npm-cache",
+    "start": "node dist/server.js",
+    "test": "npm run build && node test/run-fixtures.mjs",
+    "test:cli": "npm run build && node test/run-cli.mjs",
+    "test:compliance": "npm run build && node test/run-compliance-helpers.mjs",
+    "test:docs": "npm run build && node test/run-docs-parser.mjs",
+    "test:improvements": "npm run build && node test/run-improvements.mjs",
+    "test:mcp": "npm run build && node test/run-mcp-smoke.mjs",
+    "test:readme-coverage": "node test/run-readme-coverage.mjs",
+    "test:rule-coverage": "npm run build && node test/run-rule-coverage.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:improvements && npm run pack:check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "typescript": "^5.4.5"
+  }
+}

package/rules/design.yaml

@@ -0,0 +1,66 @@
+{
+  "domain": "design",
+  "schema_version": 1,
+  "rules": [
+    {
+      "id": "android.design.reuse-detected-tokens",
+      "version": 1,
+      "title": "Android UI code must reuse the detected design tokens",
+      "severity": "warning",
+      "rationale": "When the project ships theme/token/Compose color files, social UI built without referencing them produces inline-styled surfaces that drift from the host app's brand. Customers report this as 'the agent ignored our design system'.",
+      "applies_when": { "platforms": ["android"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "android.design.reuse-detected-tokens" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "design_usage", "description": "Where the new UI imports or references the detected design tokens (file path + symbol).", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "flutter.design.reuse-detected-tokens",
+      "version": 1,
+      "title": "Flutter UI code must reuse the detected design tokens",
+      "severity": "warning",
+      "rationale": "When the project ships theme.dart / app_theme.dart, new Flutter widgets should pull colors and typography from the existing ThemeData rather than hardcoded Color() literals.",
+      "applies_when": { "platforms": ["flutter"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "flutter.design.reuse-detected-tokens" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "design_usage", "description": "Where the new widget imports or applies the detected ThemeData.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "ios.design.reuse-detected-tokens",
+      "version": 1,
+      "title": "iOS UI code must reuse the detected design tokens",
+      "severity": "warning",
+      "rationale": "When the project ships AppTheme.swift / Tokens.swift / xcassets, new Swift UI surfaces should reference them instead of inline UIColor / Color values.",
+      "applies_when": { "platforms": ["ios"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "ios.design.reuse-detected-tokens" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "design_usage", "description": "Where the new view references the detected AppTheme or asset catalog tokens.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "typescript.design.reuse-detected-tokens",
+      "version": 1,
+      "title": "TypeScript UI code must reuse the detected design tokens",
+      "severity": "warning",
+      "rationale": "When the project ships theme modules, Tailwind config, shadcn UI components, or design-token files, new social UI should import them instead of inline style props.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.design.reuse-detected-tokens" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "design_usage", "description": "Where the new component imports the detected design tokens / UI kit (e.g., Tailwind config, shadcn component, theme module).", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "react-native.design.reuse-detected-tokens",
+      "version": 1,
+      "title": "React Native UI code must reuse the detected design tokens",
+      "severity": "warning",
+      "rationale": "When the project ships theme modules or a design-system file, new social UI should reference them instead of inline StyleSheet color/spacing literals.",
+      "applies_when": { "platforms": ["react-native"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "react-native.design.reuse-detected-tokens" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "design_usage", "description": "Where the new component imports the detected design tokens / theme module.", "upload_policy": "upload-with-consent" }] }
+      }
+    }
+  ]
+}

package/rules/feed.yaml

@@ -0,0 +1,126 @@
+{
+  "domain": "feed",
+  "schema_version": 1,
+  "rules": [
+    {
+      "id": "typescript.feed.target.literal",
+      "version": 1,
+      "title": "TypeScript feed targets must not be hardcoded literals",
+      "severity": "warning",
+      "rationale": "Feed targets such as communityId, targetId, feedId, and channelId must come from customer app state, not invented source literals.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.feed.target.literal" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "target_source", "description": "Where the runtime feed target comes from.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "react-native.feed.target.literal",
+      "version": 1,
+      "title": "React Native feed targets must not be hardcoded literals",
+      "severity": "warning",
+      "rationale": "Feed targets such as communityId, targetId, feedId, and channelId must come from customer app state, not invented source literals.",
+      "applies_when": { "platforms": ["react-native"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "react-native.feed.target.literal" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "target_source", "description": "Where the runtime feed target comes from.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "android.feed.target.literal",
+      "version": 1,
+      "title": "Android feed targets must not be hardcoded literals",
+      "severity": "warning",
+      "rationale": "Feed targets such as communityId, targetId, feedId, and channelId must come from customer app state, not invented source literals.",
+      "applies_when": { "platforms": ["android"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "android.feed.target.literal" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "target_source", "description": "Where the runtime feed target comes from.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "flutter.feed.target.literal",
+      "version": 1,
+      "title": "Flutter feed targets must not be hardcoded literals",
+      "severity": "warning",
+      "rationale": "Feed targets such as communityId, targetId, feedId, and channelId must come from customer app state, not invented source literals.",
+      "applies_when": { "platforms": ["flutter"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "flutter.feed.target.literal" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "target_source", "description": "Where the runtime feed target comes from.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "ios.feed.target.literal",
+      "version": 1,
+      "title": "iOS feed targets must not be hardcoded literals",
+      "severity": "warning",
+      "rationale": "Feed targets such as communityId, targetId, feedId, and channelId must come from customer app state, not invented source literals.",
+      "applies_when": { "platforms": ["ios"], "outcomes": ["add-feed", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "ios.feed.target.literal" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "target_source", "description": "Where the runtime feed target comes from.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "android.feed.ui-states-present",
+      "version": 1,
+      "title": "Android feed UI must render loading, empty, and error states",
+      "severity": "warning",
+      "rationale": "Live collections take time to load, can be empty, and can error. A feed that only renders the success path looks broken to users on slow networks or fresh accounts.",
+      "applies_when": { "platforms": ["android"], "outcomes": ["add-feed", "setup-live-data", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "android.feed.ui-states-present" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "state_handling", "description": "Where loading, empty, and error states are rendered (or why they aren't needed).", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "flutter.feed.ui-states-present",
+      "version": 1,
+      "title": "Flutter feed UI must render loading, empty, and error states",
+      "severity": "warning",
+      "rationale": "Live streams take time to load, can be empty, and can error. A feed widget that only renders posts looks broken on slow networks or fresh accounts.",
+      "applies_when": { "platforms": ["flutter"], "outcomes": ["add-feed", "setup-live-data", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "flutter.feed.ui-states-present" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "state_handling", "description": "Where loading (CircularProgressIndicator), empty, and error states are rendered.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "ios.feed.ui-states-present",
+      "version": 1,
+      "title": "iOS feed UI must render loading, empty, and error states",
+      "severity": "warning",
+      "rationale": "Live collections take time to load, can be empty, and can error. A feed view that only renders the success path looks broken on slow networks or fresh accounts.",
+      "applies_when": { "platforms": ["ios"], "outcomes": ["add-feed", "setup-live-data", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "ios.feed.ui-states-present" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "state_handling", "description": "Where loading (ProgressView), empty, and error states are rendered.", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "typescript.feed.ui-states-present",
+      "version": 1,
+      "title": "TypeScript feed UI must render loading, empty, and error states",
+      "severity": "warning",
+      "rationale": "Live subscriptions take time to load, can be empty, and can error. A component that only renders posts looks broken on slow networks or fresh accounts.",
+      "applies_when": { "platforms": ["typescript"], "outcomes": ["add-feed", "setup-live-data", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "typescript.feed.ui-states-present" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "state_handling", "description": "Where loading, empty, and error states are rendered (e.g., isLoading state, empty fallback, error boundary).", "upload_policy": "upload-with-consent" }] }
+      }
+    },
+    {
+      "id": "react-native.feed.ui-states-present",
+      "version": 1,
+      "title": "React Native feed UI must render loading, empty, and error states",
+      "severity": "warning",
+      "rationale": "Live subscriptions take time to load, can be empty, and can error. A component that only renders posts looks broken on slow networks or fresh accounts.",
+      "applies_when": { "platforms": ["react-native"], "outcomes": ["add-feed", "setup-live-data", "validate-setup"] },
+      "enforcement": {
+        "deterministic": [{ "check": "validator-finding-absent", "finding_rule_id": "react-native.feed.ui-states-present" }],
+        "attestation": { "allowed": true, "host_agent_min_confidence": "high", "human_allowed": true, "evidence_required": [{ "field": "state_handling", "description": "Where loading (ActivityIndicator), empty, and error states are rendered.", "upload_policy": "upload-with-consent" }] }
+      }
+    }
+  ]
+}