@hdwebsoft/hdcode-ai-darwin-x64 0.0.7 → 0.0.8

package/resources/skills/hd-iso-sync/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: hd-iso-sync
+description: "Sync ISO 9001/27001 documentation from Google Docs to Markdown files in Git. Use when importing or refreshing ISO documents from a Google Drive folder. Triggers on: sync iso docs, import from google docs, refresh iso markdown, hd-iso-sync, pull ISO docs from Google Drive."
+license: proprietary
+metadata:
+  version: "1.0.0"
+  copyright: "© HDWEBSOFT. All rights reserved."
+---
+
+# ISO Docs Sync
+
+> **[IMPORTANT]** One-way sync only: Google Docs → Markdown. Never edit the generated MD files directly — they will be overwritten on next sync. Only `pinned: true` frontmatter blocks overwrite protection.
+
+## Pipeline
+
+```
+INPUT (folder URL/ID)
+  → Phase 1: Resolve Target
+  → Phase 2: List Documents
+  → Phase 3: Export to Markdown
+  → Phase 4: Update Index
+  → Phase 5: Tagging Prompt
+OUTPUT (docs/iso/*.md + docs/iso/index.md)
+```
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| 1. Resolve | Parse folder arg, validate MCP available | Folder ID confirmed |
+| 2. List | `listFiles` → show doc list for confirmation | File manifest |
+| 3. Export | `readDocument` × N → inject frontmatter → save MD | `docs/iso/**/*.md` |
+| 4. Index | Regenerate index table | `docs/iso/index.md` |
+| 5. Tag | Prompt for untagged docs (clauses, standard, roles) | Tagged frontmatter |
+
+---
+
+## Phase 1: Resolve Target
+
+Parse the argument provided by the user.
+
+- **URL format**: `https://drive.google.com/drive/folders/<FOLDER_ID>` → extract `FOLDER_ID`
+- **Direct ID**: use as-is
+- **No arg**: ask user — "Please provide the Google Drive folder URL or ID containing your ISO documents."
+
+Validate MCP is available:
+- Check that `a-bonus/google-docs-mcp` is configured in Claude Code settings
+- If not: stop and output setup instructions (see MCP Setup section below)
+
+---
+
+## Phase 2: List Documents
+
+Use MCP `listFiles` tool with the resolved folder ID:
+
+```
+listFiles(folderId: "<FOLDER_ID>", recursive: true, mimeType: "application/vnd.google-apps.document")
+```
+
+Display results to user:
+```
+Found 42 Google Docs in folder:
+  - Password Policy (docs/procedures/)
+  - Data Retention Policy (docs/policies/)
+  - Access Control Procedure (docs/procedures/)
+  ...
+
+Proceed with sync? [yes/no]
+```
+
+Stop if user says no.
+
+---
+
+## Phase 3: Export to Markdown
+
+For each document in the list:
+
+1. Call MCP `readDocument(documentId: "<ID>")` → returns document content as markdown
+2. Derive output path:
+   - Mirror Google Drive subfolder structure under `docs/iso/`
+   - Slugify doc title for filename: lowercase, spaces → hyphens, remove special chars
+   - Example: "Password Policy" in folder "procedures/" → `docs/iso/procedures/password-policy.md`
+3. Check if file already exists with `pinned: true` in frontmatter → **skip overwrite** if pinned
+4. Inject frontmatter header:
+
+```yaml
+---
+title: "<exact Google Docs title>"
+gdoc_url: "https://docs.google.com/document/d/<DOC_ID>"
+last_sync: "<YYYY-MM-DDTHH:MM:SSZ>"
+iso_standard: []
+clauses: []
+doc_type: ""
+roles: []
+pinned: false
+---
+```
+
+5. Append document markdown body after frontmatter
+6. Save file
+
+Run all exports — do not stop on individual doc errors; collect errors and report at end.
+
+**After all exports complete — Stale Cleanup:**
+7. Collect all local `docs/iso/**/*.md` files (exclude `docs/iso/index.md`)
+8. Stale = local files whose path does NOT match any file written in steps 1–6
+9. For each stale file:
+   - Read frontmatter — if `pinned: true` → skip (never auto-delete pinned files)
+   - Otherwise → delete the file
+10. If any files were deleted, print warning:
+    ```
+    ⚠️  Removed N stale file(s) (no longer in Google Drive):
+      - docs/iso/procedures/old-policy.md
+      - docs/iso/policies/archived-doc.md
+    ```
+    If 0 stale files → silent (no output)
+
+---
+
+## Phase 4: Update Index
+
+Regenerate `docs/iso/index.md` as a full manifest:
+
+```markdown
+# ISO Document Index
+
+_Last synced: <datetime>_
+
+| Title | Standard | Clauses | Type | Roles | Last Sync | Source |
+|-------|----------|---------|------|-------|-----------|--------|
+| Password Policy | 27001 | A.9.4.3 | procedure | developer, security | 2026-03-05 | [link](...) |
+| ... | | | | | | |
+
+## Untagged Documents (needs clause assignment)
+
+| Title | Path | Action |
+|-------|------|--------|
+| Some Doc | docs/iso/... | Add iso_standard, clauses, doc_type, roles |
+```
+
+---
+
+## Phase 5: Tagging Prompt
+
+If any documents have empty `clauses`, `iso_standard`, or `doc_type` fields:
+
+```
+⚠️  12 documents need clause tagging before gap analysis will work.
+
+Options:
+  [1] Tag now interactively (recommended for first sync)
+  [2] Skip — tag manually later by editing frontmatter
+```
+
+If user chooses interactive tagging, for each untagged doc:
+1. Show doc title + first 200 characters of content
+2. Suggest iso_standard based on title keywords:
+   - Security, access, encryption, incident → 27001
+   - Quality, process, customer, audit → 9001
+   - Both keywords present → suggest both
+3. Suggest clauses from `../hd-iso/reference/iso-27001-requirements.md` or `iso-9001-requirements.md` based on title match
+4. User confirms or corrects → write to frontmatter
+5. Proceed to next doc
+
+---
+
+## Frontmatter Field Reference
+
+See `reference/frontmatter-schema.md` for full spec.
+
+| Field | Type | Values |
+|-------|------|--------|
+| `title` | string | Exact Google Docs title (auto-filled) |
+| `gdoc_url` | string | Full Google Docs URL (auto-filled) |
+| `last_sync` | datetime | ISO 8601 (auto-filled) |
+| `iso_standard` | array | `[9001]`, `[27001]`, `[9001, 27001]` |
+| `clauses` | array | `["7.5", "A.9.4.3", "8.5"]` |
+| `doc_type` | string | `policy` \| `procedure` \| `record` \| `guideline` |
+| `roles` | array | `developer` \| `qa` \| `manager` \| `security` \| `all` |
+| `pinned` | boolean | `true` = never overwrite on sync |
+
+---
+
+## MCP Setup
+
+Requires `a-bonus/google-docs-mcp` configured in Claude Code.
+
+Quick setup — add to `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "google-docs": {
+      "command": "npx",
+      "args": ["-y", "@a-bonus/google-docs-mcp"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "<your-client-id>",
+        "GOOGLE_CLIENT_SECRET": "<your-client-secret>"
+      }
+    }
+  }
+}
+```
+
+For full OAuth setup instructions, see `docs/INSTALL.md` → "ISO Skills Setup".
+
+Or run `/hd-mcp sync` to auto-configure.
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| MCP not configured | Stop, show setup instructions |
+| Folder not found / no access | Stop, show permission guidance |
+| Individual doc export fails | Log warning, continue with rest, report failures at end |
+| `pinned: true` doc | Skip silently, note in summary |
+| Duplicate filename slug | Append `-2`, `-3` etc. |

