release(doc): v1.5.0 — Contextual Decision Layer (CDL v1.1.0) & Declarative Gates

.tidyfactor

@@ -1,8 +1,8 @@
 {
   "name": "tidyfactor-doc",
-  "version": "1.4.0",
-  "category": "architecture",
-  "description": "TidyFactor Doc - Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify)",
+  "version": "1.5.0",
+  "category": "development",
+  "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
   "repository": "https://github.com/TidyFactor/Doc",
   "npm": "@alwkala/tidyfactor-doc",
   "compatibility": [

CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to `tidyfactor-doc` will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.5.0] - 2026-09-02
+
+### 🧠 Added — Contextual Decision Layer (CDL v1.1.0) & Declarative Decision Gates
+- **Declarative Decision Gates (`manifest.json`)**: Added formal `decision_gates[]` declaration for the `init` command conforming to manifest schema v1.1.0, defining `doc_engine`, `target_scope`, and `audience_persona` with `track_staleness: true`.
+- **Context Delta Resolution Engine (`references/workflows/collect.md`)**: Upgraded collect workflow to evaluate the mechanical Delta formula:
+  $$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
+- **Interactive Disclosure & User Agency First**: Surfacing all genuine Unknowns interactively with structured options and recommendations.
+- **Anti-Dual-Write Architecture**: Enforcing local markdown files under `docs/` as sole SSOT, with one-way outbound cloud sync via `--sync-brain`.
+
+---
+
 ## [1.4.0] - 2026-09-02
 
 ### 🧠 Added — Sovereign Brain MCP Integration, Hygiene Auditor & Fail-Open Protocol

brand.json

@@ -1,6 +1,6 @@
 {
   "name": "TidyFactor Doc",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "publisher": "TidyFactor Ecosystem",
   "partner": "Alwkala Digital Agency (https://alwkala.com)",
   "contact": {

dist/tidyfactor-doc/.tidyfactor

@@ -1,8 +1,8 @@
 {
   "name": "tidyfactor-doc",
-  "version": "1.4.0",
-  "category": "architecture",
-  "description": "TidyFactor Doc - Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify)",
+  "version": "1.5.0",
+  "category": "development",
+  "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
   "repository": "https://github.com/TidyFactor/Doc",
   "npm": "@alwkala/tidyfactor-doc",
   "compatibility": [

dist/tidyfactor-doc/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to `tidyfactor-doc` will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.5.0] - 2026-09-02
+
+### 🧠 Added — Contextual Decision Layer (CDL v1.1.0) & Declarative Decision Gates
+- **Declarative Decision Gates (`manifest.json`)**: Added formal `decision_gates[]` declaration for the `init` command conforming to manifest schema v1.1.0, defining `doc_engine`, `target_scope`, and `audience_persona` with `track_staleness: true`.
+- **Context Delta Resolution Engine (`references/workflows/collect.md`)**: Upgraded collect workflow to evaluate the mechanical Delta formula:
+  $$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
+- **Interactive Disclosure & User Agency First**: Surfacing all genuine Unknowns interactively with structured options and recommendations.
+- **Anti-Dual-Write Architecture**: Enforcing local markdown files under `docs/` as sole SSOT, with one-way outbound cloud sync via `--sync-brain`.
+
+---
+
 ## [1.4.0] - 2026-09-02
 
 ### 🧠 Added — Sovereign Brain MCP Integration, Hygiene Auditor & Fail-Open Protocol

dist/tidyfactor-doc/brand.json

@@ -1,6 +1,6 @@
 {
   "name": "TidyFactor Doc",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "publisher": "TidyFactor Ecosystem",
   "partner": "Alwkala Digital Agency (https://alwkala.com)",
   "contact": {

dist/tidyfactor-doc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidyfactor/doc",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
   "main": "SKILL.md",
   "bin": {
@@ -50,6 +50,7 @@
     "assets",
     "bin",
     "brand.json",
+    "manifest.json",
     "memory",
     "references",
     "scripts",

dist/tidyfactor-doc/references/workflows/collect.md

@@ -2,29 +2,55 @@
 
 One outcome: a structured findings file — `docs/.collected/<target>.md` — that `generate` can turn into any doc type without re-deriving facts from the codebase itself. `<target>` is the module, package, API surface, or component named by the request (or the whole project if none was named).
 
-## Steps
-
-Run all five collection dimensions from `memory/collection-sources.md` against the target. Skip a dimension only if it genuinely doesn't apply (e.g., no Git history available for an uploaded snapshot) — note the skip and why, don't silently omit it.
-
-0. **Active Context Discovery & Brain MCP (Fail-Open)**:
-   - Silently check if project architecture KIs exist via `search_knowledge_base(query="architecture routes apis", scope="project")` when Brain MCP is active.
-   - If Brain MCP is absent or returns empty, proceed with 0ms delay directly to step 1.
-1. **Code parsing.** Extract existing docblocks/comments, function/method/class signatures, exported types, and public surface area directly from source. Flag anything already documented inline so `generate` doesn't duplicate it.
-2. **Commit history.** Read `git log` and any available PR descriptions for the target's files. Pull out *why* behind non-obvious code — rationale, past bugs fixed, deliberate tradeoffs — not just *what* changed.
-3. **Runtime & environment.** Enumerate required environment variables, config files, software dependencies (with version constraints), and any stated hardware/resource limits. **MANDATORY**: Scrub and redact any actual secrets, production server IPs, database passwords, or private API tokens found in `.env` or config files—record only variable names, expected formats, and generic placeholder values.
-4. **User persona tracing.** Identify who actually reads docs for this target — API consumers, internal maintainers, end-users — and note which facts matter to which persona (an internal maintainer needs the "why"; an API consumer needs the contract).
-5. **Error patterns.** Collect how the code fails: thrown exceptions, error codes, logged failure messages, and how each is meant to be handled or surfaced. Scrub any sensitive runtime credentials or local workstation paths that appear inside logged messages.
-
-6. **Write the findings** to `docs/.collected/<target>.md` as plain structured notes under five headings matching the dimensions above — this is source material for `generate`, not a finished doc, so skip prose polish.
-7. **Update `docs/.doc-manifest.json`**: add `<target>` to the `collected` section with a timestamp.
-8. **Optional Brain Sync (`--sync-brain`)**: Persist extracted architecture facts via `extract_knowledge_item` per `20-brain-baas-integration.md`.
-
-## Validation checklist
-
-- [ ] `docs/.collected/<target>.md` exists and has content (or an explicit "not applicable" note) under all five dimension headings
-- [ ] Every fact traces to something actually found in the code, history, config, or logs — nothing inferred or assumed
-- [ ] Zero sensitive data leaked: all real API keys, passwords, private IPs, and secrets are replaced with safe generic placeholders
-- [ ] No local workstation drive paths (`C:\...`, `file:///...`) exist in findings; all paths are normalized to project-relative paths
-- [ ] Deterministic audit passed via `python scripts/audit_docs.py docs/.collected/<target>.md`
-- [ ] `docs/.doc-manifest.json`'s `collected` section includes `<target>`
-- [ ] Findings are organized by dimension, not pre-formatted as any particular doc type
+---
+
+## 📋 Step 0: Context Delta Resolution & Auto-Sensing
+
+Before prompting the user for scope or parameters, execute the mechanical resolution formula:
+
+$$\text{Unknowns} = \text{Required Decisions} - (\text{Discovered Facts} \cup \text{Brain KIs})$$
+
+1. **Auto-Sensing on Disk**:
+   - Inspect `mkdocs.yml`, `docs/index.html`, `docs/.doc-manifest.json`, and codebase structure.
+   - For sources marked with `track_staleness: true`, compare hash/mtime against stored snapshot.
+   - Any parameter resolved from disk is removed from $\text{Unknowns}$.
+
+2. **Fail-Open Brain MCP Acceleration**:
+   - Check if architecture KIs exist via `search_knowledge_base(query="architecture routes apis", scope="project")`.
+   - If Brain MCP is absent, offline, or returns empty, proceed with 0ms delay directly to Step 1 without warnings.
+
+---
+
+## 🔍 Step 1: Codebase Collection Dimensions
+
+Run all five collection dimensions from `memory/collection-sources.md` against the target:
+
+1. **Code parsing**: Extract existing docblocks/comments, function/method/class signatures, exported types, and public surface area directly from source. Flag anything already documented inline.
+2. **Commit history**: Read `git log` and available PR descriptions for target files. Pull out *why* behind non-obvious code (tradeoffs, rationale, bug fixes).
+3. **Runtime & environment**: Enumerate required environment variables, config files, software dependencies (with version constraints), and resource limits. **MANDATORY**: Scrub and redact any actual secrets, production server IPs, database passwords, or private API tokens—record only variable names and generic placeholders.
+4. **User persona tracing**: Identify who reads docs for this target (API consumers, internal maintainers, end-users) and map facts accordingly.
+5. **Error patterns**: Collect how the code fails: thrown exceptions, error codes, logged failure messages, and resolution steps. Scrub local workstation paths.
+
+---
+
+## 💾 Step 2: Persist Findings & Outbound Push
+
+1. Write structured notes to `docs/.collected/<target>.md` under five headings matching the dimensions above.
+2. Update `docs/.doc-manifest.json` with `<target>` and timestamp.
+3. Save local snapshot `.tidyfactor/doc-brief.snapshot.json` for deterministic drift detection.
+4. **Anti-Dual-Write Outbound Push (`--sync-brain`)**:
+   - Local markdown files are the sole Single Source of Truth.
+   - When `--sync-brain` is explicitly provided, export extracted architecture facts to Brain MCP via `extract_knowledge_item`.
+
+---
+
+## ## Validation checklist
+
+- [ ] Context Delta Resolution executed before prompting user.
+- [ ] `docs/.collected/<target>.md` exists and has content under all five dimension headings.
+- [ ] Every fact traces to verified code, history, config, or logs — zero hallucination.
+- [ ] Zero sensitive data leaked: all real API keys, passwords, private IPs, and secrets replaced with generic placeholders.
+- [ ] No local workstation drive paths (`C:\...`, `file:///...`) exist; all paths are normalized to project-relative paths.
+- [ ] Deterministic audit passed via `python scripts/audit_docs.py docs/.collected/<target>.md`.
+- [ ] `docs/.doc-manifest.json`'s `collected` section includes `<target>`.
+- [ ] Findings organized by dimension, not pre-formatted as any particular doc type.

manifest.json

@@ -1,29 +1,118 @@
 {
-  "$schema": "https://tidyfactor.com/schemas/skill-manifest.tools.schema.json",
+  "manifest_schema_version": "1.1.0",
   "skill_id": "tidyfactor-doc",
-  "version": "1.4.0",
   "skill_root_anchor": "self",
   "tools": [
     {
       "name": "audit_docs",
       "description": "Audits documentation files under /docs for sensitive data leaks, banned absolute URLs, relative link integrity, and Docsify/MkDocs compliance.",
-      "runtime": "python",
-      "entrypoint": "scripts/audit_docs.py",
-      "args_schema": {
-        "type": "object",
-        "properties": {
-          "target": {
-            "type": "string",
-            "description": "Directory or markdown file path to audit (defaults to docs)"
+      "entrypoint": {
+        "runtime": "python3",
+        "script": "scripts/audit_docs.py"
+      },
+      "invocation": {
+        "cli_pattern": "{runtime} {skill_root}/{script} {target_path} {flags}",
+        "args": [
+          {
+            "name": "target",
+            "type": "path",
+            "required": false,
+            "default": "docs",
+            "description": "Directory or markdown file path to audit"
           },
-          "json": {
+          {
+            "name": "json",
             "type": "boolean",
+            "required": false,
+            "default": false,
+            "flag": "--json",
             "description": "Output structured JSON report"
           }
-        }
+        ]
+      },
+      "output": {
+        "format": "json",
+        "channel": "stdout"
       },
-      "cli_pattern": "python {entrypoint} {target} --json",
-      "isolation_recommended": false
+      "runtime_requirements": {
+        "isolation_recommended": false,
+        "dependencies": []
+      },
+      "invoked_by_commands": ["generate", "site", "mkdocs", "docsify", "audit"]
+    }
+  ],
+  "decision_gates": [
+    {
+      "command": "init",
+      "description": "Decision gate selecting documentation engine, navigation structure, and audience persona.",
+      "decisions": [
+        {
+          "key": "doc_engine",
+          "description": "Target documentation publishing engine",
+          "type": "enum",
+          "options": ["mkdocs_material", "docsify_spa", "static_markdown"],
+          "default": "mkdocs_material",
+          "priority": 1,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "mkdocs.yml",
+              "track_staleness": true
+            },
+            {
+              "source": "local_file",
+              "path": "docs/index.html",
+              "track_staleness": true
+            },
+            {
+              "source": "brain_ki",
+              "ki_type": "project"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/doc-brief.snapshot.json" },
+            "brain_ki": {
+              "sync_direction": "outbound_push_only",
+              "requires_flag": "--sync-brain"
+            }
+          }
+        },
+        {
+          "key": "target_scope",
+          "description": "Scope of documentation generation",
+          "type": "enum",
+          "options": ["full_codebase", "api_surface_only", "developer_guide", "end_user_docs"],
+          "default": "full_codebase",
+          "priority": 2,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "docs/.doc-manifest.json"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/doc-brief.snapshot.json" }
+          }
+        },
+        {
+          "key": "audience_persona",
+          "description": "Primary audience reading the documentation",
+          "type": "enum",
+          "options": ["api_consumer", "internal_maintainer", "end_user", "bilingual_developer"],
+          "default": "bilingual_developer",
+          "priority": 3,
+          "discovery": [
+            {
+              "source": "local_file",
+              "path": "brand.json",
+              "json_path": "$.audience"
+            }
+          ],
+          "persist_to": {
+            "local": { "path": ".tidyfactor/doc-brief.snapshot.json" }
+          }
+        }
+      ]
     }
   ]
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tidyfactor/doc",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "TidyFactor Doc — Code Documentation Builder & Dual-Engine Publishing Platform (MkDocs Material & Docsify) for AI Coding Agents",
   "main": "SKILL.md",
   "bin": {
@@ -50,6 +50,7 @@
     "assets",
     "bin",
     "brand.json",
+    "manifest.json",
     "memory",
     "references",
     "scripts",