@imix-js/taproot 0.5.0 → 0.6.0

package/dist/validators/structure-rules.js

@@ -1,4 +1,5 @@
 import { join } from 'path';
+import { existsSync } from 'fs';
 import { flattenTree } from '../core/fs-walker.js';
 const KEBAB_CASE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 export function checkDuplicateMarkers(node) {
@@ -76,9 +77,23 @@ export function checkEmptyFolder(node) {
             message: `${node.marker} folder "${node.name}" has no child folders`,
         }];
 }
+export function checkGlobalTruthsIntent(root) {
+    const globalTruthsIntentPath = join(root.absolutePath, 'global-truths', 'intent.md');
+    if (!existsSync(globalTruthsIntentPath))
+        return [];
+    return [{
+            type: 'warning',
+            filePath: globalTruthsIntentPath,
+            code: 'GLOBAL_TRUTHS_INTENT_CONFLICT',
+            message: '`global-truths/` is a taproot-managed truth store — `intent.md` does not belong here. ' +
+                'Remove `global-truths/intent.md` (and any behaviours beneath it) and use truth files + ' +
+                '`check-if-affected-by` entries in `.taproot/settings.yaml` to enforce them instead.',
+        }];
+}
 export function validateStructure(root, options) {
     const violations = [];
     const nodes = flattenTree(root);
+    violations.push(...checkGlobalTruthsIntent(root));
     for (const node of nodes) {
         violations.push(...checkDuplicateMarkers(node));
         if (node !== root)

package/dist/validators/structure-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"structure-rules.js","sourceRoot":"","sources":["../../src/validators/structure-rules.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"structure-rules.js","sourceRoot":"","sources":["../../src/validators/structure-rules.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imix-js/taproot",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "AI-driven specs, enforced at commit time. Code without traceability doesn't merge.",
   "type": "module",
   "bin": {
@@ -27,7 +27,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "preflight": "bash scripts/preflight.sh"
   },
   "repository": {
     "type": "git",

package/skills/commit.md

@@ -60,7 +60,19 @@ Execute the full commit procedure: classify the commit type, run the appropriate
 
 3. If a `check:` condition requires action you cannot take (e.g. failing tests), report: "Cannot commit — `<condition>` is unresolved and requires: `<correction hint>`." Stop and wait.
 
-4. Stage source files + all matched impl.md files and commit with a concise one-line message.
+4. **Truth consistency check** — if `taproot/global-truths/` exists:
+   a. Collect all truth files applicable at impl level: intent-scoped truths (always), behaviour-scoped truths, and impl-scoped truths.
+   b. Read each applicable truth file. If a file is unreadable, note it and skip.
+   c. Check the staged impl.md and source changes for consistency with applicable truths:
+      - Are defined architectural patterns and project conventions being followed?
+      - Are implementation-level rules respected?
+      - Are domain terms used consistently with their definitions?
+   d. If a conflict is found, surface it before proceeding:
+      > "Truth conflict: `<excerpt>` in staged changes conflicts with `global-truths/<file>`: `<truth excerpt>`. [A] Fix the implementation | [B] Update the truth | [C] Proceed with conflict noted"
+      Wait for the developer's choice. Do not proceed to step 5 until resolved.
+   e. If no conflicts (or all resolved): run `taproot truth-sign` to record the session marker the hook validates.
+
+5. Stage source files + all matched impl.md files and commit with a concise one-line message.
 
 ### Declaration commit
 

package/skills/define-truth.md

@@ -38,9 +38,25 @@ Create or update a truth entry in `taproot/global-truths/` — a fact, business
 
    Wait for the developer's choice.
 
-### Phase 3 — Choose Convention
+### Phase 3 — Name the File
 
-4. Ask which storage convention to use:
+4. Propose a category-level name for the file — one that can hold multiple related truths, not the specific term being captured now:
+
+   > "What should the file be called? Pick a category name so related truths can live together:
+   >
+   > Suggested names by scope:
+   > - **intent**: `glossary` · `principles` · `ux-principles` · `domain-model` · `system-context`
+   > - **behaviour**: `principles` · `guarantees` · `rules`
+   > - **impl**: `architecture` · `tech-choices` · `patterns`
+   >
+   > (Or enter your own name — keep it generic enough to hold future truths of the same kind.)"
+
+   If a file with that name already exists at the target path, note it:
+   > "A file `<name>_<scope>.md` already exists — I'll append to it rather than create a new one."
+
+### Phase 4 — Choose Convention
+
+5. Ask which storage convention to use:
    > "Which convention do you prefer?
    > - **[S] Suffix** — `<name>_<scope>.md` in `taproot/global-truths/` (e.g. `glossary_intent.md`)
    > - **[F] Sub-folder** — `<scope>/<name>.md` in `taproot/global-truths/` (e.g. `intent/glossary.md`)
@@ -50,25 +66,25 @@ Create or update a truth entry in `taproot/global-truths/` — a fact, business
    If the project already has truth files using one convention, note it:
    > "Your project currently uses the <suffix|sub-folder> convention — using it here keeps things consistent."
 
-### Phase 4 — Write the File
+### Phase 5 — Write the File
 
-5. Determine the file path:
+6. Determine the file path:
    - **Suffix**: `taproot/global-truths/<name>_<scope>.md`
    - **Sub-folder**: `taproot/global-truths/<scope>/<name>.md`
 
    Create `taproot/global-truths/` if it does not exist.
 
-6. If the file already exists, read it and present:
+7. If the file already exists, read it and present:
    > "A truth file already exists at `<path>`. Here's the current content: [excerpt]. Do you want to [A] append to it, [B] replace it, or [C] cancel?"
    Wait for the developer's choice.
 
-7. Write the truth file with the confirmed content. Report:
+8. Write the truth file with the confirmed content. Report:
    > "✓ Written: `<path>` (scope: <scope>)"
 
-8. **Scope ambiguity check** — if the file was placed directly in `taproot/global-truths/` with no `_<scope>` suffix and not inside a scoped sub-folder, warn:
+9. **Scope ambiguity check** — if the file was placed directly in `taproot/global-truths/` with no `_<scope>` suffix and not inside a scoped sub-folder, warn:
    > "`<filename>` has no scope signal — it defaults to intent scope (applies everywhere). Add a `_intent`, `_behaviour`, or `_impl` suffix, or move it to a scoped sub-folder, to make the scope explicit."
 
-9. **Conflicting scope signals check** — if the file has both a suffix and is inside a scoped sub-folder that disagree, warn:
+10. **Conflicting scope signals check** — if the file has both a suffix and is inside a scoped sub-folder that disagree, warn:
    > "`<path>` has conflicting scope signals — sub-folder (`<folder-scope>`) is more restrictive than suffix (`<suffix-scope>`). The restrictive scope (`<folder-scope>`) applies. Rename or move the file to resolve."
 
 > 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.

package/skills/ineed.md

@@ -10,7 +10,24 @@ Route a natural language requirement to the right place in the taproot hierarchy
 
 ## Steps
 
-0. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the stated requirement for semantic matches against the patterns listed there. Match signals:
+0. **Global truth check** — Before anything else, determine if the requirement is a **principle, fact, or rule to capture** rather than a feature to build or enforce.
+
+   Global truth signals:
+   - User explicitly says "as a global truth", "add this as a truth", "capture this as a principle"
+   - The requirement is a design principle or quality attribute with no concrete actor or user-visible action (e.g. "fail early", "discoverable by default", "no surprises")
+   - The requirement describes how the system *should be* rather than what it *should do*
+
+   If a global truth signal is present, **interrupt before proceeding**:
+   > "That sounds like a **global truth** — a design principle to capture in `taproot/global-truths/`, not a feature to build. Should I route it there, or is this something that should actively enforce on every implementation via a DoD gate?
+   > **[A]** Global truth → route to `/tr-define-truth`
+   > **[B]** Enforcement gate → apply `check-if-affected-by` pattern
+   > **[C]** New requirement → continue with normal routing"
+
+   - **[A]**: call `/tr-define-truth` with the principle. Stop — do not continue routing.
+   - **[B]**: proceed to pattern check below.
+   - **[C]** or no global truth signal: proceed to pattern check below.
+
+0a. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the stated requirement for semantic matches against the patterns listed there. Match signals:
    - "apply to all / every implementation / every skill / everywhere" → `check-if-affected-by`
    - "guide agents / architecture rules / agents should follow / enforce a rule" → `check-if-affected-by`
    - "enforce documentation / docs must stay current / keep docs accurate" → `document-current`