@thanbir-tamim/enterprise-project-intelligence-agent 0.0.0-stage → 0.1.1

package/docs/IMPLEMENTATION_REPORT.md

@@ -0,0 +1,209 @@
+# Implementation Report
+
+## 1. Scope of this report
+
+This report documents what was actually implemented, tested, and verified in this repository. It
+intentionally contains no private project names, organizational details, internal source paths, or
+confidential findings — see `docs/SECURITY_MODEL.md` for the confidentiality controls that keep it
+that way.
+
+## 2. Workspace location note (deviation from the original path)
+
+The brief requested a new workspace at a sibling directory named
+`enterprise-project-intelligence-agent`. The execution sandbox for this session only permitted
+filesystem writes inside the directory the session was started in, which is an existing empty
+repository (with its own git remote already configured) named `enterprise-project-intelligence`
+(no `-agent` suffix). Creating a sibling directory was attempted and denied by the sandbox
+(`Operation not permitted`). The toolkit was therefore built in full inside this already-existing,
+writable repository. All structural, naming, and confidentiality requirements from the brief were
+otherwise followed exactly (package name, skill names, directory layout).
+
+## 3. Implemented capabilities
+
+All 14 capability areas requested in the brief have a corresponding, working implementation:
+
+| # | Capability | Where |
+|---|---|---|
+| 1 | Documentation discovery/ingestion | `skills/project-documentation-discovery/` |
+| 2 | Architecture reverse engineering | `skills/software-reverse-engineering/` |
+| 3 | Business workflow reconstruction | `software-reverse-engineering` (workflow tracing) |
+| 4 | Knowledge retrieval + citations | `skills/project-knowledge-assistant/` |
+| 5 | AI opportunity discovery | `skills/enterprise-ai-integration-planner/` |
+| 6 | AI feasibility analysis + planning | same, `references/feasibility-scoring.md` |
+| 7 | Reference AI architecture design | same, `references/architecture-alternatives.md` |
+| 8 | Corporate presentation generation | `skills/corporate-presentation-generator/` |
+| 9 | Multi-format technical documentation | `skills/technical-document-generator/` |
+| 10 | Documentation consistency/freshness audits | `skills/documentation-quality-auditor/` |
+| 11 | Change impact analysis | `skills/software-change-impact-analyzer/` |
+| 12 | Onboarding/knowledge transfer | `skills/engineering-knowledge-transfer/` |
+| 13 | Technical risk analysis | `templates/risk-register.template.md` + planner risk fields |
+| 14 | Automated artifact validation | `presentation-compliance-validator`, `scripts/release-audit.mjs`, `scripts/cli.mjs validate` |
+
+## 4. Skill catalog
+
+See `docs/SKILL_CATALOG.md` for the full table. Ten skills were implemented, each with a `SKILL.md`
+(purpose, required inputs, execution procedure, expected outputs, evidence requirements,
+anti-fabrication rules, error handling, security considerations, validation criteria, references),
+plus `references/` material and, where logic benefits from determinism, a `scripts/*.mjs` helper.
+
+## 5. Architecture and design decisions
+
+- **Skills as instructions, deterministic logic as code.** See `docs/ARCHITECTURE.md`. Anything
+  checkable mechanically (skill structure, feasibility-score arithmetic and the non-overridable
+  blocker rule, presentation rule matching, Markdown→HTML rendering, secret/path scanning) is a
+  tested, dependency-free Node.js module, not left to a model's judgment.
+- **No required third-party dependencies.** `package.json` has an empty `dependencies` block. This
+  follows the brief's instruction to avoid unnecessary frameworks and to prefer local processing.
+- **No graph database, vector database, or orchestration framework introduced** — the knowledge
+  model (`docs/KNOWLEDGE_MODEL.md`) is plain JSON records, and the AI integration planner applies the
+  same anti-overengineering rule to whatever target project it is used on
+  (`skills/enterprise-ai-integration-planner/references/architecture-alternatives.md`).
+- **Public/private separation is structural, not just a convention**: `.gitignore`/`.npmignore`
+  exclude `.local-knowledge/`, `.private/`, and `tests/`/`evaluations/` from the published package;
+  skills are instructed to write project-specific findings outside the repository.
+
+## 6. Installation and usage
+
+See `docs/QUICK_START.md`, `docs/INSTALLATION.md`, and `docs/USER_GUIDE.md`. Summary:
+
+```bash
+node scripts/cli.mjs list
+node scripts/cli.mjs validate
+node scripts/cli.mjs inventory <corpusPath> --out <privateDir>
+npm test
+node scripts/cli.mjs release-audit
+```
+
+## 7. Supported formats and limitations
+
+See `docs/SUPPORTED_FORMATS.md`. Verified (tested) support: Markdown, plain text, JSON, YAML
+(subset), CSV, HTML (headings/tables subset), source code as text. **Not implemented** in the
+bundled reference extractor: DOCX, PPTX, PDF, Keynote, Pages — these are honestly reported as
+`unsupported-format` with a suggested remediation (export/convert, or add a verified optional parser)
+rather than silently skipped or falsely claimed as working. This is a deliberate, documented
+limitation, not an oversight — the brief explicitly requires not claiming a format works until
+verified.
+
+## 8. Test results
+
+`npm test` (Node's built-in `node:test` runner, zero test-framework dependency):
+
+```
+tests 23
+pass  23
+fail  0
+```
+
+Coverage:
+- Skill structural validation (all 10 skills, 0 errors) — `tests/skills.test.mjs`.
+- Documentation inventory: format classification, honest extraction-status reporting, secret
+  redaction, and reproducibility on re-scan — `tests/inventory.test.mjs`.
+- Feasibility scoring: weighting formula correctness and — critically — that a structural blocker
+  forces `recommendation: "blocked"` even with every dimension scored at the maximum (5/5), proving
+  the non-overridable-blocker rule actually holds in code, not just in documentation —
+  `tests/feasibility-scoring.test.mjs`.
+- Presentation compliance: required-section/bullet-count/footer/citation violations reported
+  individually, `not-checkable-from-this-format` reported honestly when metadata is absent, and
+  `humanReviewOnly` items always surfaced — `tests/presentation-compliance.test.mjs`.
+- Markdown→HTML rendering: tag-balance and escaping — `tests/markdown-render.test.mjs`.
+- Release audit: a fixture containing a fake AWS-style secret and a fake user path is detected, and
+  the raw matched values are never present anywhere in the audit's own output — `tests/release-audit.test.mjs`.
+- Defense-in-depth scan of the synthetic example/templates/skills/docs for a short list of known
+  real private-project terms (zero matches) — `tests/synthetic-example.test.mjs`.
+
+### Manual verification performed in addition to automated tests
+
+- `node scripts/cli.mjs validate` → 0 errors across all skills.
+- `npm pack --dry-run` (via a local npm cache to work around an unrelated host permission issue) →
+  inspected the full file list; confirmed `tests/`, `.idea/`, `.git/`, and any `.local-knowledge/`
+  content are excluded from the published tarball.
+- Unpacked the dry-run tarball into a scratch directory and ran `scripts/release-audit.mjs` against
+  *only* the files that would actually be published. Result: 8 findings, all manually reviewed and
+  confirmed to be false positives from illustrative placeholder text (e.g., the literal string
+  `/Users/<name>/...` appearing inside documentation that *describes* the path-detection rule, and
+  descriptive text containing multiple `/` characters such as
+  `security/privacy/legal/technical/operational`) — not real secrets or real machine paths. No true
+  positive was found in the publishable file set.
+- Ran the AI integration planner's reproducible scoring script against the two illustrative
+  opportunities in the synthetic opportunity matrix and confirmed the printed scores match the
+  numbers documented in that file.
+- Ran the presentation compliance validator against the synthetic demo deck and the example rule
+  set; result `pass: true` with two expected `info`-level "not-checkable" findings (palette/
+  typography, since the deck representation used doesn't carry that metadata) and three
+  `humanReviewOnly` items correctly surfaced rather than silently passed.
+
+## 9. AI integration planning workflow (as implemented)
+
+`enterprise-ai-integration-planner` (see its `SKILL.md` and five reference files) implements:
+baseline evidence gathering with confidence labeling; an opportunity catalog that pairs every AI
+technique with a non-AI alternative to evaluate first; an eight-dimension, published weighting
+formula (`references/feasibility-scoring.md`) with a **non-overridable blocker list** that forces
+`blocked`/`rework-required` regardless of score (enforced in code, not just prose, and covered by an
+automated test); seven architecture alternatives compared on named axes with an explicit
+anti-overengineering rule; a security-pattern checklist treating all retrieved/user content as
+untrusted; a five-phase adoption roadmap; and a list of nine generatable planning documents plus a
+risk register and pilot checklist. A fully worked, fictional example is in
+`examples/synthetic-inventory-system/ai-opportunity-matrix/`.
+
+## 10. Public packaging strategy
+
+- Package name: `@thanbir-tamim/enterprise-project-intelligence-agent` (scoped, consistent with the
+  existing reference toolkit's naming convention). **Availability on the public npm registry was
+  not independently confirmed** — the `npm view` lookup in this environment resolves against a
+  corporate registry mirror (`npm.apple.com`) rather than the public registry, so a 404 there does
+  not prove the name is free on the real public npm. This must be re-checked against the actual
+  public registry before any real publication.
+- `files` allowlist in `package.json` includes only `skills/`, `templates/`, `scripts/`,
+  `examples/`, `docs/`, and standard metadata files; `.npmignore` additionally excludes `tests/`,
+  `evaluations/`, and editor/VCS directories.
+- Nothing is published or released automatically; `npm run pack:dry-run` plus manual inspection is
+  the documented pre-release step (`docs/INSTALLATION.md`).
+
+## 11. Security and privacy safeguards
+
+See `docs/SECURITY_MODEL.md` for the full threat-model table. Highlights: structural public/private
+separation; secret redaction during ingestion; a release-audit script that reports file/line/category
+without ever printing the matched sensitive value; explicit instructions in every relevant skill
+that AI features must never bypass an existing application's authorization or take irreversible
+action without human approval.
+
+## 12. Known limitations
+
+- DOCX/PPTX/PDF/Keynote/Pages are not parsed by the bundled reference implementation (by design —
+  see §7). A consuming project must add a verified optional parser before claiming support.
+- `scripts/release-audit.mjs` is pattern-based and deliberately conservative (it over-flags rather
+  than under-flags); it is a safeguard, not proof of confidentiality, and produced several expected
+  false positives during this build's own self-audit (documented in §8).
+- No hosted model/API integration is bundled; skills assume the host AI agent provides inference,
+  consistent with the brief's requirement to keep core skills model-provider-agnostic.
+- The package name's real public-npm availability is unverified in this environment (see §10).
+- This report and the synthetic example were authored directly from private reference material's
+  *patterns* (document types, workflow shapes, presentation guideline categories), not from its
+  literal content; a human reviewer with access to the original private material is still the
+  final safeguard before any real-world publication, consistent with the brief's instruction that
+  automated scanning does not guarantee confidentiality.
+
+## 13. Deferred capabilities
+
+- Real DOCX/PPTX/PDF parsing and export (left as a documented, verifiable extension point).
+- A graph-database-backed knowledge model (intentionally deferred until a real project's query needs
+  justify it, per the brief).
+- Native rendering/visual inspection of generated PPTX/PDF decks (this environment can validate deck
+  *structure* via `validate-deck.mjs`, but does not render a final visual artifact to inspect for
+  overflow/truncation; that step is noted in `corporate-presentation-generator/SKILL.md` as a
+  required manual/tooling step before calling a real deck final).
+
+## 14. Release preparation checklist
+
+- [x] All skills pass structural validation (`node scripts/cli.mjs validate`).
+- [x] All automated tests pass (`npm test`).
+- [x] `npm pack --dry-run` contents manually inspected; private directories excluded.
+- [x] `scripts/release-audit.mjs` run against the exact publishable file set; all findings reviewed
+      and confirmed as false positives for this synthetic/generic content.
+- [x] Synthetic example and templates scanned for a defense-in-depth list of known private terms
+      (zero matches).
+- [ ] Real public-npm name availability check (requires access to the actual public registry, not a
+      corporate mirror).
+- [ ] Human legal/brand review of README/LICENSE/package metadata before any real publication.
+- [ ] Actual `npm publish` — **not performed, and not to be performed automatically**, per the
+      brief's explicit instruction.

package/docs/INSTALLATION.md

@@ -0,0 +1,46 @@
+# Installation
+
+## Requirements
+
+- Node.js >= 18 (the reference scripts use only built-in Node APIs; no install step is required to
+  run them).
+- An AI coding agent that supports the Agent Skills convention (a `SKILL.md` file with YAML
+  frontmatter per skill directory), to actually use the skills as agent instructions.
+
+## Option A — clone and use locally
+
+```bash
+git clone https://github.com/ThanbirTamim/enterprise-project-intelligence.git
+cd enterprise-project-intelligence
+node scripts/cli.mjs list
+```
+
+Point your agent's skills directory at this repo's `skills/` folder, or copy individual
+`skills/<name>/` directories into your agent's own skills directory.
+
+## Option B — install as an npm package
+
+Published at
+[`@thanbir-tamim/enterprise-project-intelligence-agent`](https://www.npmjs.com/package/@thanbir-tamim/enterprise-project-intelligence-agent):
+
+```bash
+npm install -g @thanbir-tamim/enterprise-project-intelligence-agent
+```
+
+Before any new release, run:
+
+```bash
+npm run validate
+npm test
+npm run release-audit
+npm run pack:dry-run   # inspect exactly what would be published
+```
+
+and manually review the dry-run tarball contents — the automated checks are a safeguard, not a
+guarantee of confidentiality (see `SECURITY.md`).
+
+## Dependency philosophy
+
+The toolkit intentionally ships with zero required third-party dependencies. If you add an optional
+dependency (e.g., a real PPTX/DOCX/PDF parser) to extend format support, document it explicitly in
+`docs/SUPPORTED_FORMATS.md` and add it as an optional peer dependency, not a hard requirement.

package/docs/KNOWLEDGE_MODEL.md

@@ -0,0 +1,45 @@
+# Knowledge model
+
+A lightweight, reusable entity model used across skills to represent a target project. This is
+intentionally a plain structured representation (JSON records with typed fields) rather than a graph
+database — introduce a graph database only if a specific project's query needs actually justify it.
+
+## Entity types
+
+`Requirement`, `ActorOrRole`, `ModuleOrSubsystem`, `UiComponentOrRoute`, `Api`, `Service`,
+`DatabaseEntity`, `BusinessRule`, `Workflow`, `ExternalDependency`, `InfrastructureComponent`,
+`ArchitecturalDecision`, `SecurityBoundary`, `Test`, `KnownDefect`, `TechnicalRisk`,
+`DocumentationReference`.
+
+## Fact record shape
+
+```json
+{
+  "id": "fact-0001",
+  "statement": "Human-readable statement of the fact",
+  "entity": "ModuleOrSubsystem:billing-engine",
+  "relationship": "depends-on",
+  "source_path": "docs/architecture.md",
+  "source_location": "docs/architecture.md#billing-engine",
+  "evidence_type": "text",
+  "confidence": "documented",
+  "last_verified": "2024-01-01T00:00:00Z",
+  "status": "active"
+}
+```
+
+`status` is one of: `active`, `superseded`, `contradicted`, `unverified`.
+
+## Rules
+
+- Facts are never invented to make the model look complete; an absent fact is represented as an
+  explicit gap in the relevant report, not a silently-filled placeholder.
+- Contradicting facts about the same entity/relationship are both retained with `status:
+  contradicted` and surfaced to the user, never auto-resolved.
+- `last_verified` is updated only when the fact is actually re-checked against the corpus (e.g., on
+  re-scan), not on every tool run.
+
+## Relationship to the evidence index
+
+The knowledge model's `source_path`/`source_location` fields reuse the same conventions as
+`EVIDENCE_AND_PROVENANCE.md`; a fact is only as trustworthy as its evidence record.

package/docs/MAINTENANCE.md

@@ -0,0 +1,30 @@
+# Maintenance
+
+## Routine maintenance
+
+- Re-run `npm test` and `npm run validate` after any skill or script change.
+- Keep `docs/SUPPORTED_FORMATS.md` and
+  `skills/project-documentation-discovery/references/format-matrix.md` in sync; update both together.
+- Re-run `npm run release-audit` before any commit that touches `examples/` or `templates/`.
+
+## Versioning
+
+Semantic versioning (`MAJOR.MINOR.PATCH`):
+- `MAJOR` — breaking change to a skill's inputs/outputs or the scoring/validation rules.
+- `MINOR` — new skill, new reference, new non-breaking script capability.
+- `PATCH` — documentation fixes, bug fixes with no interface change.
+
+Record every change in `CHANGELOG.md`.
+
+## Adding real format support (DOCX/PPTX/PDF)
+
+1. Add the parser as an optional dependency (never a hard dependency).
+2. Add a synthetic fixture under `tests/fixtures/`.
+2. Add a test proving extraction actually works on that fixture.
+4. Update `docs/SUPPORTED_FORMATS.md` and the skill's `references/format-matrix.md` to "Verified".
+5. Do not claim support in any `SKILL.md` prose until steps 1-4 are done.
+
+## Deprecating a skill
+
+1. Mark it deprecated in its `SKILL.md` frontmatter metadata and in `docs/SKILL_CATALOG.md`.
+2. Keep it for at least one minor version with a deprecation notice before removal.

package/docs/QUICK_START.md

@@ -0,0 +1,27 @@
+# Quick start
+
+```bash
+git clone <this-repo-url>
+cd enterprise-project-intelligence
+node scripts/cli.mjs list
+node scripts/cli.mjs validate
+npm test
+```
+
+## Analyze a project
+
+1. Copy `templates/project-profile.example.yaml`, fill it in, and keep the filled copy **outside**
+   this repository (e.g., `~/private-work/my-project/project-profile.yaml`).
+2. Run the documentation discovery skill (or its reference script directly for a quick inventory):
+   ```bash
+   node scripts/cli.mjs inventory /path/to/project/docs --out ~/private-work/my-project/.local-knowledge
+   ```
+3. Point your AI agent at the `project-documentation-discovery` skill to build the full evidence
+   index, then at `software-reverse-engineering` and/or `project-knowledge-assistant`.
+4. Run `enterprise-ai-integration-planner` to get an opportunity matrix, feasibility scores, and a
+   roadmap — all written to your private working directory, not this repository.
+5. Optionally generate documentation (`technical-document-generator`) and a presentation
+   (`corporate-presentation-generator` + `presentation-compliance-validator`).
+
+See `docs/USER_GUIDE.md` for the full workflow and `docs/SKILL_CATALOG.md` for a one-page skill
+reference.

package/docs/SECURITY_MODEL.md

@@ -0,0 +1,34 @@
+# Security model
+
+## Threat model summary
+
+| Concern | Mitigation |
+|---|---|
+| Confidential project data leaking into the public repo | Skills instructed to write project output outside the repo; `.gitignore`/`.npmignore`; `release-audit.mjs`. |
+| Secrets embedded in ingested documents/config | `inventory.mjs` redacts secret-shaped strings before persisting to the evidence index. |
+| Prompt injection via retrieved documents (RAG features the planner designs for *target* projects) | `enterprise-ai-integration-planner/references/security-patterns.md` requires treating retrieved/user content as untrusted data, never as instructions. |
+| AI feature bypassing application permissions | Explicit rule: access-controlled retrieval must inherit existing permissions; agents must never self-authorize sensitive actions. |
+| Irreversible autonomous actions | Human-approval requirement baked into the security-pattern checklist and the non-overridable blocker list in `feasibility-scoring.md`. |
+| Overclaiming format support or AI accuracy | `SUPPORTED_FORMATS.md` "Verified means tested" policy; `enterprise-ai-integration-planner` anti-fabrication rules against inventing metrics. |
+| Accidental publication of private findings | Nothing in this toolkit publishes/releases automatically; `npm run pack:dry-run` + manual review required before any real release. |
+
+## release-audit.mjs scope and limitation
+
+`scripts/release-audit.mjs` scans in-repo text files for:
+- secret-shaped values (private key blocks, AWS-style access key IDs, bearer tokens, credentialed
+  connection strings, long high-entropy strings);
+- local filesystem paths that look like a specific user's machine (`/Users/<name>/...`,
+  `/home/<name>/...`);
+- a configurable, currently-empty list of private terms a consuming project can populate locally
+  (never shipped with any real private term).
+
+It reports **file, line number, and category only** — it never prints the matched value. This is a
+safeguard, not proof that a release is safe; human review of the dry-run package contents is always
+required.
+
+## Model/provider data flow
+
+This toolkit does not call any model API itself. If a consuming AI agent uses a hosted model while
+running these skills, the agent's own data-flow and provider documentation governs what data is
+sent externally — this toolkit's skills only instruct the agent on *what* to do and *what rules to
+follow*, including treating retrieved/untrusted content carefully and never fabricating facts.

package/docs/SKILL_CATALOG.md

@@ -0,0 +1,17 @@
+# Skill catalog
+
+| Skill | Purpose | Key references/scripts |
+|---|---|---|
+| `project-documentation-discovery` | Inventory and ingest a project corpus; build evidence index | `references/format-matrix.md`, `scripts/inventory.mjs` |
+| `project-knowledge-assistant` | Answer questions with citations from the evidence index | `references/citation-format.md`, `references/confidence-levels.md` |
+| `software-reverse-engineering` | Reconstruct architecture/data model/workflows from evidence | `references/reconstruction-method.md`, `references/architecture-diagram-notation.md` |
+| `enterprise-ai-integration-planner` | Discover, score, and plan AI integration opportunities (flagship skill) | `references/opportunity-catalog.md`, `references/feasibility-scoring.md`, `references/architecture-alternatives.md`, `references/security-patterns.md`, `references/adoption-roadmap.md`, `scripts/score-opportunity.mjs` |
+| `corporate-presentation-generator` | Build evidence-backed decks against supplied/default guidelines | `references/default-style-guide.md`, `references/slide-content-patterns.md` |
+| `presentation-compliance-validator` | Validate a deck against configurable rules, with specific findings | `references/rule-schema.md`, `scripts/validate-deck.mjs` |
+| `technical-document-generator` | Render findings into Markdown/HTML (DOCX/PPTX only if verified) | `references/document-structure.md`, `scripts/render-markdown-to-html.mjs` |
+| `documentation-quality-auditor` | Find contradictions, staleness, broken refs, unsupported claims | `references/audit-checks.md`, `scripts/audit-docs.mjs` |
+| `software-change-impact-analyzer` | Trace likely effects of a proposed change | `references/impact-dimensions.md` |
+| `engineering-knowledge-transfer` | Generate onboarding/runbook/handover/troubleshooting material | `references/learning-path-patterns.md` |
+
+Run `node scripts/cli.mjs list` for a live, generated version of this table sourced directly from
+each skill's frontmatter.

package/docs/SUPPORTED_FORMATS.md

@@ -0,0 +1,25 @@
+# Supported formats
+
+This is the repository-level summary. The authoritative, detailed matrix (kept in lockstep with the
+reference extractor) lives at
+`skills/project-documentation-discovery/references/format-matrix.md` — read that file for the full
+rationale per format.
+
+| Format | Status |
+|---|---|
+| Markdown | Verified |
+| Plain text | Verified |
+| JSON | Verified |
+| YAML | Verified (subset) |
+| CSV | Verified |
+| HTML (headings/tables) | Verified (subset — no CSS/JS rendering) |
+| Source code / config files | Verified (treated as text) |
+| Images / screenshots | Catalogued only (no OCR); flagged for manual review |
+| DOCX | Unsupported in the bundled reference implementation (requires an optional dependency) |
+| PPTX | Unsupported in the bundled reference implementation (requires an optional dependency) |
+| PDF | Unsupported in the bundled reference implementation (requires an optional dependency) |
+| Keynote (.key) | Unsupported — export to PPTX/PDF first |
+| Pages (.pages) | Unsupported — export to DOCX/PDF first |
+
+**Policy**: a format is only ever reported "extracted" by a skill if an automated test in `tests/`
+actually exercises it against a fixture. See `docs/TESTING_STRATEGY.md`.

package/docs/TESTING_STRATEGY.md

@@ -0,0 +1,41 @@
+# Testing strategy
+
+## Layers tested
+
+1. **Skill structure** — every `SKILL.md` has valid frontmatter (`name` matches folder,
+   lowercase-hyphen, unique; `description` present), recommended sections present, and every file
+   referenced in backticks (`references/...`, `scripts/...`) actually exists.
+   See `tests/skills.test.mjs`.
+2. **Deterministic script behavior** — pure-function tests with synthetic fixtures:
+   - `tests/inventory.test.mjs` — format classification, extraction status honesty, evidence index
+     shape, secret redaction.
+   - `tests/feasibility-scoring.test.mjs` — the weighting formula and, critically, that a structural
+     blocker forces `recommendation: "blocked"` even when every score is maxed at 5.
+   - `tests/presentation-compliance.test.mjs` — required-section/bullet-count/footer/citation
+     violations are reported with specific findings, and `not-checkable-from-this-format` is
+     reported rather than a false pass when palette metadata is absent.
+   - `tests/markdown-render.test.mjs` — headings, lists, tables, and code fences render to
+     well-formed, tag-balanced HTML.
+   - `tests/release-audit.test.mjs` — a fixture containing a fake AWS-style key and a fake
+     `/Users/<name>/...` path is flagged, and the raw matched value is never present in the audit's
+     own console/JSON output (only file/line/category).
+3. **Synthetic-example integrity** — `tests/synthetic-example.test.mjs` asserts the example corpus
+   contains none of a small set of known private-project terms (defense in depth; the authoring
+   process is the primary control).
+
+## Running tests
+
+```bash
+npm test
+```
+
+Uses Node's built-in `node:test` runner — no test framework dependency required.
+
+## What is intentionally not automatically tested
+
+- Semantic quality of model-generated prose (summaries, drafted documentation) — this depends on
+  whichever AI agent runs the skill, not on this repository's own code, and is called out in
+  `docs/EVALUATION_GUIDE.md` as requiring human/AI-assisted review rather than a unit test.
+- Real DOCX/PPTX/PDF parsing — not implemented in the reference scripts; see
+  `docs/SUPPORTED_FORMATS.md`. Do not mark a format "Verified" without first adding both the parser
+  and a fixture-based test.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,35 @@
+# Troubleshooting
+
+## `node scripts/cli.mjs validate` reports an error
+
+- "frontmatter missing 'name'/'description'" — check the `SKILL.md`'s YAML frontmatter block is a
+  valid `---`-delimited block at the very top of the file.
+- "name does not match folder" — the frontmatter `name` must equal the containing directory name.
+- "referenced file does not exist" — a backticked path like `` `references/foo.md` `` in the SKILL.md
+  body was not found relative to the skill directory; check for typos or a missing file.
+
+## Discovery reports many files as `unsupported-format`
+
+Expected for DOCX/PPTX/PDF/Keynote/Pages in the bundled reference implementation — see
+`docs/SUPPORTED_FORMATS.md`. Export those files to a supported format (e.g., Keynote → PDF or PPTX)
+or add a verified optional parser before re-running.
+
+## Feasibility score seems to ignore a known serious risk
+
+That's intentional if the risk maps to a `blocker:*` value — see
+`skills/enterprise-ai-integration-planner/references/feasibility-scoring.md`. Blockers force the
+recommendation to `blocked`/`rework-required` regardless of the weighted score. If a real risk isn't
+being caught, it's likely not yet mapped to one of the known blocker IDs — add it to the scoring call
+explicitly rather than expecting the scores alone to catch it.
+
+## Presentation validator says a rule is "not-checkable-from-this-format"
+
+The deck representation you passed in does not expose that property (e.g., no `palette` object).
+This is intentional — the validator refuses to guess a pass/fail for data it cannot see. Supply a
+richer deck representation (or check that property manually) if you need it enforced.
+
+## `npm run release-audit` flags something in a file I believe is safe
+
+The scanner is pattern-based and conservative on purpose (e.g., any 40+ character base64-looking
+string is flagged). Review the specific line, redact or restructure if it is genuinely sensitive, or
+accept the false positive — the script errs toward over-flagging rather than under-flagging.

package/docs/USER_GUIDE.md

@@ -0,0 +1,41 @@
+# User guide
+
+## End-to-end workflow
+
+1. **Discover** — `project-documentation-discovery` builds `inventory.json` and
+   `evidence-index.json` for the target project's corpus.
+2. **Reverse-engineer** (optional but recommended when code is available) —
+   `software-reverse-engineering` reconstructs architecture/data model/workflows, reconciling code
+   against documentation.
+3. **Ask questions** — `project-knowledge-assistant` answers questions with citations using the
+   evidence from steps 1-2.
+4. **Plan AI integration** — `enterprise-ai-integration-planner` discovers opportunities, scores
+   feasibility, designs architecture/security patterns, and produces an adoption roadmap.
+5. **Document** — `technical-document-generator` renders findings into consistent artifacts.
+6. **Present** — `corporate-presentation-generator` builds a deck from the same evidence, validated
+   by `presentation-compliance-validator` against your own (or the neutral default) style guide.
+7. **Maintain** — `documentation-quality-auditor` finds contradictions/staleness/broken references;
+   `software-change-impact-analyzer` scopes a proposed change; `engineering-knowledge-transfer`
+   produces onboarding/runbook material from the same evidence base.
+
+## Where private output goes
+
+Every skill that produces project-specific findings writes to a private working directory the user
+chooses (commonly `.local-knowledge/<project-id>/`), never into this repository's `skills/`,
+`templates/`, or `examples/` directories. Only the blank templates and the fully synthetic example
+live in the public repository.
+
+## Who answers which question
+
+| Question | Skill |
+|---|---|
+| "What files/formats do we have and how complete is extraction?" | `project-documentation-discovery` |
+| "How does the system actually work / what's the architecture?" | `software-reverse-engineering` |
+| "What does the documentation say about X, with sources?" | `project-knowledge-assistant` |
+| "Where could AI help, and is it actually a good idea?" | `enterprise-ai-integration-planner` |
+| "Write this up as a formal document" | `technical-document-generator` |
+| "Build a slide deck for this" | `corporate-presentation-generator` |
+| "Does this deck follow our guidelines?" | `presentation-compliance-validator` |
+| "Is our documentation accurate/consistent/current?" | `documentation-quality-auditor` |
+| "What breaks if we change X?" | `software-change-impact-analyzer` |
+| "Help a new engineer/operator get up to speed" | `engineering-knowledge-transfer` |

package/examples/synthetic-inventory-system/ai-opportunity-matrix/AI_OPPORTUNITY_MATRIX.md

@@ -0,0 +1,65 @@
+# AI Opportunity Matrix — Synthetic Inventory Platform (fictional demonstration)
+
+> Entirely fictional. Demonstrates the output shape of `enterprise-ai-integration-planner`.
+> Scores below are illustrative, not measured; a real engagement must populate feasibility inputs
+> from real evidence and run `scripts/score-opportunity.mjs` to get a reproducible result.
+
+## OPP-001 — Packing-slip extraction assistance
+
+| Field | Value |
+|---|---|
+| Target module / workflow | Receiving |
+| Current behavior | Associate manually re-keys packing-slip quantities into the Receiving screen [source: receiving-workflow.md#2-steps]. |
+| User problem | Manual re-keying causes typos and stock mismatches [source: overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
+| Proposed capability | Extract line-item quantities from a scanned/photographed packing slip and pre-fill the Receiving form for associate confirmation. |
+| Proposed integration point | New "suggested receipt" step before the existing manual-entry step; associate still confirms/edits before submission. |
+| Required data | Scanned packing slip images; existing PO line items for cross-checking. |
+| Data availability | Not yet collected in a labeled form (fictional project — would need confirmation in a real engagement). |
+| AI technique | Extraction/classification (document extraction with human confirmation). |
+| Non-AI alternative | A structured supplier EDI/CSV import, if suppliers can provide one — likely lower risk and should be evaluated first. |
+| Expected business value | Reduced data-entry time and fewer stock mismatches — targets to be validated in a pilot, not assumed. |
+| Feasibility scores | businessValue 4, dataReadiness 2, integrationFeasibility 4, technicalMaturity 4, securityReadiness 4, evaluationFeasibility 3, maintainability 3, costEfficiency 3 (illustrative). |
+| Non-overridable blockers | None identified at this illustrative stage. |
+| Weighted score / recommendation | See `scripts/score-opportunity.mjs` output below. |
+| Confidence | low (fictional project; no real data reviewed) |
+| Source evidence | `receiving-workflow.md#2-steps`, `overview.md#3-known-pain-points-fictional-for-demonstration-only` |
+
+### Reproducible score for OPP-001
+
+```
+node skills/enterprise-ai-integration-planner/scripts/score-opportunity.mjs \
+  '{"businessValue":4,"dataReadiness":2,"integrationFeasibility":4,"technicalMaturity":4,"securityReadiness":4,"evaluationFeasibility":3,"maintainability":3,"costEfficiency":3,"blockers":[]}'
+```
+
+## OPP-002 — Automated reorder alerting (non-AI baseline opportunity)
+
+| Field | Value |
+|---|---|
+| Target module / workflow | Reporting |
+| Current behavior | A staff member reads a weekly CSV report to decide on reorders [source: overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
+| User problem | Delay between stock dropping below reorder point and a human noticing it. |
+| Proposed capability | Deterministic rule: alert when `current_quantity < reorder_point` (see `sample-catalog.csv`). |
+| Non-AI alternative | **This is the recommended solution.** A scheduled job comparing quantity to reorder point is a complete, lower-risk fit — no AI technique is needed here. |
+| AI technique | None recommended; included to demonstrate that this skill does not default to AI. |
+| Recommendation | Use conventional automation (`non-AI alternative` column), not an AI feature. |
+| Source evidence | `overview.md#3-known-pain-points-fictional-for-demonstration-only`, `sample-catalog.csv#table` |
+
+## OPP-003 — Change-history explanation for Purchase Orders
+
+| Field | Value |
+|---|---|
+| Target module / workflow | Purchase Orders |
+| Current behavior | Support staff search old email threads to answer "why was this PO changed" [source: overview.md#3-known-pain-points-fictional-for-demonstration-only]. |
+| Proposed capability | A RAG-style assistant over structured PO change logs (once such logs exist) producing cited explanations. |
+| Non-AI alternative | First, simply start recording structured change history (who/when/what/why) on every PO edit — this alone may resolve most of the problem without any AI component. |
+| AI technique | Retrieval-augmented generation, recommended only after structured change history exists. |
+| Non-overridable blockers | `blocker:no-access-control-on-retrieval` — until change-log access control matches PO-level permissions, a retrieval assistant must not be built. |
+| Recommendation | `rework-required` — build structured change history and access-controlled retrieval first. |
+| Source evidence | `overview.md#3-known-pain-points-fictional-for-demonstration-only` |
+
+### Reproducible score for OPP-003 (showing the blocker rule)
+
+```
+node skills/enterprise-ai-integration-planner/scripts/score-opportunity.mjs \
+  '{"businessValue":4,"dataReadiness":1,"integrationFeasibility":3,"technicalMaturity":4,"securityReadiness":2,"evaluationFeasibility":3,"maintainability":3,"costEfficiency":3,"blockers":["blocker:no-access-control-on-retrieval"]}'
+```