ZAKON #14 — BookStack Auto-Sync Protocol

ZAKON #14 — BookStack Auto-Sync Protocol

Svaki docs/ fajl koji se kreira ili mijenja MORA biti syncan u BookStack.

Date: 2026-02-24 Origin: Documentation was being created in project docs/ dirs but never reaching BookStack — agents marked tasks done without syncing. Wiki drifted from codebase reality.

---

Rule

After ANY Write or Edit to a .md file inside a project's docs/ directory:

1. Check sync map — ~/system/config/bookstack-sync-map.json — is this file/project mapped?
2. If NOT mapped — add the file to the sync map first, then run sync
3. Run sync — node ~/system/tools/bookstack-sync.js
4. THEN mark task done — sync MUST complete before task is considered complete

---

Sync Map

Location: ~/system/config/bookstack-sync-map.json

Structure:

{
  "projects": {
    "<project-name>": {
      "shelf_id": 123,
      "docs_path": "~/ALAI/<path>/docs/",
      "book_id": 456
    }
  }
}

If a project doesn't have a BookStack shelf yet, create one before adding docs.

---

What Triggers This Rule

Condition	Sync Required?
New .md file created in docs/	YES
Existing .md file in docs/ modified	YES
.md outside docs/ (e.g. README.md, CLAUDE.md)	NO
Non-.md files (code, config, JSON)	NO
Temp files in /tmp/	NO
GOTCHA files	NO

MC task lifecycle — every task

File-sync scope above and task-lifecycle documentation are separate controls. For every real Mission Control task:

1. Link one canonical https://docs.alai.no/... page to tasks.bookstack_url.
2. Before work, add <!-- ALAI-MC:<id>:BEFORE -->; mc.js start/resume must verify it by API.
3. After work, update the same page and add <!-- ALAI-MC:<id>:AFTER -->.
4. mc.js ready/done verifies the AFTER marker and requires API updated_at newer than the baseline captured before work.
5. API failure is UNKNOWN/BLOCKED. A URL in outcome text and --force are not proof.

---

Agent Checklist

When an agent task involves documentation:

[ ] Wrote/edited .md files in docs/
[ ] Checked bookstack-sync-map.json for this project
[ ] Added new files to sync map (if needed)
[ ] Ran: node ~/system/tools/bookstack-sync.js
[ ] Confirmed sync output shows no errors
[ ] THEN: marked MC task as done

---

Anti-Patterns (NEVER do these)

1. "Dokumentacija je gotova" without running sync — wiki doesn't know that
2. Skipping sync because "it's just a draft" — drafts belong in BookStack too
3. Adding files to sync map without a valid shelf/book ID — verify IDs first
4. Running sync and ignoring errors — fix errors before marking done

---

Enforcement

• Rule: This document (behavioral standard)
• Scope: All agents that create or modify docs/ content
• Config: ~/system/config/bookstack-sync-map.json
• Tool: node ~/system/tools/bookstack-sync.js
• Hook: Post-tool hook watches for Write/Edit on */docs/*.md paths and emits reminder

---

Ljestvica (ZAKON #1)

This is a RULE + TOOL fix (2 layers):

• Rule: This document (behavioral standard)
• Tool: bookstack-sync.js (deterministic sync execution)