@namch/agent-assistant 1.3.0 → 1.3.1

package/documents/knowledge-standards/04-testing-standards.md

@@ -0,0 +1,175 @@
+# Agent Assistant — Testing Standards
+
+> **Purpose**: Test file organization, test runner usage, coverage status, test categories, and an honest assessment of what exists versus what is missing
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Test Runner
+
+Agent Assistant uses the **Node.js built-in test runner** (`node:test`), available since Node.js 18. No external test framework (Jest, Mocha, Vitest, AVA) is installed.
+
+### Test Command
+
+```json
+{
+  "test": "node --test cli/*.test.js"
+}
+```
+
+Run via:
+```bash
+npm test
+```
+
+This executes all files matching the glob `cli/*.test.js` using Node.js built-in `--test` flag.
+
+---
+
+## Test File Organization
+
+### File Location and Naming
+
+| Convention | Value |
+|-----------|-------|
+| Test directory | `cli/` (co-located with source) |
+| File pattern | `*.test.js` |
+| Module system | CommonJS (`require`) |
+| Current test files | `cli/install.test.js.example` (example only, not active) |
+
+Tests are co-located with their source files in the `cli/` directory. There is no separate `test/`, `__tests__/`, or `spec/` directory.
+
+### Example Test File Structure
+
+The project includes one example test file at `cli/install.test.js.example`. It demonstrates the intended test structure:
+
+```javascript
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+describe('CLI Installer', () => {
+    describe('ensureDir()', () => {
+        test('should create directory if it does not exist', () => {
+            // test body
+        });
+
+        test('should not throw if directory already exists', () => {
+            // test body
+        });
+    });
+
+    describe('copyWithReplace()', () => {
+        test('should copy files with text replacements', () => {
+            // test body
+        });
+    });
+});
+```
+
+### Test Naming Conventions (from example)
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| `describe` blocks | Function/module name + `()` | `'ensureDir()'`, `'copyWithReplace()'` |
+| `test` blocks | `'should ...'` format | `'should create directory if it does not exist'` |
+| Top-level `describe` | Module name | `'CLI Installer'` |
+| Assertion library | `node:assert` (strict) | `assert.ok()`, `assert.doesNotThrow()` |
+
+---
+
+## Test Categories
+
+### What Exists
+
+| Category | Status | Details |
+|----------|--------|---------|
+| Unit test example | Example file only | `cli/install.test.js.example` — not renamed, not executed by `npm test` |
+| Syntax check | Active | `npm run lint` runs `node --check cli/install.js` to validate JavaScript syntax |
+
+### What is Missing
+
+| Category | Status | Notes |
+|----------|--------|-------|
+| Active unit tests | Not present | Example file has `.example` extension; tests are placeholder stubs with `assert.ok(true, 'Test placeholder')` |
+| Function exports for testing | Not present | `cli/install.js` does not export internal functions; the example test file notes this as a blocker: "requires exporting them from install.js" |
+| Integration tests | Not present | No tests for the full install/uninstall CLI flow |
+| End-to-end tests | Not present | No tests that simulate real platform installation |
+| Web tests | Not present | No test configuration in `web/` (no Vitest, no React Testing Library) |
+| Test coverage tool | Not configured | No nyc, c8, istanbul, or `--experimental-test-coverage` flag |
+| Coverage thresholds | Not configured | No minimum coverage requirements |
+| Test CI integration | Not configured | No CI/CD pipeline to run tests automatically |
+| Snapshot tests | Not present | No snapshot testing for any content type |
+| Markdown/YAML validation tests | Not present | No tests to validate agent/command file schemas |
+| Linting as test | Partial | `node --check` validates syntax but not code quality |
+
+---
+
+## Test Command Reference
+
+| Command | What It Does | Status |
+|---------|-------------|--------|
+| `npm test` | Runs `node --test cli/*.test.js` | Active (but no `.test.js` files exist — only `.test.js.example`) |
+| `npm run lint` | Runs `node --check cli/install.js` | Active — validates JS syntax |
+| `npm run lint:md` | Echoes a suggestion to run markdownlint | Advisory only (does not execute linting) |
+
+### Running the Example Test
+
+To activate the example test:
+
+```bash
+# 1. Rename the example file
+mv cli/install.test.js.example cli/install.test.js
+
+# 2. Run tests
+npm test
+```
+
+The test will pass because all assertions are placeholders (`assert.ok(true, 'Test placeholder')`). Actual test implementation requires exporting functions from `cli/install.js`.
+
+---
+
+## Node.js Built-in Test Runner Reference
+
+The project targets Node.js >=18.0.0.  Key `node:test` APIs used in the example:
+
+| API | Import | Purpose |
+|-----|--------|---------|
+| `test()` | `require('node:test')` | Define a test case |
+| `describe()` | `require('node:test')` | Group related tests |
+| `assert.ok()` | `require('node:assert')` | Assert truthy value |
+| `assert.doesNotThrow()` | `require('node:assert')` | Assert no exception thrown |
+
+Additional `node:assert` methods available but not used in the example: `strictEqual`, `deepStrictEqual`, `throws`, `rejects`, `match`.
+
+The `--test` CLI flag auto-discovers and runs files matching the provided glob pattern. No configuration file is needed.
+
+---
+
+## Gaps Summary
+
+| Gap | Severity | Blocker |
+|-----|----------|---------|
+| No active test files (only `.example`) | High | Tests do not run in current state |
+| Internal functions not exported | High | Cannot unit test `ensureDir`, `copyWithReplace`, etc. without refactoring `install.js` |
+| No coverage tooling | Medium | No way to measure what is tested |
+| No web tests | Medium | React components in `web/` have no test setup |
+| No schema validation tests | Low | Agent/command YAML frontmatter is not validated programmatically |
+| No CI test execution | Medium | Tests are never run automatically |
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| Package manifest (test script) | [../../package.json](../../package.json) |
+| Example test file | [../../cli/install.test.js.example](../../cli/install.test.js.example) |
+| CLI source (no exports) | [../../cli/install.js](../../cli/install.js) |
+| Lint script (syntax check) | [../../package.json](../../package.json) — `scripts.lint` |
+| Lint:md script (advisory) | [../../package.json](../../package.json) — `scripts.lint:md` |
+| Node.js engine requirement | [../../package.json](../../package.json) — `engines.node` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namch/agent-assistant",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Multi-agent orchestration framework for AI coding assistants (Cursor, Copilot, Antigravity, Claude Code, Codex) with Hybrid Skill Orchestration Layer (HSOL).",
   "main": "cli/install.js",
   "bin": {

package/rules/REFERENCE.md

@@ -105,14 +105,18 @@ performance-engineer: ./reports/{topic}/performance/{component}/00-index.md + se
 
 ---
 
-## DOCUMENTATION PATHS (from /docs:core)
+## DOCUMENTATION PATHS (from /docs:core v2.0 — folder-based)
 
 ```yaml
-overview:     ./documents/knowledge-overview.md
-architecture: ./documents/knowledge-architecture.md
-domain:       ./documents/knowledge-domain.md
-source-base:  ./documents/knowledge-source-base.md
-standards:    ./documents/knowledge-standards.md
+# Each knowledge area is now a FOLDER with 00-index.md + sub-files
+overview:     ./documents/knowledge-overview/00-index.md       # + 01~04 sub-files
+architecture: ./documents/knowledge-architecture/00-index.md   # + 01~05 sub-files
+domain:       ./documents/knowledge-domain/00-index.md         # + 01~04 sub-files
+source-base:  ./documents/knowledge-source-base/00-index.md    # + 01~04 sub-files
+standards:    ./documents/knowledge-standards/00-index.md       # + 01~04 sub-files
+
+# To get full context: read 00-index.md first, then load specific sub-files
+# To get quick overview: read only 00-index.md files
 ```
 
 ---

package/skills/docs-audit/README.md

@@ -7,15 +7,16 @@ Documentation can look complete while hiding major risk: unverified controls, pr
 ## What it generates
 Docs Audit manages these mandatory outputs in the audit directory:
 
-- documents/audit/audit-security.md
-- documents/audit/audit-compliance.md
-- documents/audit/audit-dataflow.md
-- documents/audit/audit-recommendations.md
+- documents/audit/audit-security/ (00-index.md + 01~04)
+- documents/audit/audit-compliance/ (00-index.md + 01~04)
+- documents/audit/audit-dataflow/ (00-index.md + 01~04)
+- documents/audit/audit-recommendations/ (00-index.md + 01~04)
 
 Mode behavior:
 
-- CREATE: produce missing audit documents from scratch.
-- UPDATE: refresh existing audit files with current evidence, preserving valid context.
+- CREATE: produce missing audit folders from scratch.
+- UPDATE: refresh existing audit folders with current evidence, preserving valid context.
+- MIGRATE: convert legacy flat `audit-*.md` files into folder-based structure.
 
 ## Core capabilities
 - Scans audit surface using skills/docs-audit/scripts/scan-audit-surface.sh.
@@ -46,12 +47,13 @@ Mode behavior:
 - Existing files in documents/audit/
 
 ## Quality gates / Definition of Done
-- All four mandatory audit documents exist and are up to date.
+- All four mandatory audit folders exist with 00-index.md and sub-files.
 - Major claims are explicitly tagged as Verified, Partial, or Unknown.
 - Scoring is strict, justified, and free from inflated confidence.
 - Findings include severity, rationale, and evidence references.
 - Recommendations are prioritized and realistically actionable.
-- Cross-file consistency is maintained for finding IDs and severity logic.
+- Cross-folder consistency is maintained for finding IDs and severity logic.
+- Each 00-index.md contains a strict score section.
 
 ## Typical use cases
 - Produce a baseline security and compliance audit package.

package/skills/docs-audit/SKILL.md

@@ -13,9 +13,10 @@ metadata:
 
 This skill replaces the workflow in `commands/docs/audit.md` with a reusable, self-contained audit documentation engine.
 
-It supports two modes:
-- `CREATE`: generate missing audit documents from scratch.
-- `UPDATE`: refresh existing audit documents without discarding still-valid context.
+It supports three modes:
+- `CREATE`: generate missing audit folders from scratch.
+- `UPDATE`: refresh existing audit folders without discarding still-valid context.
+- `MIGRATE`: convert legacy flat `audit-*.md` files into folder-based structure.
 
 All generated files under `./documents/` must be written in English only.
 
@@ -45,21 +46,21 @@ Visual clarity bars:
 
 ## Deliverables
 
-| # | File | Purpose |
+| # | Folder | Purpose |
 |---|---|---|
-| 1 | `./documents/audit/audit-security.md` | Security assessment, attack surface, findings, and risk summary |
-| 2 | `./documents/audit/audit-compliance.md` | Compliance posture, control mapping, and verification gaps |
-| 3 | `./documents/audit/audit-dataflow.md` | Data flow map, trust boundaries, privacy posture, and sensitive-data handling |
-| 4 | `./documents/audit/audit-recommendations.md` | Prioritized remediation roadmap, score uplift plan, and implementation guidance |
+| 1 | `./documents/audit/audit-security/` | Security assessment, attack surface, findings, and risk summary (00-index + 01~04) |
+| 2 | `./documents/audit/audit-compliance/` | Compliance posture, control mapping, and verification gaps (00-index + 01~04) |
+| 3 | `./documents/audit/audit-dataflow/` | Data flow map, trust boundaries, privacy posture, and sensitive-data handling (00-index + 01~04) |
+| 4 | `./documents/audit/audit-recommendations/` | Prioritized remediation roadmap, score uplift plan, and implementation guidance (00-index + 01~04) |
 
 Failure condition:
-- If fewer than 4 files are produced, execution is incomplete.
+- If fewer than 4 folders are produced with their sub-files, execution is incomplete.
 
-Per-file standard (mandatory):
-- `audit-security.md`: vulnerabilities identified, OWASP checklist complete, risk assessment complete.
-- `audit-compliance.md`: control coverage matrix, compliance gap register, evidence-state rigor.
-- `audit-dataflow.md`: trust boundaries + sensitive data paths + privacy posture.
-- `audit-recommendations.md`: prioritized and actionable remediation roadmap linked to finding IDs.
+Per-folder standard (mandatory):
+- `audit-security/`: vulnerabilities identified, OWASP checklist complete, risk assessment complete.
+- `audit-compliance/`: control coverage matrix, compliance gap register, evidence-state rigor.
+- `audit-dataflow/`: trust boundaries + sensitive data paths + privacy posture.
+- `audit-recommendations/`: prioritized and actionable remediation roadmap linked to finding IDs.
 
 ## Required References
 
@@ -83,22 +84,23 @@ Before analysis begins:
 4. If `./documents/templates/` or `./documents/templates/audit/` exists, treat it as legacy output and ignore it as a template source.
 5. Do not create or persist template copies under `./documents/templates/`.
 6. If legacy template copies are present, remove them before continuing.
-7. Check which of the 4 audit files already exist.
-8. Determine per-file mode:
-   - missing file -> `CREATE`
-   - existing file -> `UPDATE`
+7. Check which of the 4 audit folders already exist.
+8. Determine per-folder mode:
+   - folder exists with sub-files -> `UPDATE`
+   - flat file exists (legacy `audit-*.md`) -> `MIGRATE`
+   - neither exists -> `CREATE`
 9. Record execution plan before writing.
 
 Output format:
 
 ```markdown
 ## Docs-Audit Execution Plan
-| File | Status | Mode |
-|------|--------|------|
-| audit-security.md | Exists / Missing | UPDATE / CREATE |
-| audit-compliance.md | Exists / Missing | UPDATE / CREATE |
-| audit-dataflow.md | Exists / Missing | UPDATE / CREATE |
-| audit-recommendations.md | Exists / Missing | UPDATE / CREATE |
+| Folder | Status | Mode |
+|--------|--------|------|
+| audit-security/ | Exists / Missing / Legacy flat file | UPDATE / CREATE / MIGRATE |
+| audit-compliance/ | Exists / Missing / Legacy flat file | UPDATE / CREATE / MIGRATE |
+| audit-dataflow/ | Exists / Missing / Legacy flat file | UPDATE / CREATE / MIGRATE |
+| audit-recommendations/ | Exists / Missing / Legacy flat file | UPDATE / CREATE / MIGRATE |
 ```
 
 ### Step 1: Hybrid Audit Reconnaissance
@@ -252,24 +254,25 @@ Mapping rules:
 
 Verify all of the following before completion:
 
-| Check | audit-security | audit-compliance | audit-dataflow | audit-recommendations |
+| Check | audit-security/ | audit-compliance/ | audit-dataflow/ | audit-recommendations/ |
 |---|---|---|---|---|
-| File exists | □ | □ | □ | □ |
-| TOC present | □ | □ | □ | □ |
+| Folder exists with 00-index + sub-files | □ | □ | □ | □ |
+| TOC present in 00-index.md | □ | □ | □ | □ |
 | English only | □ | □ | □ | □ |
 | Evidence sources present | □ | □ | □ | □ |
-| Known gaps present | □ | □ | □ | □ |
-| Final strict score present | □ | □ | □ | □ |
+| Known gaps present in 00-index.md | □ | □ | □ | □ |
+| Strict score in 00-index.md | □ | □ | □ | □ |
 | No TODO/TBD placeholders | □ | □ | □ | □ |
 | No unresolved {placeholder} markers | □ | □ | □ | □ |
 | Claims backed by evidence | □ | □ | □ | □ |
 | Score rationale present | □ | □ | □ | □ |
+| Finding IDs consistent cross-folder | □ | □ | □ | □ |
 
 Additional quality gates:
-- `audit-security.md` must contain at least one attack-surface view and one findings table.
-- `audit-compliance.md` must contain at least one control-mapping table.
-- `audit-dataflow.md` must contain at least one data-flow or trust-boundary diagram.
-- `audit-recommendations.md` must contain a prioritized remediation matrix.
+- `audit-security/` must contain at least one attack-surface view and one findings table.
+- `audit-compliance/` must contain at least one control-mapping table.
+- `audit-dataflow/` must contain at least one data-flow or trust-boundary diagram.
+- `audit-recommendations/` must contain a prioritized remediation matrix and score uplift plan.
 
 ### Step 8: Completion Report
 
@@ -278,12 +281,12 @@ Provide a concise final report:
 ```markdown
 ## Docs-Audit Complete
 
-| File | Mode | Status |
+| Folder | Mode | Status |
 |---|---|---|
-| ./documents/audit/audit-security.md | CREATE/UPDATE | ✅ |
-| ./documents/audit/audit-compliance.md | CREATE/UPDATE | ✅ |
-| ./documents/audit/audit-dataflow.md | CREATE/UPDATE | ✅ |
-| ./documents/audit/audit-recommendations.md | CREATE/UPDATE | ✅ |
+| ./documents/audit/audit-security/ | CREATE/UPDATE/MIGRATE | ✅ |
+| ./documents/audit/audit-compliance/ | CREATE/UPDATE/MIGRATE | ✅ |
+| ./documents/audit/audit-dataflow/ | CREATE/UPDATE/MIGRATE | ✅ |
+| ./documents/audit/audit-recommendations/ | CREATE/UPDATE/MIGRATE | ✅ |
 
 ### Score Summary
 - Security posture: {score}
@@ -308,8 +311,9 @@ Provide a concise final report:
 The skill is not complete if it produces shallow summaries.
 
 It is complete only when:
-- all 4 files exist
-- each file is evidence-driven
-- each file contains a strict score section
+- all 4 folders exist with 00-index.md + sub-files
+- each folder is evidence-driven
+- each 00-index.md contains a strict score section
+- finding IDs are consistent across folders
 - the package is materially as rigorous as `docs-core`
 - recommendations are actionable enough for engineering planning

package/skills/docs-audit/references/scoring-framework.md

@@ -103,12 +103,12 @@ Apply a cap when one or more blockers exist.
 
 Recommended weighted roll-up:
 
-| File | Weight |
+| Folder | Weight |
 | --- | --- |
-| audit-security.md | 35 |
-| audit-compliance.md | 25 |
-| audit-dataflow.md | 20 |
-| audit-recommendations.md | 20 |
+| audit-security/ | 35 |
+| audit-compliance/ | 25 |
+| audit-dataflow/ | 20 |
+| audit-recommendations/ | 20 |
 
 Rules:
 - If any individual file is below 50, overall maturity cannot exceed `D`.

package/skills/docs-core/README.md

@@ -5,33 +5,36 @@ Build and maintain the five foundational project knowledge documents with eviden
 Most repositories have fragmented knowledge: setup steps in one place, architecture in another, and business rules buried in code. Docs Core creates and maintains a single high-quality documentation baseline so onboarding is faster, decisions are safer, and changes are easier to reason about.
 
 ## What it generates
-Docs Core manages these mandatory outputs in the documents directory:
+Docs Core manages these mandatory output **folders** in the documents directory:
 
-- documents/knowledge-overview.md
-- documents/knowledge-architecture.md
-- documents/knowledge-domain.md
-- documents/knowledge-source-base.md
-- documents/knowledge-standards.md
+- documents/knowledge-overview/ (00-index.md + numbered sub-files)
+- documents/knowledge-architecture/ (00-index.md + numbered sub-files)
+- documents/knowledge-domain/ (00-index.md + numbered sub-files)
+- documents/knowledge-source-base/ (00-index.md + numbered sub-files)
+- documents/knowledge-standards/ (00-index.md + numbered sub-files)
+
+Each folder contains `00-index.md` (summary + TOC) and numbered sub-files (`01-...md`, `02-...md`, etc.).
 
 Mode behavior:
 
-- CREATE: generate missing documents from scratch.
-- UPDATE: enrich existing documents with new evidence while preserving valid context.
+- CREATE: generate missing knowledge folders from scratch.
+- UPDATE: enrich existing folder sub-files with new evidence while preserving valid context.
+- MIGRATE: convert legacy flat files (v1.0) to folder-based structure (v2.0).
 
 ## Core capabilities
 - Runs a structured repository scan using skills/docs-core/scripts/scan-project.sh.
-- Produces or updates all five mandatory knowledge documents.
+- Produces or updates all five mandatory knowledge folders (00-index.md + sub-files each).
 - Uses hybrid reconnaissance: script output plus targeted file reading and pattern search.
 - Builds evidence-backed content instead of speculative summaries.
 - Preserves still-valid legacy context in UPDATE mode.
 - Enforces consistency across architecture, domain, source-base, and standards docs.
 
 ## Workflow summary
-1. Validate document targets and determine CREATE or UPDATE per file.
+1. Validate folder targets and determine CREATE, UPDATE, or MIGRATE per knowledge area.
 2. Scan project structure, stack signals, entry points, and core modules.
 3. Build an evidence ledger for architecture, domain, standards, and source map claims.
-4. Draft or update each document using the correct template and required sections.
-5. Verify quality gates across all five outputs before completion.
+4. For each folder: write 00-index.md, then numbered sub-files using templates.
+5. Verify quality gates across all five folders (25+ files) before completion.
 
 ## Inputs and evidence sources
 - skills/docs-core/SKILL.md
@@ -46,8 +49,10 @@ Mode behavior:
 - Existing files in documents/
 
 ## Quality gates / Definition of Done
-- All five mandatory documents exist and are internally consistent.
-- Each file includes practical, onboarding-ready content rather than generic prose.
+- All five mandatory knowledge folders exist with 00-index.md + sub-files.
+- Each sub-file includes practical, onboarding-ready content rather than generic prose.
+- 00-index.md TOC in each folder matches actual sub-files.
+- No sub-file exceeds ~300 lines (split when needed).
 - Claims are traceable to repository evidence.
 - No placeholder text, unresolved TODOs, or unsupported assumptions.
 - Required sections (such as table of contents, evidence sources, known gaps) are present where specified by the workflow.