@theglitchking/hit-em-with-the-docs 2.7.0 → 2.8.0

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for hit-em-with-the-docs - Self-managing documentation system",
-    "version": "2.7.0"
+    "version": "2.8.0"
   },
   "plugins": [
     {
       "name": "hit-em-with-the-docs",
       "description": "Self-managing documentation system with hierarchical structure, intelligent automation, pattern discovery, and agent orchestration",
-      "version": "2.7.0",
+      "version": "2.8.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hit-em-with-the-docs",
   "description": "Self-managing documentation system with hierarchical structure, intelligent automation, pattern discovery, and agent orchestration",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/README.md

@@ -874,6 +874,43 @@ src/
     └── logger.ts            # Logging and output formatting
 ```
 
+### Lifecycle enforcement (2.8.0+)
+
+hewtd's policy is now **binding on an agent**, not merely documented. A
+`PreToolUse` hook — run by the harness, not the model — **denies** the two
+destructive violations: hand-editing a generated `INDEX.md`/`REGISTRY.md` (it is
+rebuilt from disk; edits are discarded) and `rm`-ing a doc under
+`.documentation/` (use `hewtd archive` — reversible and link-safe). It **warns**,
+without blocking, on `status: deprecated` without archiving and on starting a
+rival `docs/` folder.
+
+It **fails open**: no `.documentation/` tree, or any internal error, and it allows
+everything silently. Both rules are opt-out via an `enforcement` block in
+`.claude/hit-em-with-the-docs.json`. A `SessionStart` brief and a model-invocable
+skill round it out — no `CLAUDE.md` is written or modified.
+
+**Full reference: [docs/enforcement.md](docs/enforcement.md).**
+
+### Indexing: what counts as a document
+
+`INDEX.md` and `REGISTRY.md` are **generated** — `index`, `maintain`, and
+`integrate` rebuild them from disk, so a row you add by hand is overwritten on
+the next run.
+
+Domain folders are walked **recursively**, so a document at any depth inside a
+domain is indexed (`standards/backend/foo.md` appears in `standards/INDEX.md` as
+`backend/foo.md`). Never indexed: the generated `INDEX.md`/`REGISTRY.md`
+themselves; anything under `archive/`, `drafts/`, `reports/`, `_templates/`,
+`node_modules/`, or a nested `.documentation/`; and the vault's `facts/`,
+`incidents/`, and `symptoms/` subtrees, which have their own generators.
+
+Recursive indexing landed in **2.7.1**. Before that the walk was flat and every
+document in a subfolder was invisible to the whole system — so the first
+`index`/`maintain` run after upgrading will add a row for each one.
+
+**Full contract, and the troubleshooting ladder for "my doc isn't in the index":
+[docs/indexing.md](docs/indexing.md).**
+
 ### File Structure
 
 When you run `hewtd init`, it creates this structure:
@@ -887,7 +924,9 @@ When you run `hewtd init`, it creates this structure:
 ├── security/                 # Security documentation (priority: 9)
 │   ├── INDEX.md             # Security domain table of contents
 │   ├── REGISTRY.md          # Quick reference for security docs
-│   └── *.md                 # Individual security documents
+│   ├── *.md                 # Individual security documents
+│   └── auth/                # Subfolders are indexed too (2.7.1+)
+│       └── *.md             # → listed as auth/<name>.md
 │
 ├── api/                      # API documentation (priority: 8)
 │   ├── INDEX.md

package/dist/action/core/enforce/guard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lifecycle enforcement — the decision function behind the PreToolUse hook.
+ *
+ * hewtd's lifecycle policy has always been enforced at the CLI boundary (the
+ * archive link guard, `auto: false`, the frontmatter schema). None of that
+ * binds an *agent*, which will happily `rm` a doc, hand-edit a generated
+ * INDEX.md, or invent its own `docs/` folder. This is the part the model
+ * cannot reason its way past: the harness runs it, and a `deny` is final.
+ *
+ * Two rules deny, because they destroy work or corrupt a generated artifact.
+ * Everything else at most warns. Anything unrecognized is allowed — this runs
+ * in every session the plugin is installed in, including repos that have
+ * nothing to do with hewtd, so the cost of a false positive is far higher
+ * than the cost of a miss.
+ */
+export type GuardDecision = {
+    action: 'allow';
+} | {
+    action: 'warn';
+    context: string;
+} | {
+    action: 'deny';
+    reason: string;
+};
+export interface GuardInput {
+    toolName: string;
+    /** `file_path` for Write/Edit. */
+    filePath?: string;
+    /** `command` for Bash. */
+    command?: string;
+    /** `content` (Write) or `new_string` (Edit) — used to spot lifecycle changes. */
+    text?: string;
+    /** Docs root relative to the project, e.g. `.documentation`. */
+    docsDir: string;
+}
+/** Which enforcement rules are active. Both default on; users can opt out. */
+export interface EnforcementPolicy {
+    blockIndexEdits: boolean;
+    blockDocDeletion: boolean;
+}
+export declare const DEFAULT_ENFORCEMENT: EnforcementPolicy;
+/**
+ * Is this path inside an `archive/` folder, at any depth?
+ *
+ * Archived docs are **referenceable but never concrete** — history you may cite,
+ * never evidence of what is true now. Nothing under an `archive/` folder is
+ * indexed, audited, link-checked, or validated.
+ */
+export declare function isArchived(path: string): boolean;
+/**
+ * Decide what to do about one tool call. Pure — all I/O lives in the hook.
+ */
+export declare function evaluate(input: GuardInput, policy?: EnforcementPolicy): GuardDecision;
+//# sourceMappingURL=guard.d.ts.map

package/dist/action/core/enforce/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/core/enforce/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GACnB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,eAAO,MAAM,mBAAmB,EAAE,iBAGjC,CAAC;AAOF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIhD;AA4BD;;GAEG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,UAAU,EACjB,MAAM,GAAE,iBAAuC,GAC9C,aAAa,CA4Gf"}

package/dist/action/generators/regenerate.d.ts

@@ -9,6 +9,12 @@ export interface RegenerateOptions {
      */
     domains?: Domain[];
     silent?: boolean;
+    /**
+     * Compute everything, write nothing. `filesWritten` then lists the files
+     * that WOULD be written. Exists so users can preview the (large, one-time)
+     * diff the 2.7.1 recursive walk produces before committing to it.
+     */
+    dryRun?: boolean;
 }
 export interface RegenerateResult {
     /** Per-domain document counts — all domains, regardless of the filter. */
@@ -19,9 +25,14 @@ export interface RegenerateResult {
     totalDocuments: number;
 }
 /**
- * List the document files in a domain directory, excluding the generated
- * INDEX.md / REGISTRY.md. Returns sorted file names (not paths). Empty when
- * the domain directory does not exist.
+ * List the document files in a domain directory, walking subfolders. Returns
+ * sorted, domain-relative POSIX paths (`backend/entity-schema-contract.md`).
+ * Empty when the domain directory does not exist.
+ *
+ * This is the shared spine for three consumers — the index generator, the
+ * `index-drift` audit rule, and the `domain remove` orphan count — so what it
+ * excludes, the whole system excludes: the generated INDEX/REGISTRY at any
+ * depth, `EXCLUDED_DIRS`, and the vault's generator-owned subtrees (issue #12).
  */
 export declare function listDomainDocFiles(docsPath: string, domain: string): Promise<string[]>;
 /**

package/dist/action/generators/regenerate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regenerate.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/generators/regenerate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAmB3D,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8DAA8D;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CASnB;AAkED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAkE3B"}
+{"version":3,"file":"regenerate.d.ts","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/generators/regenerate.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAiE3D,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8DAA8D;IAC9D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBnB;AAwFD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAuE3B"}

package/dist/action/index.d.ts

@@ -34,6 +34,7 @@ export * from './reports/link-report.js';
 export * from './core/archive/manage.js';
 export * from './core/archive/candidates.js';
 export * from './core/archive/links.js';
+export * from './core/enforce/guard.js';
 export * from './core/metadata/errors.js';
 export * from './core/knowledge-base/citers.js';
 export * from './generators/facts-index.js';

package/dist/action/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC;AAG3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAGhD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAGhD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AAGzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AAGxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"","sourceRoot":"","sources":["file:///home/tmarlette/workspace/the-glitch-kingdom/hit-em-with-the-docs/src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC;AAG3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iCAAiC,CAAC;AAGhD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAGhD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AAGzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AAGxC,cAAc,yBAAyB,CAAC;AAGxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}