package/resources/skills/hd-iso-sync/reference/frontmatter-schema.md

@@ -0,0 +1,89 @@
+# ISO Doc Frontmatter Schema
+
+Every file under `docs/iso/` must have this YAML frontmatter block at the top.
+`hd-iso-sync` auto-fills the marked fields. Human fills the rest.
+
+## Full Schema
+
+```yaml
+---
+title: "<string>"          # AUTO — exact Google Docs title
+gdoc_url: "<url>"          # AUTO — full Google Docs edit URL
+last_sync: "<datetime>"    # AUTO — ISO 8601 UTC, e.g. 2026-03-05T08:00:00Z
+iso_standard: []           # HUMAN — list: [9001], [27001], or [9001, 27001]
+clauses: []                # HUMAN — list of clause IDs (see formats below)
+doc_type: ""               # HUMAN — one value: policy | procedure | record | guideline
+roles: []                  # HUMAN — list: developer | qa | manager | security | all
+pinned: false              # HUMAN — set true to prevent overwrite on next sync
+---
+```
+
+## Field Specs
+
+### `iso_standard`
+Which ISO standard(s) this document supports.
+- `[9001]` — Quality management only
+- `[27001]` — Information security only
+- `[9001, 27001]` — Supports both
+
+### `clauses`
+Clause IDs this document satisfies. Use the exact ID format from the standard:
+
+**ISO 27001:2022** (Annex A controls):
+```
+A.5.1   A.5.2   A.5.3  ...  A.5.37
+A.6.1   A.6.2   ...    A.6.8
+A.7.1   A.7.2   ...    A.7.14
+A.8.1   A.8.2   ...    A.8.34
+```
+
+**ISO 27001:2022** (mandatory clauses):
+```
+4.1  4.2  4.3  4.4
+5.1  5.2  5.3
+6.1  6.2  6.3
+7.1  7.2  7.3  7.4  7.5
+8.1  8.2  8.3
+9.1  9.2  9.3
+10.1 10.2
+```
+
+**ISO 9001:2015**:
+```
+4.1  4.2  4.3  4.4
+5.1  5.2  5.3
+6.1  6.2  6.3
+7.1  7.2  7.3  7.4  7.5
+8.1  8.2  8.3  8.4  8.5  8.6  8.7
+9.1  9.2  9.3
+10.1 10.2 10.3
+```
+
+Multiple clauses example:
+```yaml
+clauses: ["7.5", "A.5.37", "A.8.9"]
+```
+
+### `doc_type`
+The nature of the document:
+- `policy` — states intent and direction (e.g. "Information Security Policy")
+- `procedure` — step-by-step instructions (e.g. "Access Review Procedure")
+- `record` — evidence of activity (e.g. "Annual Risk Assessment Record")
+- `guideline` — recommendations, non-mandatory guidance
+
+### `roles`
+Who needs to read this document:
+- `developer` — software engineers, DevOps
+- `qa` — quality assurance, testers
+- `manager` — team leads, department heads
+- `security` — CISO, security team
+- `all` — every employee (use for company-wide policies)
+
+Multiple roles: `["developer", "security"]`
+
+### `pinned`
+Set to `true` to prevent `hd-iso-sync` from overwriting this file.
+Use when you've made manual corrections to the MD body that don't exist in Google Docs yet,
+or when the Google Doc is being heavily edited and you don't want partial content synced.
+
+**Important**: pinned files still appear in the index; sync just skips the body update.

