mustflow 2.28.0 → 2.29.0

package/dist/core/technology-preferences.js

@@ -0,0 +1,189 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord } from './config-loading.js';
+export const TECHNOLOGY_CONFIG_RELATIVE_PATH = '.mustflow/config/technology.toml';
+export const TECHNOLOGY_SCHEMA_VERSION = '1';
+export const TECHNOLOGY_AUTHORITY = 'hint';
+export const TECHNOLOGY_GUIDANCE = [
+    'Technology preferences are hints only; inspect the current repository stack before proposing changes.',
+    'They do not authorize dependency installation, framework migration, command execution, or ignoring existing style.',
+    'When adding packages, verify package reality and use the configured command contract or direct user approval.',
+];
+export const TECHNOLOGY_KINDS = [
+    'language',
+    'runtime',
+    'framework',
+    'library',
+    'tool',
+    'service',
+    'platform',
+];
+export const TECHNOLOGY_STATUSES = ['preferred', 'allowed', 'avoid'];
+function isTechnologyKind(value) {
+    return TECHNOLOGY_KINDS.includes(value);
+}
+function isTechnologyStatus(value) {
+    return TECHNOLOGY_STATUSES.includes(value);
+}
+function readString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const entries = value
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return entries.length === value.length ? entries : null;
+}
+function normalizeStringList(values) {
+    return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
+}
+export function normalizeTechnologyName(value) {
+    return value.trim().replace(/\s+/gu, ' ');
+}
+export function normalizeTechnologyKey(value) {
+    return normalizeTechnologyName(value).toLowerCase();
+}
+function slug(value) {
+    const normalized = normalizeTechnologyKey(value)
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+    return normalized.length > 0 ? normalized : 'item';
+}
+export function createTechnologyPreferenceId(kind, name, scope) {
+    const scopePart = scope.length > 0 ? `${slug(scope[0])}.` : '';
+    return `${kind}.${scopePart}${slug(name)}`;
+}
+function normalizePreference(raw, index, issues) {
+    const rawKind = readString(raw.kind);
+    if (!rawKind || !isTechnologyKind(rawKind)) {
+        issues.push(`[preferences.${index}].kind must be one of ${TECHNOLOGY_KINDS.join(', ')}`);
+        return null;
+    }
+    const rawName = readString(raw.name);
+    if (!rawName) {
+        issues.push(`[preferences.${index}].name must be a non-empty string`);
+        return null;
+    }
+    const rawStatus = readString(raw.status) ?? 'preferred';
+    if (!isTechnologyStatus(rawStatus)) {
+        issues.push(`[preferences.${index}].status must be preferred, allowed, or avoid`);
+        return null;
+    }
+    const rawAuthority = readString(raw.authority) ?? TECHNOLOGY_AUTHORITY;
+    if (rawAuthority !== TECHNOLOGY_AUTHORITY) {
+        issues.push(`[preferences.${index}].authority must be "${TECHNOLOGY_AUTHORITY}"`);
+        return null;
+    }
+    const scope = normalizeStringList(readStringArray(raw.scope) ?? []);
+    const packages = normalizeStringList(readStringArray(raw.packages) ?? []);
+    const constraints = normalizeStringList(readStringArray(raw.constraints) ?? []);
+    const id = readString(raw.id) ?? createTechnologyPreferenceId(rawKind, rawName, scope);
+    return {
+        id,
+        kind: rawKind,
+        name: normalizeTechnologyName(rawName),
+        status: rawStatus,
+        authority: TECHNOLOGY_AUTHORITY,
+        scope,
+        ecosystem: readString(raw.ecosystem),
+        packages,
+        rationale: readString(raw.rationale),
+        constraints,
+    };
+}
+export function normalizeTechnologyPreferencesTable(table, exists) {
+    const issues = [];
+    const schemaVersion = table ? readString(table.schema_version) ?? '' : TECHNOLOGY_SCHEMA_VERSION;
+    if (table && schemaVersion !== TECHNOLOGY_SCHEMA_VERSION) {
+        issues.push(`[technology].schema_version must be "${TECHNOLOGY_SCHEMA_VERSION}"`);
+    }
+    const rawPreferences = table?.preferences;
+    const preferences = [];
+    if (rawPreferences !== undefined) {
+        if (!Array.isArray(rawPreferences)) {
+            issues.push('[technology].preferences must be an array of tables');
+        }
+        else {
+            for (const [index, rawPreference] of rawPreferences.entries()) {
+                if (!isRecord(rawPreference)) {
+                    issues.push(`[preferences.${index}] must be a TOML table`);
+                    continue;
+                }
+                const preference = normalizePreference(rawPreference, index, issues);
+                if (preference) {
+                    preferences.push(preference);
+                }
+            }
+        }
+    }
+    const seenIds = new Set();
+    for (const preference of preferences) {
+        if (seenIds.has(preference.id)) {
+            issues.push(`[technology].preferences contains duplicate id "${preference.id}"`);
+            continue;
+        }
+        seenIds.add(preference.id);
+    }
+    return {
+        path: TECHNOLOGY_CONFIG_RELATIVE_PATH,
+        exists,
+        schema_version: schemaVersion || TECHNOLOGY_SCHEMA_VERSION,
+        authority: TECHNOLOGY_AUTHORITY,
+        guidance: TECHNOLOGY_GUIDANCE,
+        preferences,
+        issues,
+    };
+}
+export function technologyPreferenceMatches(preference, filters) {
+    if (filters.kind && preference.kind !== filters.kind) {
+        return false;
+    }
+    if (filters.status && preference.status !== filters.status) {
+        return false;
+    }
+    if (filters.scope) {
+        const expectedScope = normalizeTechnologyKey(filters.scope);
+        if (!preference.scope.some((scope) => normalizeTechnologyKey(scope) === expectedScope)) {
+            return false;
+        }
+    }
+    return true;
+}
+function quoteTomlString(value) {
+    return JSON.stringify(value);
+}
+function renderStringArray(values) {
+    return `[${values.map((value) => quoteTomlString(value)).join(', ')}]`;
+}
+export function serializeTechnologyPreferences(preferences) {
+    const lines = [
+        `schema_version = ${quoteTomlString(TECHNOLOGY_SCHEMA_VERSION)}`,
+        '',
+        '# Repository-local technology preferences for agents.',
+        '# Entries here are low-authority hints. They do not authorize dependency installation,',
+        '# migration, command execution, or ignoring current project style.',
+    ];
+    for (const preference of [...preferences].sort((left, right) => left.id.localeCompare(right.id))) {
+        lines.push('', '[[preferences]]', `id = ${quoteTomlString(preference.id)}`, `kind = ${quoteTomlString(preference.kind)}`, `name = ${quoteTomlString(preference.name)}`, `status = ${quoteTomlString(preference.status)}`, `authority = ${quoteTomlString(TECHNOLOGY_AUTHORITY)}`, `scope = ${renderStringArray(preference.scope)}`);
+        if (preference.ecosystem) {
+            lines.push(`ecosystem = ${quoteTomlString(preference.ecosystem)}`);
+        }
+        if (preference.packages.length > 0) {
+            lines.push(`packages = ${renderStringArray(preference.packages)}`);
+        }
+        if (preference.rationale) {
+            lines.push(`rationale = ${quoteTomlString(preference.rationale)}`);
+        }
+        if (preference.constraints.length > 0) {
+            lines.push(`constraints = ${renderStringArray(preference.constraints)}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function technologyConfigExists(projectRoot) {
+    return existsSync(path.join(projectRoot, ...TECHNOLOGY_CONFIG_RELATIVE_PATH.split('/')));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.28.0",
+  "version": "2.29.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/context-report.schema.json

@@ -47,6 +47,7 @@
           "items": { "$ref": "#/$defs/pathContext" }
         },
         "command_contract": { "$ref": "#/$defs/commandContractContext" },
+        "technology_preferences": { "$ref": "#/$defs/technologyPreferencesContext" },
         "effective_policy": { "$ref": "#/$defs/effectivePolicy" },
         "state_policy": { "$ref": "#/$defs/statePolicy" },
         "blocked_actions": {
@@ -149,6 +150,66 @@
         }
       }
     },
+    "technologyPreference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "name",
+        "status",
+        "authority",
+        "scope",
+        "ecosystem",
+        "packages",
+        "rationale",
+        "constraints"
+      ],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "enum": ["language", "runtime", "framework", "library", "tool", "service", "platform"] },
+        "name": { "type": "string" },
+        "status": { "enum": ["preferred", "allowed", "avoid"] },
+        "authority": { "const": "hint" },
+        "scope": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "ecosystem": { "type": ["string", "null"] },
+        "packages": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "rationale": { "type": ["string", "null"] },
+        "constraints": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "technologyPreferencesContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "exists", "authority", "guidance", "count", "preferences", "issues"],
+      "properties": {
+        "path": { "type": "string" },
+        "exists": { "type": "boolean" },
+        "authority": { "const": "hint" },
+        "guidance": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "count": { "type": "integer", "minimum": 0 },
+        "preferences": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/technologyPreference" }
+        },
+        "issues": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
     "effectivePolicy": {
       "type": "object",
       "additionalProperties": false,

package/templates/default/common/.mustflow/config/mustflow.toml

@@ -7,6 +7,7 @@ read_order = [
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/skills/INDEX.md",
 ]
 optional_read_order = [
@@ -20,6 +21,7 @@ repository_map = "REPO_MAP.md"
 skill_index = ".mustflow/skills/INDEX.md"
 command_contract = ".mustflow/config/commands.toml"
 workflow_preferences = ".mustflow/config/preferences.toml"
+technology_preferences = ".mustflow/config/technology.toml"
 workflow_reference = ".mustflow/docs/agent-workflow.md"
 context_index = ".mustflow/context/INDEX.md"
 project_context = ".mustflow/context/PROJECT.md"
@@ -35,6 +37,7 @@ anchor_files = [
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/skills/INDEX.md",
   "README.md",
   "PROJECT.md",
@@ -98,6 +101,7 @@ command_contract = true
 skills = true
 repo_map = "generated_optional"
 preferences = "optional"
+technology_preferences = "optional"
 context = "optional"
 local_index = "generated_optional"
 work_items = "disabled"
@@ -136,6 +140,7 @@ read = [
   ".mustflow/docs/agent-workflow.md",
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/commands.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/skills/INDEX.md",
 ]
 
@@ -230,6 +235,7 @@ read = [
   "AGENTS.md",
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
 ]
 
 [refresh.levels.skill]
@@ -247,6 +253,7 @@ read = [
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/skills/INDEX.md",
 ]
 
@@ -369,6 +376,7 @@ canonical = [
   ".mustflow/config/commands.toml",
   ".mustflow/config/mustflow.toml",
   ".mustflow/config/preferences.toml",
+  ".mustflow/config/technology.toml",
   ".mustflow/context/**",
   ".mustflow/docs/**",
   ".mustflow/skills/**",

package/templates/default/common/.mustflow/config/technology.toml

@@ -0,0 +1,20 @@
+schema_version = "1"
+
+# Repository-local technology preferences for agents.
+# Entries here are low-authority hints. They do not authorize dependency installation,
+# migration, command execution, or ignoring current project style.
+#
+# [[preferences]]
+# id = "framework.frontend.nextjs"
+# kind = "framework"
+# name = "nextjs"
+# status = "preferred"
+# authority = "hint"
+# scope = ["frontend", "web", "react"]
+# ecosystem = "npm"
+# packages = ["next", "react", "react-dom"]
+# rationale = "Preferred React full-stack framework for product web apps."
+# constraints = [
+#   "Check existing project stack before proposing migration.",
+#   "Do not install packages without direct user approval or a configured command intent.",
+# ]

package/templates/default/i18n.toml

@@ -10,8 +10,8 @@ status_values = ["current", "stale", "needs_review", "missing"]
 [documents."agents.root"]
 source = "locales/en/AGENTS.md"
 source_locale = "en"
-revision = 13
-translations.ko = { path = "locales/ko/AGENTS.md", source_revision = 13, status = "current" }
+revision = 14
+translations.ko = { path = "locales/ko/AGENTS.md", source_revision = 14, status = "current" }
 translations.zh = { path = "locales/zh/AGENTS.md", source_revision = 11, status = "needs_review" }
 translations.es = { path = "locales/es/AGENTS.md", source_revision = 11, status = "needs_review" }
 translations.fr = { path = "locales/fr/AGENTS.md", source_revision = 11, status = "needs_review" }
@@ -53,10 +53,16 @@ source_locale = "en"
 revision = 4
 translations = {}
 
+[documents."config.technology"]
+source = "common/.mustflow/config/technology.toml"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 89
+revision = 94
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -92,13 +98,13 @@ translations = {}
 [documents."skill.code-review"]
 source = "locales/en/.mustflow/skills/code-review/SKILL.md"
 source_locale = "en"
-revision = 5
+revision = 6
 translations = {}
 
 [documents."skill.contract-sync-check"]
 source = "locales/en/.mustflow/skills/contract-sync-check/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.date-number-audit"]
@@ -128,7 +134,7 @@ translations = {}
 [documents."skill.dependency-reality-check"]
 source = "locales/en/.mustflow/skills/dependency-reality-check/SKILL.md"
 source_locale = "en"
-revision = 6
+revision = 7
 translations = {}
 
 [documents."skill.dependency-upgrade-review"]
@@ -164,7 +170,7 @@ translations = {}
 [documents."skill.codebase-orientation"]
 source = "locales/en/.mustflow/skills/codebase-orientation/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.astro-code-change"]
@@ -266,7 +272,19 @@ translations = {}
 [documents."skill.rust-code-change"]
 source = "locales/en/.mustflow/skills/rust-code-change/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
+translations = {}
+
+[documents."skill.runtime-target-selection"]
+source = "locales/en/.mustflow/skills/runtime-target-selection/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
+[documents."skill.structure-first-engineering"]
+source = "locales/en/.mustflow/skills/structure-first-engineering/SKILL.md"
+source_locale = "en"
+revision = 1
 translations = {}
 
 [documents."skill.svelte-code-change"]
@@ -305,6 +323,36 @@ source_locale = "en"
 revision = 3
 translations = {}
 
+[documents."skill.completion-evidence-gate"]
+source = "locales/en/.mustflow/skills/completion-evidence-gate/SKILL.md"
+source_locale = "en"
+revision = 2
+translations = {}
+
+[documents."skill.evidence-stall-breaker"]
+source = "locales/en/.mustflow/skills/evidence-stall-breaker/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
+[documents."skill.command-intent-mapping-gate"]
+source = "locales/en/.mustflow/skills/command-intent-mapping-gate/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
+[documents."skill.public-json-contract-change"]
+source = "locales/en/.mustflow/skills/public-json-contract-change/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
+[documents."skill.provenance-license-gate"]
+source = "locales/en/.mustflow/skills/provenance-license-gate/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.composition-over-inheritance"]
 source = "locales/en/.mustflow/skills/composition-over-inheritance/SKILL.md"
 source_locale = "en"
@@ -362,7 +410,7 @@ translations = {}
 [documents."skill.external-prompt-injection-defense"]
 source = "locales/en/.mustflow/skills/external-prompt-injection-defense/SKILL.md"
 source_locale = "en"
-revision = 5
+revision = 6
 translations = {}
 
 [documents."skill.external-skill-intake"]
@@ -463,7 +511,7 @@ translations = {}
 [documents."skill.source-freshness-check"]
 source = "locales/en/.mustflow/skills/source-freshness-check/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 4
 translations = {}
 
 [documents."skill.source-anchor-authoring"]
@@ -499,7 +547,7 @@ translations = {}
 [documents."skill.security-privacy-review"]
 source = "locales/en/.mustflow/skills/security-privacy-review/SKILL.md"
 source_locale = "en"
-revision = 19
+revision = 21
 translations = {}
 
 [documents."skill.security-regression-tests"]
@@ -517,7 +565,25 @@ translations = {}
 [documents."skill.skill-authoring"]
 source = "locales/en/.mustflow/skills/skill-authoring/SKILL.md"
 source_locale = "en"
-revision = 7
+revision = 8
+translations = {}
+
+[documents."skill.template-install-surface-sync"]
+source = "locales/en/.mustflow/skills/template-install-surface-sync/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
+[documents."skill.restricted-handoff-resume"]
+source = "locales/en/.mustflow/skills/restricted-handoff-resume/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
+[documents."skill.secret-exposure-response"]
+source = "locales/en/.mustflow/skills/secret-exposure-response/SKILL.md"
+source_locale = "en"
+revision = 1
 translations = {}
 
 [documents."skill.test-design-guard"]