Note: The shokunin-update.ps1 script lives in .pack/scripts/ and is deployed to ~/.shokunin/scripts/ by the installer.
Shokunin Update System
Maintains the Shokunin ecosystem by detecting drift between the declarative manifest and the actual filesystem state.
Workflow
1. Load the manifest
Read ~/.shokunin/shokunin.json. This is the single source of truth. Every component, path, hash, and template is defined here.
2. Check status
Run shokunin-update.ps1 status to detect drift:
- OK: hash matches manifest
- MISSING: file doesn't exist but manifest expects it
- PROTECTED: data files (chroma_db, sessions) that must never be modified
Report results to the user with counts.
3. Plan changes
Run shokunin-update.ps1 plan to see what would change without applying anything.
Show the user a clear summary of what will be created, modified, or left alone.
4. Apply with confirmation
& "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" apply -Confirm
This automatically:
- Backs up each file to
~/.shokunin/backups/<timestamp>/
- Applies changes
- Saves update event to ChromaDB
- Runs
memory-healthcheck.ps1 to verify
5. Rollback if needed
& "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" rollback -Timestamp 20260514-120000
When to use this skill
- User notices something broken in the ecosystem
- User wants to add/remove/modify a component
- User asks "is everything up to date?"
- Pre-commit or pre-PR verification
Do NOT
- Modify files in
protected groups (chroma_db, sessions, logs, backups)
- Apply changes without user confirmation
- Edit the manifest without understanding every field
Error Handling
| Cause |
Fix |
| shokunin.json manifest is missing or malformed |
Validate JSON syntax with Test-Json. If missing, run installer ~/.shokunin/install.ps1 to regenerate from template. Report exact parse error line if malformed. |
| File hash mismatch but content is identical |
Encoding difference (CRLF vs LF) or trailing whitespace. Normalize line endings with .pack/scripts/normalize-eol.ps1 before re-checking. |
| Backup directory exceeds disk quota |
Old backups accumulate over time. Retention policy: keep last 5 backups. Purge older directories with Remove-Item -Recurse. |
| Protected file group modified by apply |
A bug or misconfiguration in the manifest marked a protected path as writable. Abort immediately. Rollback from backup. Fix manifest before retry. |
| Rollback target timestamp not found |
Backup was purged by retention policy or never created. Cannot recover that point in time. Run status to assess current state and manually fix drift. |
| Powershell execution policy blocks the script |
System execution policy set to Restricted |
| ChromaDB save during apply step fails |
MCP server is down or ChromaDB collection is locked |
Related Scripts
~/.shokunin/scripts/validate-skills.ps1 — Validates all installed skills for required sections, size, and referenced script existence~/.shokunin/scripts/shokunin-update.ps1 — Drift detection, manifest-driven update apply, rollback, and status reporting
Sources
- PowerShell 5.1 documentation (learn.microsoft.com/en-us/powershell/scripting) — execution policy, file hashing, and error handling
- ChromaDB Python client documentation (docs.trychroma.com) — collection management and persistence
- Semantic Versioning 2.0.0 (semver.org) — version comparison logic used in drift detection
- Git documentation on plumbing commands (git-scm.com/docs/git-hash-object) — content-addressable storage pattern inspiration
- "Infrastructure as Code" by Kief Morris (O'Reilly, 2nd Edition, 2020) — drift detection and reconciliation patterns
- NIST SP 800-88 Guidelines for Media Sanitization — secure file overwrite patterns used in backup rotation
Anti-Patterns
| Pattern |
Problem |
Fix |
Running apply without running plan first |
Changes are applied without user awareness of what will be modified |
Always run plan → show summary → get confirmation → then apply. |
| Modifying protected paths directly instead of through manifest |
Data loss: chroma_db, sessions, logs get overwritten and cannot be recovered |
Never touch paths under the protected group. If they need changes, update the manifest logic, not the files. |
| Hand-editing the manifest without understanding every field |
A typo in a path or hash field cascades into false drift positives or corrupted apply |
Use the declarative format. Every path must be absolute. Every hash must be SHA-256. Validate with Test-Json after edits. |
| Ignoring drift warnings for long periods |
Drift accumulates, making later applies riskier and harder to roll back |
Run status weekly. Schedule via Task Scheduler: shokunin-update.ps1 status > ~/.shokunin/logs/drift.log. |
| Restoring from backup without verifying backup integrity |
A corrupted backup restores corrupted files |
Before rollback, verify backup checksums against the original manifest hashes. Abort if mismatch. |
| Running apply while another apply is in progress |
Race condition on backup/restore directories causing incomplete state |
Use a lock file: ~/.shokunin/.apply-lock. If lock exists and process is alive, wait or abort. Stale lock (>30 min) can be removed. |
Checklist
1---2name: shokunin-update3description: Detect drift, plan updates, and apply changes to the Shokunin AI Ecosystem. Use this when user asks to update, fix, sync, or verify the ecosystem.4license: MIT5---678> **Note:** The `shokunin-update.ps1` script lives in `.pack/scripts/` and is deployed to `~/.shokunin/scripts/` by the installer.910# Shokunin Update System1112Maintains the Shokunin ecosystem by detecting drift between the declarative manifest and the actual filesystem state.1314## Workflow1516### 1. Load the manifest1718Read `~/.shokunin/shokunin.json`. This is the single source of truth. Every component, path, hash, and template is defined here.1920### 2. Check status2122Run `shokunin-update.ps1 status` to detect drift:2324- OK: hash matches manifest25- MISSING: file doesn't exist but manifest expects it26- PROTECTED: data files (chroma_db, sessions) that must never be modified2728Report results to the user with counts.2930### 3. Plan changes3132Run `shokunin-update.ps1 plan` to see what would change without applying anything.3334Show the user a clear summary of what will be created, modified, or left alone.3536### 4. Apply with confirmation3738```powershell39& "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" apply -Confirm40```4142This automatically:431. Backs up each file to `~/.shokunin/backups/<timestamp>/`442. Applies changes453. Saves update event to ChromaDB464. Runs `memory-healthcheck.ps1` to verify4748### 5. Rollback if needed4950```powershell51& "$env:USERPROFILE\.shokunin\scripts\shokunin-update.ps1" rollback -Timestamp 20260514-12000052```5354## When to use this skill5556- User notices something broken in the ecosystem57- User wants to add/remove/modify a component58- User asks "is everything up to date?"59- Pre-commit or pre-PR verification6061## Do NOT6263- Modify files in `protected` groups (chroma_db, sessions, logs, backups)64- Apply changes without user confirmation65- Edit the manifest without understanding every field6667## Error Handling6869| Cause | Fix |70|-------|-----|71| shokunin.json manifest is missing or malformed | Validate JSON syntax with `Test-Json`. If missing, run installer `~/.shokunin/install.ps1` to regenerate from template. Report exact parse error line if malformed. |72| File hash mismatch but content is identical | Encoding difference (CRLF vs LF) or trailing whitespace. Normalize line endings with `.pack/scripts/normalize-eol.ps1` before re-checking. |73| Backup directory exceeds disk quota | Old backups accumulate over time. Retention policy: keep last 5 backups. Purge older directories with `Remove-Item -Recurse`. |74| Protected file group modified by apply | A bug or misconfiguration in the manifest marked a protected path as writable. Abort immediately. Rollback from backup. Fix manifest before retry. |75| Rollback target timestamp not found | Backup was purged by retention policy or never created. Cannot recover that point in time. Run `status` to assess current state and manually fix drift. |76| Powershell execution policy blocks the script | System execution policy set to Restricted | Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` or invoke with `powershell -ExecutionPolicy Bypass -File script.ps1`. |77| ChromaDB save during apply step fails | MCP server is down or ChromaDB collection is locked | Apply still succeeded on the filesystem. Save the update event manually: `python ~/.shokunin/scripts/chroma-helper.py save "update applied" ...`. |7879## Related Scripts8081- `~/.shokunin/scripts/validate-skills.ps1` — Validates all installed skills for required sections, size, and referenced script existence82- `~/.shokunin/scripts/shokunin-update.ps1` — Drift detection, manifest-driven update apply, rollback, and status reporting8384## Sources8586- PowerShell 5.1 documentation (learn.microsoft.com/en-us/powershell/scripting) — execution policy, file hashing, and error handling87- ChromaDB Python client documentation (docs.trychroma.com) — collection management and persistence88- Semantic Versioning 2.0.0 (semver.org) — version comparison logic used in drift detection89- Git documentation on plumbing commands (git-scm.com/docs/git-hash-object) — content-addressable storage pattern inspiration90- "Infrastructure as Code" by Kief Morris (O'Reilly, 2nd Edition, 2020) — drift detection and reconciliation patterns91- NIST SP 800-88 Guidelines for Media Sanitization — secure file overwrite patterns used in backup rotation9293## Anti-Patterns9495| Pattern | Problem | Fix |96|---------|---------|-----|97| Running `apply` without running `plan` first | Changes are applied without user awareness of what will be modified | Always run `plan` → show summary → get confirmation → then `apply`. |98| Modifying protected paths directly instead of through manifest | Data loss: chroma_db, sessions, logs get overwritten and cannot be recovered | Never touch paths under the protected group. If they need changes, update the manifest logic, not the files. |99| Hand-editing the manifest without understanding every field | A typo in a path or hash field cascades into false drift positives or corrupted apply | Use the declarative format. Every path must be absolute. Every hash must be SHA-256. Validate with `Test-Json` after edits. |100| Ignoring drift warnings for long periods | Drift accumulates, making later applies riskier and harder to roll back | Run `status` weekly. Schedule via Task Scheduler: `shokunin-update.ps1 status > ~/.shokunin/logs/drift.log`. |101| Restoring from backup without verifying backup integrity | A corrupted backup restores corrupted files | Before rollback, verify backup checksums against the original manifest hashes. Abort if mismatch. |102| Running apply while another apply is in progress | Race condition on backup/restore directories causing incomplete state | Use a lock file: `~/.shokunin/.apply-lock`. If lock exists and process is alive, wait or abort. Stale lock (>30 min) can be removed. |103104## Checklist105106- [ ] Verify shokunin.json is valid JSON and all component paths resolve107- [ ] Run shokunin-update.ps1 status — 0 MISSING, no crashes108- [ ] Run shokunin-update.ps1 apply — all components sync without errors109- [ ] Verify MCP server starts: python ~/.shokunin/memory/mcp-server.py responds to tools/list110- [ ] Verify chroma-helper.py CLI works: python ~/.shokunin/scripts/chroma-helper.py count111- [ ] Verify all 62 skills present in .config/opencode/skills/112- [ ] Verify templates match installed files (no drift)113- [ ] Verify AGENTS.md version matches shokunin.json version114- [ ] Run memory-healthcheck.ps1 — all tests pass115- [ ] Run alidate-skills.ps1 — 0 failures
eliasoulkadi