package/resources/skills/hd-iso-verify/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: hd-iso-verify
+description: "ISO document content quality audit. Checks whether a document body actually fulfills ISO requirements for its tagged clauses — not just existence, but content quality. Use when: verifying a policy is ISO-compliant, auditing document quality, checking if a process meets ISO requirements, natural language queries like 'is onboarding ISO compliant', 'verify password policy against ISO 27001', 'hd-iso-verify'."
+license: proprietary
+metadata:
+  version: "1.0.0"
+  copyright: "© HDWEBSOFT. All rights reserved."
+---
+
+# ISO Document Content Verifier
+
+> **[IMPORTANT]** This skill reads from `docs/iso/*.md` (run `hd-iso-sync` first) and
+> `skills/hd-iso/reference/` for clause definitions. All verdicts are advisory — humans
+> own all compliance decisions and auditor submissions.
+
+> **Distinction from `hd-iso gap`**:
+> - `hd-iso gap` — existence check: is there *a* doc for clause X?
+> - `hd-iso-verify` — content check: does that doc *say what ISO requires*?
+
+## Invocation
+
+```
+/hd-iso-verify <path>                          — verify a specific doc
+/hd-iso-verify --clause A.5.17                 — verify all docs tagged with this clause
+/hd-iso-verify --standard 27001                — verify all docs for this standard
+/hd-iso-verify --standard 9001                 — verify all docs for ISO 9001
+/hd-iso-verify --standard 27001 --clause A.8   — verify docs for a clause section
+/hd-iso-verify <natural language query>        — semantic: find + verify docs by topic
+```
+
+**Natural language examples:**
+```
+/hd-iso-verify check if the new member onboarding process is valid against ISO 27001
+/hd-iso-verify verify our password policy against ISO 27001
+/hd-iso-verify is the incident response procedure ISO compliant?
+/hd-iso-verify check backup policy completeness
+```
+
+---
+
+## Phase 0 — Argument Parse + Prerequisite Check
+
+Parse the invocation to determine scope:
+
+| Args | Scope |
+|------|-------|
+| `<path>` | Single file at `docs/iso/<path>` or absolute path |
+| `--clause <id>` | All docs in `docs/iso/` where frontmatter `clauses` contains `<id>` |
+| `--standard <std>` | All docs in `docs/iso/` where frontmatter `iso_standard` contains `<std>` |
+| `--standard <std> --clause <id>` | Intersection: standard AND clause prefix match |
+| Natural language query | → **NL Query Mode** (see below) |
+
+### NL Query Mode
+
+When args are free text (no flags, no file path), extract:
+1. **Topic** — what process/policy is being asked about (e.g., "new member onboarding", "password policy", "backup")
+2. **Standard** — if mentioned explicitly (e.g., "ISO 27001", "9001"); if not → check both standards
+
+Then:
+1. **Find relevant docs** — grep `docs/iso/` for docs whose title or body contains the topic keywords
+2. **Identify relevant clauses** — use the reference files + ISO knowledge to name the 2–5 clauses that typically govern this topic
+   - Examples: "onboarding" → A.6.1 (Screening), A.6.2 (Terms), A.6.3 (Training), A.6.5 (Responsibilities after termination)
+   - "password policy" → A.5.17 (Authentication), A.8.5 (Secure authentication)
+   - "incident response" → A.5.24 (Planning), A.5.26 (Response), A.5.27 (Learning from incidents)
+3. **Scope = found docs** — run full verification (Phase 1–3) on those docs
+4. **Gap check** — for the identified relevant clauses, note any that have no docs tagged (existence gap)
+5. Output includes a preamble: "I found N docs related to '<topic>' covering clauses X, Y, Z. Here's the content quality analysis:"
+
+If no docs found for the topic → report: "No docs found in `docs/iso/` matching '<topic>'. Run `hd-iso gap --standard 27001` to check if a doc for this area is missing entirely."
+
+**Prerequisite checks**:
+- If `docs/iso/` is empty or missing → stop:
+  > "Run `/hd-iso-sync` first to import your ISO documents.
+  > If Google Docs MCP is not yet configured, see `docs/INSTALL.md` → Google Docs MCP section, or run `/hd-mcp` (no args) for guided setup."
+- If no docs match the scope → stop with "No docs found matching `<args>`. Check clause IDs or run `hd-iso gap` first."
+- Load reference files from `skills/hd-iso/reference/` relative to this skill's location:
+  - For ISO 27001 docs: `iso-27001-requirements.md`
+  - For ISO 9001 docs: `iso-9001-requirements.md`
+
+---
+
+## Phase 1 — Load Target Docs
+
+For each doc in scope:
+1. Read the full MD file (frontmatter + body)
+2. Extract frontmatter fields: `title`, `iso_standard`, `clauses`, `doc_type`, `gdoc_url`, `last_sync`
+3. Check for verifiability:
+   - `clauses: []` → skip with warning: "⚠️ `<filename>` has no clause tags — cannot verify. Tag it in frontmatter or re-run `hd-iso-sync` with tagging step."
+   - `iso_standard: []` → warn: "⚠️ `<filename>` has no standard tagged — will infer from clause IDs (A.x = 27001, numeric only = 9001)"
+4. Display loaded scope to user before running verification:
+   ```
+   Verifying 3 documents against ISO 27001:
+     - docs/iso/password-policy.md  (clauses: A.5.17, A.8.5)
+     - docs/iso/access-control.md   (clauses: A.5.15, A.5.18)
+     - docs/iso/incident-response.md (clauses: A.5.24, A.5.26)
+   ```
+
+---
+
+## Phase 2 — Per-Clause Content Check
+
+For each document, run verification clause by clause.
+
+### Step 2a — Load Clause Definition
+
+For each clause in the doc's `clauses` frontmatter:
+- Look up the clause row in the reference file (match by `Clause` column)
+- Extract: clause title + description
+- If clause not found in reference → note as "unknown clause ID — skipping"
+
+### Step 2b — Universal Quality Checklist
+
+Apply these 5 checks to the document body for EACH clause being evaluated.
+These are the baseline ISO document control requirements (ISO 9001 cl. 7.5 / ISO 27001 cl. 7.5):
+
+| # | Check | Signal words / patterns to look for |
+|---|-------|--------------------------------------|
+| U1 | **Scope defined** | "applies to", "scope", "covers", "this policy/procedure applies", "all staff", "all systems" |
+| U2 | **Ownership assigned** | role name + "is responsible", "owner:", "maintained by", department name, job title |
+| U3 | **Process described** | numbered steps, "shall", "must", "procedure:", "how to", imperative verbs |
+| U4 | **Evidence/records** | "record", "log", "audit trail", "documented", "evidence of", "report" |
+| U5 | **Review trigger** | "reviewed annually", "reviewed every", "upon change", "review date", version table |
+
+Grade each: ✅ Present and specific / ⚠️ Mentioned but vague / ❌ Absent
+
+### Step 2c — Clause-Specific Signals
+
+After the universal checklist, derive clause-specific signals and check the doc body for each.
+
+**Signal source — use the first available:**
+1. **`Shall` column** in the reference file (if populated) — contains normative "shall" statements from the official ISO standard. Extract each distinct requirement as a check. This is the most accurate source.
+2. **Fallback** — derive 2–4 checks from the clause title + description + built-in ISO knowledge.
+
+> To populate the `Shall` column with official text: purchase the PDF from BSI ([bsigroup.com](https://www.bsigroup.com)) or ISO ([iso.org/store](https://www.iso.org/store)), extract with `/hd-docs-parse <pdf> --markdown`, then add the key "shall" statements to the reference file.
+
+**How to derive fallback signals** (when `Shall` column is empty):
+1. Read the clause title and description from the reference file
+2. Identify 2–4 concrete things that document MUST address for that clause
+3. Check the doc body for each
+
+**Examples** (to illustrate the pattern — apply the same logic to ALL clauses):
+
+```
+A.5.17 — Authentication Information
+  → check: password complexity rules present
+  → check: MFA or multi-factor authentication mentioned
+  → check: prohibition of shared accounts
+  → check: password recovery/reset process described
+
+A.5.24 — Information Security Incident Management
+  → check: incident classification or severity levels defined
+  → check: escalation path or contacts named
+  → check: response timeline or SLA stated
+  → check: post-incident review process mentioned
+
+A.8.13 — Information Backup
+  → check: backup frequency specified
+  → check: backup storage location described
+  → check: restoration test/verification process mentioned
+  → check: retention period stated
+
+8.3 (ISO 9001) — Design and Development
+  → check: design inputs defined
+  → check: design review steps included
+  → check: design verification/validation described
+  → check: design output requirements stated
+```
+
+Grade each clause-specific signal: ✅ Present and specific / ⚠️ Mentioned but vague / ❌ Absent
+
+### Step 2d — Clause Verdict
+
+For each clause, calculate:
+- Total checks = 5 universal + N clause-specific
+- Met = count of ✅
+- Partial = count of ⚠️ (counts as 0.5 in percentage)
+- Score = (Met + 0.5 × Partial) / Total
+
+| Score | Verdict |
+|-------|---------|
+| ≥ 80% | ✅ COMPLIANT |
+| 50–79% | ⚠️ PARTIAL |
+| < 50% | ❌ NON-COMPLIANT |
+
+Override to ❌ NON-COMPLIANT if ANY universal check (U1–U5) is ❌ Absent.
+
+---
+
+## Phase 3 — Per-Document Output
+
+Print a detailed report for each document:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📄 Password and Authentication Policy
+   Standard: ISO 27001 | Type: policy | Last sync: 2026-03-01
+   Source: https://docs.google.com/document/d/1abc...
+
+── Clause A.5.17 — Authentication Information ──────────────
+
+   Universal checks:
+   ✅ U1 Scope — "applies to all staff and system accounts" (line 4)
+   ✅ U2 Ownership — "IT Security team owns this policy" (line 7)
+   ⚠️ U3 Process — password complexity rules present but reset process vague
+   ❌ U4 Evidence — no mention of audit logs or compliance records
+   ✅ U5 Review — "reviewed annually each January" (line 45)
+
+   Clause-specific checks:
+   ✅ Password complexity — min 12 chars, mixed case, symbols required (line 12)
+   ⚠️ MFA — mentioned ("MFA is encouraged") but no specifics on when mandatory
+   ❌ Shared account prohibition — not mentioned
+   ❌ Password recovery process — not described
+
+   Verdict: ⚠️ PARTIAL (5.5/9 checks — 61%)
+   Key gaps: Evidence records, shared account prohibition, recovery process
+
+Overall Document Verdict: ⚠️ REVIEW NEEDED
+Recommendations:
+  1. Add compliance record/audit trail requirement (fixes U4 across all clauses)
+  2. Define when MFA is mandatory (A.5.17 specific)
+  3. Add explicit prohibition of shared accounts (A.5.17 specific)
+  4. Add password recovery/reset process with SLA (A.5.17 specific)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Document-level verdict** (aggregate of all clause verdicts):
+- 🟢 **COMPLIANT** — all clauses ✅ COMPLIANT
+- 🟡 **REVIEW NEEDED** — any clause ⚠️ PARTIAL, no clause ❌ NON-COMPLIANT
+- 🔴 **NON-COMPLIANT** — any clause ❌ NON-COMPLIANT
+
+---
+
+## Phase 4 — Summary Report
+
+After all documents are processed, print a summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+hd-iso-verify Summary — 2026-03-05
+Scope: ISO 27001 | Docs verified: 12
+
+Results:
+  🟢 COMPLIANT       4 docs
+  🟡 REVIEW NEEDED   6 docs
+  🔴 NON-COMPLIANT   2 docs
+
+Docs requiring immediate attention (🔴 NON-COMPLIANT):
+  1. docs/iso/incident-response.md
+     — A.5.24: missing response timeline, escalation path absent
+  2. docs/iso/backup-policy.md
+     — A.8.13: no restoration test procedure, retention period absent
+
+Top gaps across all 12 docs:
+  ❌ U4 Evidence/records     — missing in 8/12 docs
+  ❌ U5 Review trigger       — missing in 5/12 docs
+  ⚠️ U3 Process specificity  — vague in 6/12 docs
+
+Skipped (untagged):
+  3 docs have no clause tags — cannot verify. Run hd-iso-sync tagging step.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Report saved: reports/verify-27001-20260305.md
+```
+
+**Report filename**:
+- Single doc: `reports/verify-<doc-slug>-<YYYYMMDD>.md`
+- Clause scope: `reports/verify-clause-<id-slug>-<YYYYMMDD>.md`
+- Standard scope: `reports/verify-<standard>-<YYYYMMDD>.md`
+
+Create `reports/` directory if it doesn't exist.
+
+**After verification, always suggest next steps**:
+- Any 🔴 → "Fix in Google Docs, re-sync with `/hd-iso-sync`, then re-run."
+- Only 🟡 → "Use `/hd-iso change '<description>'` for a guided change checklist."
+- All 🟢 → "Run `/hd-iso gap --standard <std>` to check for coverage gaps."
+
+If reference file missing → "Ensure `hd-iso` skill is installed alongside `hd-iso-verify`."
+
+---
+
+## Relationship to Other ISO Skills
+
+```
+hd-iso-sync     — import docs from Google Drive → docs/iso/*.md
+hd-iso gap      — existence check: which clauses have NO documents?
+hd-iso-verify   — content check: do existing documents fulfill requirements?  ← this skill
+hd-iso change   — before editing: what clauses does a change affect?
+hd-iso onboard  — new employee reading path by role
+```
+
+Run order for a full compliance review:
+1. `/hd-iso-sync` — refresh MD layer
+2. `/hd-iso gap --standard 27001` — find missing docs (existence)
+3. `/hd-iso-verify --standard 27001` — audit existing docs (content quality)
+4. Fix gaps in Google Docs → re-sync → re-verify

package/resources/skills/hd-issue-resolution/SKILL.md

@@ -550,6 +550,26 @@ If a Linear task URL was provided at the start of this session:
 
 Skip this step if no task URL is in context, or if the task was already updated.
 
+## Known Issues Suggestion Hook
+
+After resolution, check if the fix involved accepting or deferring the underlying issue rather than fully resolving it.
+
+**Trigger signals** (in fix summary, root cause, or verification notes):
+- "workaround", "temporary fix", "partial fix", "deferred", "can't fix now", "won't fix"
+- "known limitation", "accepted", "acknowledged", "expected behavior"
+- "TODO", "FIXME", "tech debt", "legacy constraint"
+
+If any trigger signal is present and no matching KI entry exists in `docs/KNOWN_ISSUES.md`:
+
+```
+> This resolution appears to involve accepted/deferred debt: "<matched phrase>".
+> Add to docs/KNOWN_ISSUES.md as a known issue? (y/n)
+```
+
+On **yes**: append a new KI entry with auto-assigned next sequential ID, title from the issue summary, scope from affected files, today's date, and `<fill in>` placeholders for Reason, Accepted-by, and Target-fix. Display: `KI-NNN added — fill in the remaining fields.`
+
+On **no**: skip silently.
+
 ---
 
 ## Quick Reference

package/resources/skills/hd-task/SKILL.md

@@ -90,6 +90,9 @@ Parse the invocation arguments before any other action:
    - If description is missing, fewer than 50 characters, or lacks acceptance criteria: ask the developer for more context before proceeding.
 6. **Stale detection** — compare `task.updatedAt` to today's date.
    - If difference > `state_machine.stale_days` (default: 5) from `docs/tasks/config.yaml`: print `Warning: task last updated N days ago. Verify it is still current.` Continue without blocking.
+7. **Load Known Issues** — check for `docs/KNOWN_ISSUES.md` in the project root.
+   - If found: read and store as `KNOWN_ISSUES`. Pass as context to the routed skill in Phase 4 so it can factor in accepted debt when planning or debugging.
+   - If not found: `KNOWN_ISSUES` = none. Continue without blocking.
 
 ### Phase 2: Route
 
@@ -239,6 +242,15 @@ Skip if code review is not part of your team's workflow.
    ```
    <id> | <date> | <hitl-mode> | pending-review
    ```
+4. **Known Issues suggestion** — scan the session output (execution notes, routed skill output, PR description) for language indicating accepted or deferred debt:
+   - Trigger signals: "workaround", "known issue", "accepted", "deferred", "can't fix now", "TODO", "tech debt", "temporary fix", "acknowledged"
+   - For each match with no existing KI entry in `docs/KNOWN_ISSUES.md`:
+     ```
+     > This looks like accepted debt: "<matched phrase>".
+     > Add to docs/KNOWN_ISSUES.md as a known issue? (y/n)
+     ```
+   - On **yes**: append a new KI entry (auto-assign next KI-NNN, use today's date, leave Reason/Accepted-by/Target-fix as `<fill in>` placeholders). Display: `KI-NNN added — fill in the remaining fields.`
+   - On **no**: skip silently.
 
 ---