@indigoai-us/hq-cli 5.282.0 → 5.284.0

package/dist/lib/policy-validator.js

@@ -0,0 +1,136 @@
+const VALIDATION_NOTE = '\n(The HQ_ALLOW_POLICY_NO_TRIGGER override requires explicit human permission.\nAn agent must never set, export, or write it on its own initiative.)\n';
+function isPolicyPath(file) {
+    const low = file.toLowerCase().replaceAll('\\', '/');
+    const basename = low.slice(low.lastIndexOf('/') + 1);
+    return low.endsWith('.md')
+        && (low.includes('/policies/') || low.startsWith('policies/'))
+        && basename !== 'readme.md'
+        && !low.includes('/audit/');
+}
+function normalizeValidatorText(content) {
+    return content.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+}
+function hasValidTriggerGrammar(expression) {
+    let input = expression.replace(/[A-Za-z0-9_./][A-Za-z0-9_./-]*/g, '0');
+    if (/[^01&|!() \t]/.test(input))
+        return false;
+    let position = 0;
+    let valid = true;
+    const skip = () => { while (input[position] === ' ' || input[position] === '\t')
+        position += 1; };
+    let parseOr;
+    let parseAnd;
+    let parseNot;
+    let parseAtom;
+    parseAtom = () => {
+        skip();
+        const current = input[position];
+        if (current === '(') {
+            position += 1;
+            const result = parseOr();
+            skip();
+            if (input[position] !== ')') {
+                valid = false;
+                return false;
+            }
+            position += 1;
+            return result;
+        }
+        if (current === '0' || current === '1') {
+            position += 1;
+            return current === '1';
+        }
+        valid = false;
+        return false;
+    };
+    parseNot = () => {
+        skip();
+        if (input[position] === '!') {
+            position += 1;
+            return !parseNot();
+        }
+        return parseAtom();
+    };
+    parseAnd = () => {
+        let result = parseNot();
+        skip();
+        while (valid && input.slice(position, position + 2) === '&&') {
+            position += 2;
+            const rhs = parseNot();
+            result = result && rhs;
+            skip();
+        }
+        return result;
+    };
+    parseOr = () => {
+        let result = parseAnd();
+        skip();
+        while (valid && input.slice(position, position + 2) === '||') {
+            position += 2;
+            const rhs = parseAnd();
+            result = result || rhs;
+            skip();
+        }
+        return result;
+    };
+    input = input.replace(/\r/g, '');
+    if (input.replace(/[ \t]/g, '') === '')
+        return false;
+    parseOr();
+    skip();
+    return valid && position === input.length;
+}
+export function policyValidatorDiagnostic(content, filePath, env) {
+    if (!isPolicyPath(filePath))
+        return undefined;
+    const normalized = normalizeValidatorText(content);
+    const match = /^\s*---[ \t]*\n([\s\S]*?)\n---[ \t]*(\n|$)/.exec(normalized);
+    if (!match)
+        return `BLOCKED: policy file is missing required trigger frontmatter (missing: no-frontmatter).\n\nEvery policy under */policies/ must declare BOTH:\n  when: <expression>   # e.g.  always  |  git && push  |  deploy || share\n  on:   [<events>]     # any of PreToolUse, PostToolUse, UserPromptSubmit, AssistantIntent, SessionStart\nThese drive just-in-time policy injection. See\ncore/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").\nAdd both fields to the frontmatter, then retry.\n${VALIDATION_NOTE}`;
+    const frontmatter = match[1];
+    const whenLines = [...frontmatter.matchAll(/^[ \t]*when:[ \t]*(.*)$/gm)].map((entry) => entry[1] ?? '');
+    const hasWhen = whenLines.some((line) => /\S/.test(line));
+    const onMatch = /^[ \t]*on:[ \t]*\S/m.test(frontmatter);
+    const missing = [];
+    if (!hasWhen)
+        missing.push('when');
+    if (!onMatch)
+        missing.push('on');
+    if (missing.length > 0)
+        return `BLOCKED: policy file is missing required trigger frontmatter (missing: ${missing.join(',')}).\n\nEvery policy under */policies/ must declare BOTH:\n  when: <expression>   # e.g.  always  |  git && push  |  deploy || share\n  on:   [<events>]     # any of PreToolUse, PostToolUse, UserPromptSubmit, AssistantIntent, SessionStart\nThese drive just-in-time policy injection. See\ncore/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").\nAdd both fields to the frontmatter, then retry.\n${VALIDATION_NOTE}`;
+    const enforcement = /^[ \t]*enforcement:[ \t]*["']?([A-Za-z]+)["']?/m.exec(frontmatter)?.[1]?.toLowerCase();
+    if (enforcement === 'hard') {
+        const tautological = whenLines.some((line) => !/[&!]/.test(line.toLowerCase()) && /(^|[^A-Za-z0-9_./-])always([^A-Za-z0-9_./-]|$)/i.test(line));
+        const onLine = /^[ \t]*on:[ \t]*(.*)$/m.exec(frontmatter)?.[1] ?? '';
+        const reactive = ['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'AssistantIntent'].filter((event) => onLine.includes(event));
+        if (tautological && reactive.length > 0) {
+            const events = reactive.join(', ');
+            return `BLOCKED: an enforcement: hard policy pairs an unconditional \`when:\` with a\nreactive event (${events}).\n\n\`when: always\` is TRUE for every command, prompt, and message. On a reactive\nevent the injector ranks that as an event-specific match, so it takes the\nsession cap slot of a policy that genuinely matched the thing you are doing —\nthe loose trigger crowds out the precise one.\n\nPick one:\n  when: always          + on: [SessionStart]        # ambient governance rule\n  when: <real signal>   + on: [PreToolUse, ...]     # e.g. deploy || publish\n\nName the word(s) that actually appear when the rule is relevant. See\ncore/knowledge/public/hq-core/policies-spec.md ("Trigger Expressions").\n${VALIDATION_NOTE}`;
+        }
+        const after = normalized.slice(match.index + match[0].length);
+        const binding = [];
+        const stop = /^#+[ \t]*(rationale|rationale and context|background|change history|changelog|history|examples?|references?|related|see also|sources?|provenance|evidence)[ \t]*$/i;
+        for (const line of after.split('\n')) {
+            if (stop.test(line.trim().toLowerCase()))
+                break;
+            binding.push(line);
+        }
+        const byteCount = Buffer.byteLength(binding.join('\n').trim(), 'utf8');
+        const rawMax = env.HQ_POLICY_HARD_RULE_MAX_BYTES || '6144';
+        const max = Number.parseInt(rawMax, 10);
+        if (Number.isFinite(max) && max > 0 && byteCount > max) {
+            return `BLOCKED: enforcement: hard policy body is ${byteCount} bytes; the limit is ${rawMax}.\n\nA hard policy is injected VERBATIM into the session, so its length is a\nrecurring context cost for every session it fires in. Keep the binding rule\ntight and move the reasoning out of the injected span: everything from the\nfirst \`## Rationale\` / \`## Background\` / \`## Change history\` /\n\`## Examples\` / \`## References\` heading onward is NOT counted and NOT\ninjected, so long-form context belongs there.\n\nIf the rule genuinely needs more than that, either split it into separate\npolicies with distinct triggers, or raise HQ_POLICY_HARD_RULE_MAX_BYTES in\n.claude/settings.local.json "env".\n${VALIDATION_NOTE}`;
+        }
+    }
+    let malformedWhen;
+    for (const when of whenLines) {
+        if (!hasValidTriggerGrammar(when))
+            malformedWhen = when;
+    }
+    if (malformedWhen !== undefined) {
+        const when = malformedWhen;
+        return `BLOCKED: policy file has a malformed when: trigger expression:\n\n  when: ${when}\n\nThe canonical trigger evaluator rejected it. A space is NOT an AND, and quoted\nphrases are NOT tokens. Use explicit boolean operators instead:\n  "pull request"  -> (pull && request)\n  "force-push"    -> force-push\n\nUse only identifiers joined by the documented boolean grammar:\n  when: <identifier>                 # e.g.  always  |  git  |  /deep-plan\n  when: <expr> && <expr>             # AND\n  when: <expr> || <expr>             # OR\n  when: ! <expr>                     # NOT\n  when: ( <expr> )                   # grouping\nIdentifiers may contain letters, digits, _, ., /, and internal -. Quotes,\nYAML block scalars, adjacent identifiers without an operator, and other\npunctuation are not valid. See core/knowledge/public/hq-core/policies-spec.md\n("Trigger Expressions"). Fix the expression, then retry.\n${VALIDATION_NOTE}`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=policy-validator.js.map

package/dist/native-fast-route.d.ts

@@ -1,3 +1,5 @@
 /** Default-off flag check for native entrypoint routes. */
 export declare function nativeFastRouteEnabled(argv: readonly string[], env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** Reads a default-off fast-route gate from its local override or fresh snapshot. */
+export declare function fastFlagEnabled(flagKey: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
 //# sourceMappingURL=native-fast-route.d.ts.map

package/dist/native-fast-route.js

@@ -5,7 +5,11 @@ export async function nativeFastRouteEnabled(argv, env = process.env) {
     const parsed = parseFastCore(argv);
     if (!parsed || parsed.entry.kind !== "native")
         return false;
-    const override = nativeRouteOverride(parsed.entry.flagKey, env);
+    return fastFlagEnabled(parsed.entry.flagKey, env);
+}
+/** Reads a default-off fast-route gate from its local override or fresh snapshot. */
+export async function fastFlagEnabled(flagKey, env = process.env) {
+    const override = nativeRouteOverride(flagKey, env);
     if (override !== null)
         return override;
     try {
@@ -16,7 +20,7 @@ export async function nativeFastRouteEnabled(argv, env = process.env) {
         const { companyUid } = resolveProcessFlagCompanyContext(env);
         if (!companyUid)
             return false;
-        return readFlagSnapshotFile(companyUid, { env })?.flags[parsed.entry.flagKey] === true;
+        return readFlagSnapshotFile(companyUid, { env })?.flags[flagKey] === true;
     }
     catch {
         // The new path is a rollout optimization. Any unavailable local scope or

package/dist/utils/contribution-table.d.ts

@@ -99,5 +99,5 @@ export declare const CONTRIBUTION_KEYS: ContributionKey[];
  */
 export declare function payloadFor(key: ContributionKey, item: string): string;
 /** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
-export declare const SYMLINK_KEYS: ("workers" | "mcp" | "commands" | "skills" | "knowledge" | "hooks" | "policies" | "scripts")[];
+export declare const SYMLINK_KEYS: ("workers" | "mcp" | "commands" | "hooks" | "skills" | "policies" | "knowledge" | "scripts")[];
 //# sourceMappingURL=contribution-table.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.282.0",
+  "version": "5.284.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {