Skip to content

AGENTS.md

Latest commit

 

History

History
210 lines (187 loc) · 90.6 KB

AGENTS.md

File metadata and controls

210 lines (187 loc) · 90.6 KB
Raw

Agent / assistant notes (Cursor, Copilot, etc.)

Complete issue and PR threads

Before implementing, committing, closing, or declaring work complete: read the full GitHub issue body and every paginated comment to the end. For PR-driven work, also read the complete PR conversation, reviews, and inline review findings. Do not rely on the title, a summary, or the first page of comments. Do not close an issue or PR solely from a title, summary, or first page.

This is a runtime rule in this file (GitHub #1953). It does not by itself complete the org-wide epic; other maintained DataBoar repositories keep their own root AGENTS.md.

Quick index (find the policy first)

Use this table to jump to the canonical bullet or rule for each theme. Details stay in the bullets below and in linked files — this section is a map only (consolidation phase A). The same map with clickable paths is in docs/ops/CURSOR_AGENT_POLICY_HUB.md (pt-BR) (consolidation phase B). Fresh chat / low context / token-aware: read docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md (pt-BR) first — ordered ladder + task router + seven non-negotiables (homelab ssh reachability = §7), then this table.

Theme Where to look first
Complete issue and PR threads — full body, all comments, PR reviews + inline findings before implement/commit/close This file, section Complete issue and PR threads (GitHub #1953)
Cold start (fresh agent, token-aware) — ladder + task router before deep-reading this file docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md · hub map: docs/hubs/INDEX.md
Ops docs index / guidelines / shorthands docs/hubs/OPS_HUB.md · docs/hubs/GUIDELINES_AND_GUARDRAILS_HUB.md · docs/hubs/SHORTHANDS_HUB.md
Ecosystem map (bestiary, private repos, vault CHIRP) — off-band onboarding; Cursor = executor on data-boar only docs/ops/CURSOR_ECOSYSTEM_ONBOARDING.md · vault ~/Projects/dev/obsidian-vault/databoar-commercial/_NORTE_mapa-do-todo-e-sequencia.md (operator-local)
.cursor/ / .vscode/ / .github/ / caches — tracked vs gitignored docs/ops/CURSOR_AND_EDITOR_ARTIFACTS.md
Cursor rules — phase 2 situationalization (Tier A/B/C, reproducible ritual) docs/ops/CURSOR_RULES_PHASE2_SITUATIONALIZATION.md (pt-BR)
docs/private/ read access / never self-block .cursor/rules/agent-docs-private-read-access.mdc (always-on) · situational docs-private-workspace-context.mdc ( private-stack-sync or @docs-private-workspace-context.mdc ) · First bullet below · docs/PRIVATE_OPERATOR_NOTES.md · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (private-stack-sync)
Chat pt-BR / locale (private drafts = pt-BR; EN-only prose → en-US) docs-locale-pt-br-contract.mdc (always) · operator-chat-language*.mdc · docs-pt-br-locale.mdc · .cursor/skills/operator-dialogue-pt-br/SKILL.md · .cursor/skills/documentation-en-pt-br/SKILL.md
Session keywords (deps, feature, es-find, …) .cursor/rules/session-mode-keywords.mdc
Windows filename search (Everything / es-find) everything-es-cli.mdc (situational — es-find or @everything-es-cli.mdc) · windows-pcloud-drive-search-discipline.mdc (always-on for P:) · docs/ops/EVERYTHING_ES_PRIMARY_WINDOWS_DEV_LAB.md · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (es-find) — Windows-only; on Linux primary use find, fd, locate/plocate (plocate 1.1.23 on the Linux primary), git grep, grep -r
Primary dev workstation protection (primary Linux dev workstation, temporary) docs/ops/PRIMARY_LINUX_WORKSTATION_PROTECTION.md (+ .pt_BR.md) · .cursor/rules/primary-linux-workstation-protected-no-destructive-repo-ops.mdc (always-on) · ADR 0068 · ./scripts/check-all.sh before PR · uv run pre-commit install once per clone
Plans — PLANS_TODO / PLAN_* drift + archive plans-status-pl-sync.mdc · plans-archive-on-completion.mdc (both situational — plan globs or @…; docs / feature / houseclean / backlog) · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (plans — status sync) + § (plans — archive)
SonarQube MCP (Cursor tools) sonarqube_mcp_instructions.mdc (situational — sonar-mcp or @sonarqube_mcp_instructions.mdc) · docs/ops/SONARQUBE_HOME_LAB.md · quality-sonarqube-codeql.mdc · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (sonar-mcp)
Study cadence (calendar vs deep code) study-cadence-reminders.mdc (situational — study-check or @study-cadence-reminders.mdc) · docs/plans/PORTFOLIO_AND_EVIDENCE_SOURCES.md §3 · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (study-check)
Agreed scripts / wrapper ritual (hub + scripts/*.ps1 before long ad-hoc shell) .cursor/rules/repo-scripts-wrapper-ritual.mdc · docs/ops/TOKEN_AWARE_SCRIPTS_HUB.md · check-all-gate.mdc · .cursor/skills/token-aware-automation/SKILL.md
Vendor web LLMs vs validated orchestration / as-is scripts docs/ops/LLM_AGENT_EDITING_CAUTION.md (pt-BR) · full evidence index under docs/private/ops/ (gitignored from GitHub)
PII / secrets / public tree private-pii-never-public.mdc · docs/ops/PII_PUBLIC_TREE_OPERATOR_GUIDE.md · docs/ops/PII_REMEDIATION_RITUAL.md · pii-remediation-ritual / pii-fresh-audit
Never weaken a security gate (hard rule) .cursor/rules/never-weaken-security-gates.mdc (always-on) · ADR 0071 · .github/CODEOWNERS · security/pii_gate_allowlist.txt · docs/plans/PLAN_PII_GATE_INTEGRITY.md
Private legal / labour dossier (gitignored evidence) dossier-update-on-evidence.mdc · session legal-dossier-update · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (legal dossier)
Commercial / confidential confidential-commercial-never-tracked.mdc
GitHub / PR / merge advice git-pr-sync-before-advice.mdc · CONTRIBUTING.md (PR state) · docs/ops/COMMIT_AND_PR.md
Release publish order (tag + GitHub + Hub before beta on main) release-publish-sequencing.mdc (situational — release-ritual or @release-publish-sequencing.mdc or release-doc globs) · docker-local-smoke-cleanup.mdc (always-on) · docs/VERSIONING.md (Assistant / automation) · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (release-ritual)
Release & versioning guardrails (commit gate ≠ release gate; #970/#772 class) docs/VERSIONING.md · ADR-0072 / ADR-0073 (Accepted) · security/version_policy.yaml · tests/test_release_version_policy.py · .cursor/rules/release-versioning.mdc (situational)
Docker Desktop smoke + disk + prune (before Hub push; avoid tag sprawl) docker-local-smoke-cleanup.mdc · .cursor/skills/docker-smoke-container-hygiene/SKILL.md · scripts/docker/README.md · docs/ops/DOCKER_IMAGE_RELEASE_ORDER.md
Outbound HTTP User-Agent + README executive pitch boundaries ADR 0034 (DataBoar-Prospector/<version> on discovery connectors; override via target headers) · ADR 0035 (stakeholder README block vs optional Data Sniffing / Deep Boring deck labels in COMPLIANCE_FRAMEWORKS / glossary) · tests/test_about_version_matches_pyproject.py, tests/test_connector_timeouts.py, tests/test_readme_stakeholder_pitch_contract.py
Investigation / recovery (“figure it out”) operator-investigation-before-blocking.mdc · .cursor/private/skills/operator-recovery-investigation/SKILL.md
Cursor browser / SSO / tabs (todas as redes do operador + Gmail + Docker Hub + UI web; mesmo eixo que SSH no PC dev) cursor-browser-social-sso-hygiene.mdc (Contrato único) · operator-browser-warm-session.mdc · operator-direct-execution.mdc §5 · .cursor/skills/cursor-browser-social-session/SKILL.md
Homelab / SSH / LAN — integrated terminal = same dev PC + LAN as your shell; read AGENT_LAB_ACCESS.md before claiming unreachable (cold-start §7) homelab-ssh-via-terminal.mdc (situational — session homelab or @homelab-ssh-via-terminal.mdc) · docs/private/homelab/AGENT_LAB_ACCESS.md (when present) · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Seven non-negotiables + § Token → rule latch (homelab)
Lab completão (SSH orchestrate from dev PC, -Privileged) lab-completao-workflow.mdc (Narrow sudoers baseline — sudo -n + fixed script paths vs visudo; assume LAB/WSL deployed unless logs prove otherwise) · docs/ops/LAB_COMPLETAO_RUNBOOK.md · docs/ops/COMPLETAO_OPERATOR_PROMPT_LIBRARY.md (completao + tier: · scripts/completao-chat-starter.ps1) · session keyword completao · First-message latch: docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule → wrapper latch — never destructive Git on the primary dev workstation canonical clone (primary Linux dev workstation today — PRIMARY_LINUX_WORKSTATION_PROTECTION.md); LAB manifest hosts + Docker Hub images are safe to align / re-pull
Lab lessons (public archive + hub) Session lab-lessons · lab-lessons-learned-archive.mdc (situational) · docs/ops/LAB_LESSONS_LEARNED.md · docs/ops/lab_lessons_learned/ · ADR 0042 · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (lab-lessons)
Autonomous merge / LAB-OP agent-autonomous-merge-and-lab-ops.mdc
Assistant session ritual (synced main, private stack, next steps) AGENTS.md (Assistant session ritual) · .cursor/rules/agent-session-ritual-sync-main-and-private-stack.mdc · docs/ops/PRIVATE_STACK_SYNC_RITUAL.md
Situational “today” (workstation clock, today-mode file anchor) AGENTS.md (Workstation calendar clock) · docs/ops/today-mode/README.md (For assistants) · .cursor/rules/agent-session-ritual-sync-main-and-private-stack.mdc
Execution priority / PR batching execution-priority-and-pr-batching.mdc · docs/plans/PLANS_TODO.md
Operator career / LinkedIn layout (private) operator-career-private-layout.mdc · docs/private/author_info/career/README.pt_BR.md
Private stacked git docs/ops/PRIVATE_LOCAL_VERSIONING.md · mini-plan docs/private/ops/CURSOR_CONSOLIDATION_MINI_PLAN.pt_BR.md
Risk / non-destructive vs destructive Risk posture bullet below — do not fear harmless actions; pause and ask when destructive ops are doubtful
Direct execution (clear “ship it” requests — avoid redundant confirmation) .cursor/rules/operator-direct-execution.mdc
Private history / evidence mirrors (no “should I also backup?” when align or sync is obvious) .cursor/rules/operator-evidence-backup-no-rhetorical-asks.mdc · ADR 0040 · docs/ops/PRIVATE_STACK_SYNC_RITUAL.md
Publication truthfulness (no invented dates/facts; capture permalinks when reachable) .cursor/rules/publication-truthfulness-no-invented-facts.mdc · docs/private/social_drafts/editorial/SOCIAL_HUB.md (Política de data + inventário)
Agent roles (AI executor × auditor) .cursor/rules/agent-roles-executor-vs-auditor.mdc · CLAUDE.md (Claude Code cold-start pointer). Cursor = executor; Claude Code = read-only auditor (issues + prompts only, never direct writes). Complements human axis: collaboration-maintainer-contributor.mdc.
  • Risk posture — non-destructive vs destructive: Do not shy away from non-destructive actions that fit these notes (read/list tools, searches, tests, doc edits, additive scripts). Respect destructive or high-blast-radius work even when it looks “reversible”: e.g. git reset --hard, history rewrite / filter-repo, force-push, mass deletes, DB drops, clean-slate on the canonical clone — assess impact and rollback before running. If in doubt whether the operator wants the next step, stop and ask, explaining clearly why (what could break, what rollback exists, regression risk). “Reversible in theory” ≠ always safe in practice.
  • docs/private/ — agent access (non-negotiable): The assistant is always expected to use read_file (or equivalent workspace tools) on any path under docs/private/ that exists on disk in this workspace—including security_audit/, commercial/, legal_dossier/, homelab/, author_info/, gemini_bundles/, and any other subtree. .gitignore excludes these paths from Git/GitHub only; it is not a policy that hides files from the agent. Do not tell the operator that private content is “inaccessible because gitignored,” and do not ask them to paste private text or rely on @ / / context to “grant” access. Never self-block: do not refuse or defer work that needs private context; do not answer from generics alone when private files hold the truth—read first, then redact only for public/collaborator-facing tracked output per audience-segmentation-docs. Private content is never committed to GitHub origin; it may be versioned in the stacked private repo under docs/private/ (see docs/ops/PRIVATE_LOCAL_VERSIONING.md). If read_file fails, report a technical reason only—then retry with an absolute path or list_dir. See docs/PRIVATE_OPERATOR_NOTES.md §1 and .cursor/rules/agent-docs-private-read-access.mdc.
  • Chat language (operator preference): Default to concise Brazilian Portuguese (pt-BR) for explanations in chat—not European Portuguese (pt-PT). Always-on locale contract: .cursor/rules/docs-locale-pt-br-contract.mdc — assistants must not default to pt-PT in tracked *.pt_BR.md, private Portuguese Markdown, chat, or suggested PT prose; exceptions only as listed there (EN jargon, deliberate quote/humor, or operator-requested regional variant). Vocabulary examples: arquivo (not ficheiro), compartilhar (not partilhar), padrão for “default” in IT (not defeito). Reduces cognitive load. Scope (Portuguese prose): the same pt-BR bar applies to all Portuguese narrative the assistant writes or edits—including gitignored docs/private/ (e.g. social_drafts/, runbooks, notes), not only tracked *.pt_BR.md. English-only copy (explicitly EN titles, EN-only docs, or the operator asks for English): use American English (en-US) as the style reference for prose—keep UK spellings out unless quoting a third party. Tracked docs: after editing *.pt_BR.md, run uv run pytest tests/test_docs_pt_br_locale.py -v (see .cursor/rules/docs-pt-br-locale.mdc). Chat in Portuguese: same pt-BR bar — .cursor/skills/operator-dialogue-pt-br/SKILL.md (optional invoke); rule operator-chat-language-pt-br.mdc is always on. If the operator asks for English in a thread (e.g. to avoid mixed Portuguese variants), use English there until they switch back. Keep English for repo paths, Conventional Commits (feat:, fix(api):, …), code/API/CLI identifiers, .mdc rule names, and technical terms that stay EN in this repo. The operator may code-switch (pt-BR ↔ EN) in the same thread—mirror that flexibly; do not duplicate the same answer fully in both languages unless asked. Token-aware: prefer short bullets; if they say short / token-aware, minimize prose. See .cursor/rules/operator-chat-language.mdc and docs/PRIVATE_OPERATOR_NOTES.md §5.1.
  • Session taxonomy (English tokens only): Invoke cues exactly as written (same order and set as .cursor/rules/session-mode-keywords.mdc): deps, feature, homelab, external-eval, completao, lab-lessons, docs, houseclean, backlog, pmo-view, study-check, sidequest (same message must include subtype mandatory, exploratory, or pauseable), glossary-check, feedback-inbox, today-mode (with date YYYY-MM-DD), carryover-sweep, morning-readiness, eod-sync, block-close, private-stack-sync, safe-commit, pii-fresh-audit, pii-remediation-ritual, legal-dossier-update, es-find, x-pace-check, x-posted, social-today-check, sonar-mcp, release-ritual, plus brevity short / token-aware. pii-remediation-ritual = on-demand HEAD + private seeds pass per docs/ops/PII_REMEDIATION_RITUAL.md (judgment-triggered ritual, not a substitute for the full cadence in PII_PUBLIC_TREE_OPERATOR_GUIDE.md). Do not add Portuguese aliases for tokens in rules or tracked docs—narration around them may be pt-BR. carryover-sweep = start-of-day Tier A readiness + today-mode / carryover sweep (scripts/operator-day-ritual.ps1 -Mode Morning, docs/ops/today-mode/README.md Morning readiness); morning-readiness = same intent as step (1) of carryover-sweep (alias); eod-sync = end-of-day git/PR/main ritual (not OS sleep); block-close = work-block or lab-exit boundary (VC / carryover / optional private stack — not the full EOD script); private-stack-sync = stacked private repo close (scripts/private-git-sync.ps1, docs/ops/PRIVATE_STACK_SYNC_RITUAL.md); safe-commit = read-only snapshot (git status, optional nested docs/private, optional quick guard tests) before Preview — does not replace check-all. release-ritual = re-read .cursor/rules/release-publish-sequencing.mdc and docs/VERSIONING.md before shipping a public semver (tag vX.Y.Z, GitHub Release, Docker image push, then paste entire Hub Short + Full from docs/ops/DOCKER_HUB_REPOSITORY_DESCRIPTION.md — stable only; Hub does not sync from Git — before moving main to -beta). feedback-inbox = triage external reviews from gitignored docs/feedbacks, reviews, comments and criticism/ (WRB-style); ask operator for source if unclear. x-pace-check / x-posted = X editorial pace reminder + post-publish validation (docs/private/social_drafts/, scripts/social-x-pace-remind.ps1). completao = lab smoke orchestration from the dev PC (scripts/lab-completao-orchestrate.ps1 -Privileged, repo wrappers, LAB_OP_PRIVILEGED_COLLECTION.md / private sudoers template; lab-completao-workflow.mdc) — protect primary Windows dev PC (L-series role, PRIMARY_WINDOWS_WORKSTATION_PROTECTION.md); resync other lab hosts / Docker images as needed; no redundant “may I SSH?” prompts (operator-direct-execution.mdc); validate documented capabilities vs code (LAB_COMPLETAO_RUNBOOK.md); encode repeatable steps via scripts/ / Ansible / manifest (TOKEN_AWARE_SCRIPTS_HUB.md); record in private session notes timeouts, latency, FP/FN vs synthetic truth, confidence on real paths. Container-only lab hosts (manifest completaoEngineMode: container or completaoSkipEngineImport: true) run Data Boar via Docker / Swarm / Podman only — do not default to “install uv on bare metal” when the operator’s posture is stack/HTTP-based (LAB_COMPLETAO_RUNBOOK.md Container-only lab hosts). Inventory preflight: lab-completao-inventory-preflight.ps1 (default 15-day check on private LAB_SOFTWARE_INVENTORY.md / OPERATOR_SYSTEM_MAP.md, lab-op-sync-and-collect.ps1 when stale) runs inside lab-completao-orchestrate.ps1 unless -SkipInventoryPreflight — LAB_COMPLETAO_RUNBOOK.md Inventory freshness.
  • lab-lessons: Public lab lessons archive ritual (dated files under docs/ops/lab_lessons_learned/, rolling hub docs/ops/LAB_LESSONS_LEARNED.md, situational lab-lessons-learned-archive.mdc) per ADR 0042 — docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (lab-lessons). Promote actionable gaps into docs/plans/PLANS_TODO.md and run python scripts/plans-stats.py --write when dashboard rows change. Pair private docs/private/homelab/COMPLETAO_SESSION_*.md with number-only references in tracked text—no LAN secrets in public archives.
  • legal-dossier-update: Private legal/labour evidence under docs/private/legal_dossier/ or raw_pastes/ — follow dossier-update-on-evidence.mdc and docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (legal dossier); never name parties or docket numbers in tracked files.
  • Taxonomy discipline: Prefer backlog + a named item, feature + a PLANS_TODO.md row, completao for lab orchestration smoke, lab-lessons when closing a dated public lessons + plan-bridge slice, or docs instead of inventing many new English chat tokens. Any new keyword belongs only in .cursor/rules/session-mode-keywords.mdc with a single clear scope—see docs/ops/OPERATOR_WORKFLOW_PACE_AND_FOCUS.md §3.
  • Session keywords ≠ application CLI: The tokens above set Cursor chat scope for the assistant. The Data Boar command line is main.py (and related entrypoints) with flags documented in docs/USAGE.md; drift guardrails in docs/OPERATOR_HELP_AUDIT.md / operator-help-sync.mdc. Do not treat session tokens as argparse flags or vice versa.
  • No secrets or home infra in tracked files: Do not put real hostnames, RFC1918 LAN IPs, hardware serials, $HOME / C:\Users\... paths, or live credentials into committed Markdown, .mdc rules, or code comments. Use placeholders; the operator keeps specifics under gitignored docs/private/ per docs/PRIVATE_OPERATOR_NOTES.md. Same for raw last / lastlog / w / uptime dumps (habit + IP trail)—docs/private/homelab/ only if persisted. Do not paste secrets in chat — use session env vars / vault CLI / gitignored .env patterns; see docs/private.example/homelab/CREDENTIALS_AND_LAB_SECRETS.md.
  • Publication truthfulness (no invented dates or facts): Do not invent dates, URLs, publish status, or metrics for GitHub, sites, or social — in chat or in committed files. Verify via API/tool/git/HTTP or use facts the operator stated in-session. After publishing via WordPress (or similar) API, align local draft filename prefix and hub permalinks to the response (link, date). After cross-posts (Jetpack, native shares), record real permalinks per network in SOCIAL_HUB.md when reachable (curl, browser MCP, gh, etc.) — see Permalinks in the rule. Full rule: .cursor/rules/publication-truthfulness-no-invented-facts.mdc; operator hub: docs/private/social_drafts/editorial/SOCIAL_HUB.md.
  • Workstation calendar clock (today-mode and “what day is it”): Do not treat IDE/chat “Today’s date” metadata as the sole source of truth — it can be stale vs the operator’s real session. When anchoring docs/ops/today-mode/OPERATOR_TODAY_MODE_YYYY-MM-DD.md, dated social filenames, or any reasoning that depends on calendar day, run a clock command on the same machine as the workspace (integrated terminal): PowerShell Get-Date -Format "yyyy-MM-dd" (full offset: Get-Date -Format "o"), or cmd date /t / time /t. Use that YYYY-MM-DD for the today-mode filename unless the operator states otherwise. Guarantee in the sense of process: re-check when the session is long or the date could have rolled over. See docs/ops/today-mode/README.md (For assistants).
  • Commercial / client confidentiality: Pricing studies, client-specific proposals, strategic market drafts, and similar material that could help competitors belong only under gitignored docs/private/ (e.g. docs/private/commercial/). Operator OPEX (utilities, tools, shopping lists) → docs/private/operator_economics/. Do not commit or git add -f them. CI and pre-commit run tests/test_confidential_commercial_guard.py. Rule .cursor/rules/confidential-commercial-never-tracked.mdc · skill .cursor/skills/confidential-commercial-layout/SKILL.md.
  • Public Git narratives (commits, PRs, tracked examples): Do not embed third-party identifiers (talent-pool aliases, LinkedIn slugs, client or legal-case breadcrumbs) in commit messages, PR descriptions, or public scripts/skills beyond generic placeholders. Real mappings stay in gitignored docs/private/commercial/ (e.g. talent_pool.json). CI guards include tests/test_pii_guard.py, tests/test_talent_ps1_tracked_no_inline_pool.py, tests/test_talent_public_script_placeholders.py on tracked files; they do not rewrite old history—see docs/ops/PII_PUBLIC_TREE_OPERATOR_GUIDE.md for audits (Parts I–III; legacy paths under docs/ops/ redirect). Contributor policy: CONTRIBUTING.md → Public repo: third-party identifiers and Git history; PR flow: docs/ops/COMMIT_AND_PR.md → Commit and PR text: no sensitive third-party narratives.
  • Never weaken a security gate (hard rule): When a security gate fires — PII seed gate (gatekeeper_audit.py / gatekeeper-audit.ps1), pii_history_guard.py, secret scanners, CODEOWNERS, signed-commit / ADR-attestation checks — NEVER weaken, disable, loosen (-i, drop -w/\b, shorten a seed), bypass (--no-verify, skip a hook), or edit the audited file just to dodge it. Gate fired → STOP and escalate to the operator. The only sanctioned responses to a false positive are (1) tighten the pattern structurally (word-boundary, distinctive full-string seeds — never less sensitive) and (2) an operator-approved, per-location allowlist (security/pii_gate_allowlist.txt, CODEOWNERS-protected) — never FP-handling in matcher logic. The gate is self-protected: gate files are .github/CODEOWNERS-owned by the operator and a CI tripwire (scripts/gate_change_tripwire.py) fails LOUD if a PR touches a gate file without an operator marker. Full rule: .cursor/rules/never-weaken-security-gates.mdc (always-on) · ADR 0071 · docs/plans/PLAN_PII_GATE_INTEGRITY.md · issue #944.
  • Agents never fill Gate-Change-Approved-By:: That trailer is operator-only (HITL). Typing the operator handle into a commit or PR comment is theatre, not approval — incident class #1707 / #1709. Valid approval is trailer + file-namespace SSHSIG verified by scripts/gate_trailer_attest.py. On PRs, that signature covers trailer + PR number + head SHA (not the trailer line alone). CI: operator-gated-pr-guard.yml (pull_request_target, checkout of the default-branch tree only — never PR HEAD) and the tripwire on GATE_FILES. Do not merge gated PRs by stuffing the trailer.
  • PII self-audit vs clean-slate (do not simulate): The clean-slate.sh flow is a real destructive re-clone + guards on disk (Linux lab: install from docs/private.example/scripts/clean-slate.sh.example → docs/private/scripts/clean-slate.sh). On Windows, scripts/pii-fresh-clone-audit.ps1 (or manual empty-dir git clone + same guards) is the equivalent fresh-tree check; session keyword pii-fresh-audit. Use it to validate that improvements match intent on a fresh tree — not as a substitute for git filter-repo. Quick start: docs/ops/PII_FRESH_CLONE_AUDIT.md; canonical prose: docs/ops/PII_PUBLIC_TREE_OPERATOR_GUIDE.md §H.9–H.10; rule .cursor/rules/clean-slate-pii-self-audit.mdc; skill .cursor/skills/pii-fresh-clone-audit/SKILL.md. Assistants: run the actual guard commands in the integrated terminal when asked; do not claim clean-slate ran without a real clone/reset.
  • Primary dev workstation (never destructive repo ops on the canonical clone): Today (temporary): primary Linux dev workstation (LMDE 7) — Lenovo repair E0482B2DMD after Windows primary failed 2026-06-07 — see docs/ops/PRIMARY_LINUX_WORKSTATION_PROTECTION.md, .cursor/rules/primary-linux-workstation-protected-no-destructive-repo-ops.mdc, ADR 0068. DATA_BOAR_ROOT (placeholder path in public docs — operator default under ~/Projects/.../data-boar). When Windows primary returns: resume docs/ops/PRIMARY_WINDOWS_WORKSTATION_PROTECTION.md + .cursor/rules/primary-windows-workstation-protected-no-destructive-repo-ops.mdc. On any primary: no clean-slate-class resets, git filter-repo, git reset --hard / git clean -fdx, or run-pii-history-rewrite.ps1 without opt-in. Temp-only audits: /tmp/ on Linux; %TEMP% on Windows. Quality ritual on the Linux primary dev workstation: uv run pre-commit install once per clone; ./scripts/check-all.sh green before every PR. Filename search: es-find / es.exe = Windows-only (everything-es-cli.mdc, docs/ops/EVERYTHING_ES_PRIMARY_WINDOWS_DEV_LAB.md). Linux (Linux primary + lab-op SSH): find, fd, locate/plocate (plocate 1.1.23 on the Linux primary), git grep, grep -r — not es-find.ps1.
  • Cursor embedded browser (all operator social, Patreon, Docker Hub, Gmail / webmail, research): Same workstation contract as homelab SSH — try cursor-ide-browser first; do not claim “no access” because there is no public API. On any site that offers Google / SSO and the operator uses that identity: must attempt Continue with Google / Sign in with Google when the session is cold and the button exists — before asking the operator to intervene. Only after a failed attempt (captcha, hard MFA, broken tree, timeout), one clear ping so the operator can click once and restore a warm tab. Do not ask for passwords in chat. Gmail often stays warm; other networks may not — the SSO click attempt still applies. Do not paste full email bodies or sensitive attachments into tracked files or long chat; prefer docs/private/ + read_file for PDF review. Redundant “may I use the browser?” pings are operator toil (cursor-browser-social-sso-hygiene.mdc Contrato único + § Gmail e webmail, operator-browser-warm-session.mdc, operator-direct-execution.mdc §5). After the task, close unneeded tabs via browser_tabs → close unless the operator asks to keep a session open. Skill: .cursor/skills/cursor-browser-social-session/SKILL.md. Session persistence across Cursor restarts is not guaranteed.
  • LinkedIn / FacColleague-Sok / X / Threads / Instagram / social (operator-authorized, no “no access” excuses): Covered by the single browser contract above — all listed networks: try MCP navigation + snapshot first; cold → try Google SSO click before escalating. Do not claim the assistant “cannot access” because there is no public API. SOCIAL_HUB / published-post validation (e.g. Instagram IG1, Threads → docs/private/social_drafts/editorial/SOCIAL_HUB.md, shortcut docs/private/social_drafts/SOCIAL_HUB.md): try public profile or post URL before “I cannot see your feed.” Rule: .cursor/rules/cursor-browser-social-sso-hygiene.mdc. PDF export + operator-linkedin-profile-extract.ps1 remains a complement for long text diff, not a substitute for live browser when authorized. Talent-pool ATS/SLI refresh: same. Private: docs/private/commercial/ats_sli_hub/LIVE_LINKEDIN_REFRESH_POLICY.pt_BR.md.
  • Investigation before blocking (SRE-style recovery): When the operator asks to figure it out, recover something, or RCA a mishap, do not substitute panic, defensive refusals, or “no chat memory” for local work. Try in order (as fits): docs/ops/TOKEN_AWARE_SCRIPTS_HUB.md + .cursor/rules/repo-scripts-wrapper-ritual.mdc (agreed scripts/*.ps1 / *.sh for the situation — not only es-find); list/read_file under docs/private/ (including author_info/, legal_dossier/, team_info/), git -C docs/private log on the stacked private repo, git log -S / --all on the public tree, filename search on Windows (scripts/es-find.ps1, session keyword es-find, situational everything-es-cli.mdc) or on Linux primary / lab-op (find, fd, locate/plocate, git grep, grep -r), LinkedIn PDF export + operator-linkedin-profile-extract.ps1, then MCP browser if needed. Blameless tone: facts and hypotheses; escalate with a short list of what was tried, not empty “impossible.” Rule: .cursor/rules/operator-investigation-before-blocking.mdc · skill: .cursor/private/skills/operator-recovery-investigation/SKILL.md.
  • Homelab access (operator LAN): From the Cursor integrated terminal on the dev workstation, use ssh / scp / sftp, curl (HTTP/API), etc., when relevant. Same PC + LAN as your shell — not a cloud hop; changing IDE does not revoke SSH keys or LAN access. Privileged steps on a lab host: non-interactive sudo often fails from a separate ssh session vs sudo -v in tmux (TTY); use ssh -tt for a password prompt, Ansible become, or you run the exact command on the host — see .cursor/rules/homelab-ssh-via-terminal.mdc (situational — session homelab or @homelab-ssh-via-terminal.mdc in fresh threads; completao still uses lab-completao-workflow.mdc first — see docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (homelab)). docs/private/ is workspace-only (gitignored from GitHub)—proactively read_file docs/private/homelab/AGENT_LAB_ACCESS.md, docs/private/homelab/OPERATOR_SYSTEM_MAP.md (hardware + access + software chart), docs/private/homelab/LAB_SOFTWARE_INVENTORY.md (cross-host runtimes), docs/private/homelab/OPERATOR_RETEACH.md (structure templates: docs/private.example/homelab/OPERATOR_RETEACH.md + .pt_BR.md); @ / open tab not required once the rule is in context. Never copy those specifics into committed files. See docs/PRIVATE_OPERATOR_NOTES.md §4–§5 and .cursor/rules/homelab-ssh-via-terminal.mdc.
  • Windows pCloud drive P: or VeraCrypt Z: (operator default): On the same machine as Cursor, the assistant may list and read paths under P:\... (pCloud client default mount) or Z:\... when the operator uses VeraCrypt to mount the encrypted volume there (Y:\... only if you intentionally remap the drive letter). Use Test-Path / dir to see which letter is live. Same rules as before: never commit real absolute paths—docs/private/ or chat only. If P: and the VeraCrypt letter you need (Z: by default) are both absent, the volume or sync client is likely offline. Filename discovery on large P:\... trees: default = .\scripts\es-find.ps1 -SearchRoot ... -MaxCount N ( es.exe / wrappers that call it) — unchanged; do not treat Get-ChildItem as an equal default. Get-ChildItem is recovery if es fails: tell the operator what broke (IPC, PATH, etc.), then -FallbackPowerShell, Glob, or scoped Get-ChildItem — avoid opening with unbounded -Recurse from massive sync roots. Rule .cursor/rules/windows-pcloud-drive-search-discipline.mdc (alwaysApply: true).
  • Git & PR state: The model does not see GitHub or your local repo unless a command runs in-session. Before advising merge, next steps after a PR, or sharing a PR number/URL, refresh state (git fetch, git pull on main, and/or gh pr view). See .cursor/rules/git-pr-sync-before-advice.mdc (always applied) and CONTRIBUTING.md → PR state and agent advice.
  • Release publish sequencing (semver, all networks): Do not put X.Y.Z-beta (or the next dev bump) on main before vX.Y.Z is tagged, GitHub Release exists, and Docker Hub image push plus repository description paste from docs/ops/DOCKER_HUB_REPOSITORY_DESCRIPTION.md are done when the operator asked for a full publish — unless they explicitly split workflow and name the commit SHA to tag. Docker: before docker push to Hub for a stable release, run local smoke on Docker Desktop (docker-lab-build.ps1 + docker run --rm — docs/ops/DOCKER_IMAGE_RELEASE_ORDER.md, docs/DOCKER_SETUP.md §7); check disk headroom on the dev PC; after push, recommend docker-prune-local.ps1 so Docker Desktop does not hoard duplicate data_boar:* tags. Hub UI: replace Short + entire Full in the same session as the push (Hub does not mirror Git) — including hygiene / customer-pullable tags such as v*-safe when those tags change or old tags are deleted, so version examples never reference removed tags. Use cursor-ide-browser for Hub Edit; do not stall on “permission to use SSO” before attempting navigation (operator-browser-warm-session.mdc). -beta / -rc pushes do not require refreshing public Hub marketing copy unless asked. Tag vX.Y.Z on the commit that still has final X.Y.Z in pyproject.toml, not on a later beta commit. Verify with gh release list / gh release view before claiming “published.” Full order: .cursor/rules/release-publish-sequencing.mdc (situational — release-ritual / @release-publish-sequencing.mdc when globs miss; docker-local-smoke-cleanup.mdc stays always-on for smoke/prune) · docs/VERSIONING.md (Assistant / automation). Session keyword release-ritual · cold-start ladder § Token → rule latch (release-ritual).
  • Release & versioning (post-#970 — always-on summary): Two distinct gates — commit gate = check-all / CI / pre-commit (never call this “gate” alone; say local checks / CI per ADR-0048); release gate = GitHub #406 (CLOSED with 1.7.4 stable in PR #1024). Green commit gate does NOT authorize a stable semver bump. #970 = premature stable bump without release gate (ADR-0072); 1.7.4 is not VOID. main carries 1.7.4 stable after merge; publish (tag/Hub) = operator release-ritual post-merge. 1.7.5 does not exist — next dev line 1.8.0-beta (#772) after publish. Distribution: -beta/-rc = git-only for users (no Docker Hub / GH Release); local image smoke OK; stable = tag + GH Release + Hub. Canonical: docs/VERSIONING.md, ADR-0072, ADR-0073 (Accepted). Machine guards: security/version_policy.yaml (release_gate.open: false) + tests/test_release_version_policy.py; operator-gated label + .github/workflows/operator-gated-reopen.yml (#990). Situational rule: .cursor/rules/release-versioning.mdc.
  • Autonomous merge (when safe): If gh pr checks are green, the PR is mergeable (not conflicting), and there is no suspected regression, the assistant should run .\scripts\pr-merge-when-green.ps1 -PrNumber <N> from the repo root without asking for permission each time — escalate on failures, pending CI, or doubt. Rule: .cursor/rules/agent-autonomous-merge-and-lab-ops.mdc · skill: .cursor/skills/autonomous-merge-and-lab/SKILL.md.
  • LAB-OP batch inventory: With docs/private/homelab/lab-op-hosts.manifest.json (copy from docs/private.example/homelab/lab-op-hosts.manifest.example.json), run .\scripts\lab-op-sync-and-collect.ps1 from the integrated terminal (SSH + optional fping + git pull + homelab-host-report.sh), then read logs under docs/private/homelab/reports/ — do not only paste command lists when the manifest exists and the session can run ssh. Escalate if SSH/git fails.
  • Maintainer + contributor (two humans, one repo): Git user.name / user.email identify commit authors; the assistant does not infer who is typing. Workflow, copy-paste Git commands, and suggested Cursor prompts: docs/COLLABORATION_TEAM.pt_BR.md (EN stub). Rule: .cursor/rules/collaboration-maintainer-contributor.mdc.
  • AI agent roles — executor × auditor: Cursor is the executor (writes, commits, pushes, opens PRs — under full governance hooks). Claude Code (and any other read-only AI added by the operator) is the auditor (reads, reasons, delivers findings via gh issue create / comments / prompts handed to Cursor; never writes directly to the repo). Rationale: a single write path keeps ADR protection, PII guards, pre-commit hooks, and signed-commit discipline intact. Cross-vendor containment (ADR-0062 amended #991): A+B+C without an OpenAI-family slot is vendor-correlated — fine for ping-pong typos, not sole sign-off on P0 gates; pin models (never Auto); ideal = different vendor and harness. Roster slots: C Claude Code, A claude.ai, B Sonnet/lab node, G Gemini/NotebookLM, O OpenAI (gap). Full contract: .cursor/rules/agent-roles-executor-vs-auditor.mdc. Claude Code cold-start pointer: CLAUDE.md at the repo root.
  • Operator reachability (CI / PRs): The maintainer may use only the GitHub mobile app (channel A) for now. When adding Slack, Signal (Docker REST bridge), or Actions webhooks for human pings, follow docs/ops/OPERATOR_NOTIFICATION_CHANNELS.md (pt-BR) and .cursor/rules/operator-notification-channels.mdc—secrets only in GitHub Actions / env, never in committed files. Telegram is not used for Data Boar operator notifications (maintainer policy). Slack (channel B): workflow Slack operator ping (manual) uses repository secret SLACK_WEBHOOK_URL; Slack CI failure notify ships on origin as .github/workflows/slack-ci-failure-notify.yml, with a private snapshot at docs/private/raw_pastes/cursor-incident/slack-ci-failure-notify.yml.old for pause drills. Pause, turn back on, and pytest guards are spelled in §4.1.1 of that doc (EN + pt-BR). tests/test_github_workflows.py enforces slack-*.yml shape (including CI-failure workflow_run + webhook step pattern).
  • Session capture (chat → durable memory): When preserving high-value alignment from chat, follow docs/ops/OPERATOR_SESSION_CAPTURE_GUIDE.md (pt-BR); put sensitive or personal follow-ups under docs/private/ (e.g. author_info/RECENT_OPERATOR_SYNC_INDEX.pt_BR.md). Rule .cursor/rules/operator-session-capture.mdc · skill .cursor/skills/operator-session-capture/SKILL.md.
  • Social editorial + today-mode: Planned posts, deferrals (rename YYYY-MM-DD_* drafts), and optional evidence files for ad-hoc publishes are documented in docs/ops/today-mode/SOCIAL_PUBLISH_AND_TODAY_MODE.md (pt-BR); morning ritual prints private hub paths via scripts/operator-day-ritual.ps1 -Mode Morning. Chat token social-today-check (English-only per .cursor/rules/session-mode-keywords.mdc). Skill .cursor/skills/operator-social-today-alignment/SKILL.md. This does not auto-post or auto-sync platforms — discipline + docs.
  • Operator career / LinkedIn / ATS / SLI (private layout): Canonical map and file placement: gitignored docs/private/author_info/career/README.pt_BR.md. Store your ATS/SLI deliverables and Calendly notes there — not under docs/private/commercial/candidates/ (talent pool = other people). Social post drafts live in docs/private/social_drafts/drafts/; published state and cross-network reconciliation live in docs/private/social_drafts/editorial/SOCIAL_HUB.md (single inventory table; shortcut at docs/private/social_drafts/SOCIAL_HUB.md). Draft filenames use prefix YYYY-MM-DD: actual publication date when published, or next planned date while still draft—rename when the date changes and keep the hub Rascunho column in sync. WordPress (e.g. databoar.wordpress.com) may share or cross-post to X, LinkedIn, FacColleague-Sok, Threads, and other linked services — when reconciling, the assistant asks the operator if a live post could map to more than one planned row (L#/X#/T#/W#) instead of guessing. LinkedIn has no general public API for full-profile JSON to automation — for bulk structured extract, use PDF export from the site + scripts/operator-linkedin-profile-extract.ps1 → JSON under author_info/career/exports_linkedin_snapshot/; read_file on that JSON saves tokens for diffs. For live headline/About/skills review (operator or talent pool), the assistant may use the embedded browser when the operator authorizes—see previous bullet. Tracked pointers: docs/PRIVATE_OPERATOR_NOTES.md §2 · docs/private.example/author_info/README.md · docs/plans/TOKEN_AWARE_USAGE.md §2. Rule .cursor/rules/operator-career-private-layout.mdc.
  • Private tree versioning (off GitHub): Optional nested Git under docs/private/ (or backups / file:// / self-hosted remote) keeps private-note history out of the product origin—see docs/ops/PRIVATE_LOCAL_VERSIONING.md (pt-BR).
  • Open PR dangling guard: At session start/end, run gh pr list --state open and explicitly record any still-open PRs whose goal was partially superseded (for example older branch paths/docs). Before new feature work, either (a) resume to completion with a fresh sync from main, or (b) close as superseded and note replacement PR/commit.
  • Execution strategy: Apply critical-first sequencing and PR batching. Resolve critical blockers to a stable local commit state first; otherwise prioritize product work per docs/plans/PLANS_TODO.md taxonomy (token-aware, high-gain slices). Do not force micro-PRs for every commit; batch coherent commits into a reviewable PR. See .cursor/rules/execution-priority-and-pr-batching.mdc.
  • Plan checkbox discipline (hard rule): When a PR implements or closes a named slice from a PLAN_*.md, explicitly open that plan file in the same branch and update its phase table checkboxes (⬜ → ✅) before the PR merges. Do not rely on plans-status-pl-sync.mdc loading automatically — that rule is situational (docs/plans/** globs only). The plan file is in scope: touch it intentionally. Run python scripts/plans_hub_sync.py --write if the Status: header changes or the plan moves to completed/. Globs on plans-status-pl-sync.mdc stay restricted (no connectors/** / core/** expansion) — AGENTS.md + this bullet are the default for code-only PRs.
  • GitHub activity vs office hours (maintainer optional): The operator may prefer fewer public pushes/PRs/merges on weekday business hours when the slice is not urgent; critical-first, security/CVE, and broken CI on main still warrant immediate sync, with clear Conventional Commits as breadcrumbs. Tracked summary: docs/ops/OPERATOR_WORKFLOW_PACE_AND_FOCUS.md §7.1; full note (private): docs/private/OPERATOR_GIT_PR_RHYTHM_OFFICE_HOURS.pt_BR.md. Assistants: read that private file for the current mode (e.g. sabbatical / between jobs = do not defer push/PR/merge for office hours unless the operator asks otherwise). When employed mode is active in the same file, apply the defer/batch rhythm by default when proposing push/PR/merge for non-critical work.
  • Study cadence (operator calendar): The operator balances deep coding with CWL + alternating AI + other study (see docs/plans/PORTFOLIO_AND_EVIDENCE_SOURCES.md §3.0–§3.2). At natural breakpoints (slice done, session end, calm “what next?”), the assistant may add a brief optional reminder only when study-cadence-reminders.mdc is already in context (situational rule — portfolio/sprints/operator-manual globs or study-check / @study-cadence-reminders.mdc)—not during incidents, not every message, and not by inventing nudges when the rule never attached. For an on-demand recap, the operator types study-check. Full rules: .cursor/rules/study-cadence-reminders.mdc · docs/ops/OPERATOR_AGENT_COLD_START_LADDER.md § Token → rule latch (study-check).
  • Commit grouping strategy: Classify work as feature, workflow, or documentation before committing. Keep tracks separate by default; allow feature + documentation or workflow + documentation only when docs are required for that checkpoint. Avoid mixing feature + workflow in one commit/PR unless explicitly requested.
  • Commit message types (Conventional Commits): Use a clear type as the first token, orthogonal to the grouping above:
  • feat — new behavior or user-visible capability.
  • fix — bugfix / incorrect behavior; use a scope when helpful, e.g. fix(security): when the primary risk is security.
  • security — optional top-level type when the change is primarily hardening or threat reduction (alternative to fix(security): for larger security slices).
  • refactor — behavior-preserving restructuring; prefer this over a combo of feat + fix in one commit. If a change mixes unrelated feature work and a bugfix, use two commits (or two PRs) instead of one ambiguous commit.
  • docs, chore, ci, test, perf, style — standard meanings.
  • Dependency-only bumps — prefer chore(deps): (e.g. uv.lock, pyproject.toml pins, Dependabot merges) so scans and changelogs stay obvious.
  • Scopes — optional domain in parentheses. Common scopes (product + operator “fronts”):
Scope Use when changing…
detector core/detector.py, sensitivity heuristics, ML/DL gates.
report report/, Excel/trends/recommendations output.
api api/routes, OpenAPI, dashboard API surface.
docker Dockerfile, deploy/docker-compose*, image publish notes.
homelab Generic tracked runbooks only: HOMELAB_VALIDATION*, HOMELAB_* (power, UniFi, solar, WSL, OS matrix), scripts/homelab-host-report.sh, windows-dev-report.ps1. Real hostnames, IPs, inventory → docs/private/homelab/ (never committed).
ops Other docs/ops/ runbooks (Sonar, commit/PR, notifications, troubleshooting) when not homelab-specific.
workflow PR/commit process docs, TOKEN_AWARE_USAGE.md, check-all / hygiene scripts (pr-hygiene-remind.ps1), CONTRIBUTING workflow bullets.
private-layout Tracked policy/templates only: docs/PRIVATE_OPERATOR_NOTES.md, docs/private.example/ (layout copy-me). Not for real LAB-OP truth—that lives under gitignored docs/private/ (e.g. homelab/).
feedback-inbox Tracked policy: .cursor/rules/operator-feedback-inbox.mdc, docs/private.example/feedbacks-inbox/, keyword feedback-inbox. Drops: gitignored docs/feedbacks, reviews, comments and criticism/ (not docs/private/).
plans PLANS_TODO.md dashboard/stats, sequencing edits in docs/plans/*.md.
cursor .cursor/rules/, .cursor/skills/ (often with chore(cursor): or docs(cursor):). Collaboration maintainer/contributor rule: collaboration-maintainer-contributor.mdc.
sidequest Intentional detours outside the main slice (mandatory unblock, exploratory spike, or pauseable tangent). Keep bounded with stop condition + resume pointer to primary goal.

Examples: docs(homelab):, docs(private-layout):, docs(feedback-inbox):, chore(deps):, docs(workflow):, feat(detector):, chore(cursor):.

  • Optional test corpus (text / cifras): For local scanner experiments, the operator’s public chord/tab repo FabioLeitao/cifras is a good Portuguese text source; third-party chord sites may be ToS/copyright-sensitive—see tests/README.md § Optional real-world text samples.
  • Automation: Prefer scripts/check-all.ps1, scripts/commit-or-pr.ps1, and related helpers — .cursor/skills/token-aware-automation/SKILL.md. For talent pool (ATS, LinkedIn, dossiers): .\scripts\talent.ps1 (CLI — scan, import, review, linkedin, social, search; skill: .cursor/private/skills/candidate-ats-evaluation/SKILL.md). For LAB-OP env vars: . .\scripts\lab-env-load.ps1** (dot-source; Bitwarden-first, .env fallback; see .cursor/rules/lab-op-systems-context.mdc §3).
  • Cloud Agents / Cursor Web: Use Cloud Agents as a sandbox + toil offload (token-aware) and keep LAN/private/secrets out of them. Rule: .cursor/rules/cloud-agents-token-aware-safety.mdc.
  • Proactive anti-regression automation (default behavior): When a change can reasonably be guarded by automation, prefer to add or update a script/test/rule now instead of relying on memory later. Priorities: (1) regression prevention for fixed issues, (2) consistency checks that save future tokens, (3) narrow fast checks that fit pre-commit/CI. If no automation was added, briefly justify why (for example, unstable signal, excessive runtime, or duplicate coverage). Bundled examples: outbound discovery identity — ADR 0034 + get_http_user_agent() tests; README stakeholder copy vs deck jargon — ADR 0035 + tests/test_readme_stakeholder_pitch_contract.py.
  • Local commits to document progress: Commit on a feature branch when you finish a meaningful unit—one important change or a coherent batch (“train of thought”)—so history stays understandable before PR/release. Avoid huge uncommitted trees; merge/rebase main regularly to limit conflicts. See .cursor/rules/execution-priority-and-pr-batching.mdc and docs/ops/COMMIT_AND_PR.md (pt-BR).
  • Assistant session closure (no redundant permission ping): When a scoped change passes .\scripts\check-all.ps1 (or an agreed subset) and is ready as a coherent unit, commit on a feature branch—do not stop to ask whether to commit when the gate is green and intent is clear. Open a PR and merge only when it makes sense: the batch is reviewable, CI is worth running, and the slice is done enough to integrate—not after every micro-edit. Batch related commits into one PR when practical (.cursor/rules/execution-priority-and-pr-batching.mdc). Avoid CI churn loops: do not default to commit → PR → CI → tiny fix → merge → pull → repeat in the same session for nits that could wait or be folded into the same branch before the first push. Merge when gh pr checks are green and the diff matches intent (.cursor/rules/agent-autonomous-merge-and-lab-ops.mdc); escalate on failures or doubt.
  • Assistant session ritual (synced clone + evidence + next steps): Treat git history and GitHub as the durable record—same as the operator expects from a careful human maintainer. (1) Public tree: At the start of substantive work, run git fetch origin and git status -sb. On main, if behind origin/main, run git pull origin main before editing so the canonical clone is not silently stale. On a feature branch, git fetch and integrate origin/main when the branch is long-lived or before PR (merge or rebase per project habit). Do not advise merge, “what’s next,” or diff review without this refresh (.cursor/rules/git-pr-sync-before-advice.mdc). (2) Primary dev workstation (canonical clone — primary Linux dev workstation today): Keep non-destructive posture—no filter-repo, clean-slate on the product tree, or history rewrite here from routine sessions (docs/ops/PRIMARY_LINUX_WORKSTATION_PROTECTION.md, .cursor/rules/primary-linux-workstation-protected-no-destructive-repo-ops.mdc; Windows doc when Windows primary returns). (2b) Linux primary quality gate: uv run pre-commit install if .git/hooks/pre-commit is missing; ./scripts/check-all.sh before opening a PR. (3) Exceptions: sidequest / exploratory branches may diverge temporarily and be abandoned if unworkable—stop condition + resume pointer per .cursor/rules/session-mode-keywords.mdc. (4) Stacked private repo (docs/private/.git): The main repo ignores this tree for origin—that does not mean “no Git” or “assistant must not commit.” After changes under docs/private/, the assistant runs .\scripts\private-git-sync.ps1 (and -Push to all configured non-public mirrors—lab-* SSH remotes, optional Windows P: file-tree mirror when the script finds P: mounted, and a bare notes-sync.git on a VeraCrypt-mounted drive letter (Z: operator default; script probes Z: then Y:) when that path exists—see scripts/private-git-sync.ps1) without asking the operator to “remember” private commits or for rhetorical backup permission when the task already implies full mirror alignment. PyPI tokens, SSH keys, and Hub passwords stay in env / OS keychain—never in any commit. docs/ops/PRIVATE_STACK_SYNC_RITUAL.md, operator-evidence-backup-no-rhetorical-asks.mdc, ADR 0040, keyword private-stack-sync. (5) After a slice: Continue with the next necessary step (local commit, PLANS_TODO.md row, doc, private-stack-sync, or a single PR when the slice warrants it) when the path is obvious—do not stall on redundant “should I…?” PR/merge is not mandatory after every commit—only when integrating that work is the right move. Full rule: .cursor/rules/agent-session-ritual-sync-main-and-private-stack.mdc.
  • Docker homelab (optional): Prefer .\scripts\docker-lab-build.ps1, .\scripts\docker-hub-pull.ps1, and .\scripts\docker-prune-local.ps1 -WhatIf (then without -WhatIf when agreed) over ad-hoc docker build / tag sprawl / manual rmi lists — same outcomes, fewer tokens, predictable tags (data_boar:lab, Hub latest + semver + previous patch). See scripts/docker/README.md and .cursor/skills/docker-smoke-container-hygiene/SKILL.md. Use opportunistically after Dockerfile/image work, before/after Hub push + Scout, or when the operator mentions disk clutter.
  • Plans: Single source of truth for backlog sequencing is docs/plans/PLANS_TODO.md (English-only history); orientation map for collaborators is docs/plans/PLANS_HUB.md (auto-table of every PLAN_*.md under docs/plans/ and docs/plans/completed/; sync with python scripts/plans_hub_sync.py --write; check in pre-commit). Keep docs/plans/ for active plans only: when a plan is truly done, git mv it to docs/plans/completed/, fix links, run plans_hub_sync.py --write, update PLANS_TODO.md — .cursor/rules/plans-archive-on-completion.mdc · .cursor/rules/docs-plans.mdc. Keep each PLAN_*.md first-line Status: and the plan body consistent with PLANS_TODO.md when work ships — .cursor/rules/plans-status-pl-sync.mdc. Operator runbooks live under docs/ops/ (EN + pt-BR). When creating new PLAN_*.md files (including from GitHub issues), assume overlap awareness with existing plans unless the operator marks the work completely independent—see .cursor/rules/docs-plans.mdc § When creating a new plan. Do not add markdown links from external-tier product docs into docs/plans/; entry point for humans is docs/README.md Internal and reference. Guard: tests/test_docs_external_no_plan_links.py. Record: docs/adr/ADR-0004-external-docs-no-markdown-links-to-plans.md. Rule: .cursor/rules/audience-segmentation-docs.mdc. Milestone / identity coherence (avoid duplicating roadmap text across plans): .cursor/rules/plan-milestone-and-identity-coherence.mdc; optional skill .cursor/skills/milestone-roadmap-coherence/SKILL.md.
  • Doc hubs (MAP, docs README, ADR index): PLANS_HUB and plans-stats outputs are CI-enforced; MAP, root README hub tables, and AGENTS policy bullets are curated (do not rely on AGENTS.md for the “latest ADR number”—see ADR habit below). When editing those surfaces, follow .cursor/skills/doc-hubs-plans-sync/SKILL.md and .cursor/rules/doc-hubs-sync-ritual.mdc so links, paired pt-BR, and ADR pointers stay aligned with accepted ADRs and plans.
  • pmo-view (English token): When you want plan/PMO Markdown rendered in Cursor, type pmo-view in chat (same as other session keywords—English only). The agent lists key files and Markdown preview shortcuts (Ctrl+Shift+V / Ctrl+K V on Windows; Cmd+… on macOS). The agent cannot flip the editor to Preview for you. See .cursor/rules/session-mode-keywords.mdc and docs/ops/README.md § pmo-view.
  • ADR habit (always-on): After any session where a tooling choice, architectural pattern, security/compliance posture, workflow lock-in, or explicit deferral occurs, create an ADR without waiting to be asked. Use .\scripts\new-adr.ps1 -Title "..." -Summary "..." to scaffold (the script auto-picks the next NNNN from docs/adr/*.md), then fill Context/Decision/Consequences. Update docs/adr/README.md index. Commit as docs(adr): add ADR NNNN — short-title. Full trigger taxonomy: .cursor/rules/adr-trigger.mdc (always applied). Never hardcode a “current last ADR” number in this file (it goes stale). Filenames are ADR-NNNN-slug.md. Next number from disk: bash ls docs/adr/ADR-*.md | sort | tail -n 1 then increment NNNN; PowerShell Get-ChildItem docs/adr/ADR-*.md | Sort-Object Name | Select-Object -Last 1. Reconcile with docs/adr/README.md if unsure.

Learned User Preferences

  • ADR improvements are thin slices: When improving an existing ADR, propose one focused change at a time, read the current file before editing, and never alter the ADR's original intent, context section, or approved Decision scope — only additive or clarifying amendments, always after explicit operator approval.
  • Draft-first before creating governance files: When suggesting changes to ADRs, .mdc rules, scripts, or similar governance files, present the full draft text in chat for approval before writing or creating any file. The operator corrected this pattern repeatedly when new files were created without prior review.
  • Copy-paste-ready output (default): Deliver suggestions in final, copy-paste-ready form — not as manual-assembly snippets or inline "edit this by hand" instructions. Recurring operator correction across multiple sessions.
  • "Defensible and enforceable" gate for new process ADRs: Before creating a process/culture/workflow ADR, honestly assess whether each decision item is actually enforceable. Present a table showing enforcement grade per item (CI-enforced / review convention / honor system) and let the operator decide — honor-system-only decisions have low durable value.
  • Deprecation discipline — read before proposing: Before proposing deprecation of any file, rule, or config section, always read_file the actual content (never rely on cache or assumptions). Present justification field-by-field with evidence, and ask for operator approval one section at a time. Do not bundle deprecation proposals without individual evidence.
  • Continual-learning / transcript memory updates stay additive: When refreshing Learned Workspace Facts from agent transcripts (e.g. agents-memory-updater + .cursor/hooks/state/continual-learning-index.json), append new durable facts; do not delete or swap out existing bullets to "make room" for unrelated topics — that is continual-forgetting and regresses operator-grounded rigor. Retire or replace a fact only with explicit operator approval or a tracked superseding decision (ADR / plan / commit message) that names what it replaces.
  • Thin PR burn-down and [Pn] bands: When collapsing GitHub audit / plan issues into thin PRs, maximize autonomy inside the same P0→P3 band ([P0] … [P3] in the title); blocked work needs an explicit resume pointer before picking another same-band issue; do not bury higher-band work by quietly moving to P3 housekeeping—when that gap would strand actionable higher-band tickets, stop and ping the operator instead of "backlogging" silently. Behaviour is spelled end-to-end in docs/ops/THIN_SLICE_AGENT_PRIORITY_HANDOFF.md (.pt_BR.md pair).
  • Merge-ready proof requires full check-all: When claiming a slice is green before merge or answering whether tests passed, run .\scripts\check-all.ps1 on the real workspace—not lint-only.ps1, ad-hoc pytest, or commit-or-pr.ps1 -RunTests alone (that flag runs pytest-only). Remote CI green supplements but does not replace a recent local full gate when the operator asks for evidence.
  • X (Twitter) threads — linear reply-chain: Tweet 1 is the root post; each subsequent tweet must use Reply on the immediately previous tweet (not an earlier anchor). Before adding the next tweet, the parent should show "1 Reply"—"2 Replies" on the same parent means a fork (delete wrong branch and re-chain from the prior tweet).
  • Social publish close — document always: After operator-confirmed publish, update SOCIAL_HUB.md, add or refresh a row under docs/private/social_drafts/drafts/evidence/, align the draft filename date prefix, and run .\scripts\private-git-sync.ps1 -Push in the same close pass (see docs/ops/today-mode/SOCIAL_PUBLISH_AND_TODAY_MODE.md).
  • Deterministic numbered prompts (PASSO/FASE): When the operator supplies a step-by-step prompt with explicit order and stop boundaries, execute only those steps in sequence; stop at the declared boundary; no improvisation, no extra files/issues, and no Task/subagent delegation for that slice unless the prompt allows it.
  • gh Allow ritual: Show the complete gh command in chat before running mutating GitHub CLI (gh issue close, gh pr create, etc.); wait for explicit operator Allow unless the prompt already authorized that exact command.
  • Issue close via PR, not manual: Do not gh issue close on issues meant to auto-close via PR Closes #N in the body — manual close breaks the intended merge workflow.
  • ADR commits and G0-S (ADR-0056): New or changed files under docs/adr/ trigger G0-S in .cursor/hooks/pre-commit; run .\scripts\inv-adr.ps1 and stage docs/adr/INVENTORY.txt; use git commit --no-verify only when the operator prompt explicitly authorizes bypass for that ADR slice.
  • Emergency stop: On EMERGENCY STOP, halt immediately; resume only with surgical work (single stated file/change) and zero extra scope until a new operator prompt.
  • The repo constitution is BINDING, not advisory — this is NOT a toy project: ADRs, always-on .cursor/rules/*.mdc (especially never-weaken-security-gates.mdc), AGENTS.md, and CI/pre-commit gates are enforcement, not suggestions. This is a paid, reputation- and money-bearing product: the founder has 1,000+ USD in disputed Cursor charges and an open SEV-1 vendor escalation caused by agent-driven PII leakage. A fired security gate (PII seed gate gatekeeper_audit.py, pii_history_guard.py, tests/test_pii_guard.py, secret scanner, CODEOWNERS, signed-commit / ADR attestation) means STOP and escalate to the operator — NEVER weaken, loosen, make case-insensitive, remove -w/\b, --no-verify, skip a hook, or reword the audited file to dodge the seed. The #944 incident did exactly this (matcher made case-insensitive to pass CI) and is the canonical failure the rule exists to prevent. The ONLY sanctioned response to a false positive is tighten-pattern + operator-approved allowlist (security/pii_gate_allowlist.txt). Refs: ADR-0071 (self-protecting PII gate), ADR-0049 (no brittle mitigations), ADR-0018 / 0020 (PII guards), ADR-0066 (fail-closed), ADR-0062 (repo is the source of truth, not LLM consensus).

Learned Workspace Facts

  • lab-op vs lab-pb is a hard, REAL PII distinction — never collapse them: lab-op = REAL, sensitive homelab infrastructure (actual hostnames and RFC1918 IPs; the operator's docs/private/security_audit/PII_LOCAL_SEEDS.txt denylist) that must NEVER appear in tracked/public files or git history. lab-pb = sanctioned placeholders for public docs. This distinction existed from the project's start and must not be dismissed "as noise." Real lab-op hostnames were leaked into history: a deterministic per-seed measurement on 2026-06-18 found 251 commits carrying infra hostnames plus a third-party individual's name (former-employer contact = third-party personal data). Treat any lab-op hostname / IP / third-party name as PII-class: placeholders in tracked files, real values only under gitignored docs/private/. When a tracked file would carry a real hostname, redact to a generic label (e.g. "the laptop lab node") — that is removing PII, not "dodging the gate."
  • ADR content must be read before asserting: Never summarize or state what a specific ADR covers from memory alone — always read_file the ADR before recommending changes or quoting its scope. Asserting incorrect content was flagged by the operator as a "blunt mistake" (example: claiming ADR-0007 covers sampling caps when it actually covers synthetic-data-corpus-before-real-data).
  • Git ref corruption recovery (null bytes): If .git/refs/heads/main contains null bytes, recover by locating the correct commit SHA from loose objects via zlib decompress and searching for the known commit message, then writing the SHA back to the ref file. This is safe and reversible without git filter-repo.
  • .cursorrules legacy file deprecated and deleted: The .cursorrules JSON config (linguistic rules, Slack protocol, web session contract) was fully deprecated in commit 817cdf5; all content migrated to .mdc rules (always-on), ADRs, and skills. A pre-commit hook no-legacy-cursorrules (guard test: tests/test_no_legacy_cursorrules.py) prevents recreation. Do not recreate this file.
  • Bandit/Ruff coverage gap (P1 closed 2026-05-14): utils/, scanners/, and logging_custom/ were excluded from Ruff lint + Bandit (commit c208113); gap is now closed. db/ is still excluded (legacy structural issues). utils/notify.py, utils/regex_patterns.py, and scanners/db_connector.py are now covered. PII guard (tests/test_pii_guard.py) was upgraded (2026-05) to also detect AWS AKIA keys, GitHub PATs, Slack tokens, Stripe keys, PEM headers, and Bearer tokens.
  • completão is TWO-LEVEL (host + container) + DANFE lineage for labop scripts: lab-completao-container-smoke.sh validates the containerized Data Boar stack (starts container on port 9002, writes ~/.labop-status). Architecture is TWO-LEVEL: host smoke (OS/Python) and container smoke (Docker/Podman engine) — both must pass. New labop-*.sh scripts follow the DANFE-lineage pattern (from FabioLeitao/bash_localiza_danfe_por_id_de_upload): do_log_() function, STATUS_FILE, ~/log/ directory, and [cite:N] comments for traceability. ctop shows Docker Swarm containers (they appear in docker ps on the node); Data Boar appears as a one-shot container that exits quickly — a ctop snapshot may miss it (not a false positive). MongoDB and other long-running target services persist normally.
  • docs/private/commercial/ is NOT empty: The directory contains ~160+ files including ENGAGEMENT_TRACKER, BATTLE_KIT_ESCRITORIO_ADVOCACIA, pricing studies, talent pool, and ATS/SLI deliverables. Never claim this directory is empty or sparse — always list_dir or read_file before asserting its state.
  • Plans H-taxonomy extends beyond H3: H0–H3 are the near-term bands; H4 (far horizon, post-lato/master's) and H5 (dream/PhD) also exist. Do not assume H3 is the furthest horizon when referencing PLANS_TODO.md sequencing.
  • inventory.json schema: derive from existing fields, never add derived ones: The personas list already encodes which services are expected (target_nfs → NFS present, target_cifs → CIFS present); distro already exists for OS/pkg derivation. Never add pkg_mgr, nfs_svc, smb_svc, or similar derived fields to docs/private/homelab/data/inventory.json — derive them in handler PS1 code via a lookup table. The operator explicitly reverted schema additions made on agent suggestion; always check what is derivable from existing fields before proposing new schema additions.
  • Private plans live in docs/private/plans/: Operator-private plans (e.g. PLAN_FOUNDER_CAREER_AND_BRANDING.pt_BR.md, PLAN_FOUNDER_SRE_CAREER_AND_PRODUCT_ALIGNMENT.md) are gitignored and tracked only in the stacked private repo. Do not list them in public plan inventories or PLANS_HUB.md.
  • scan_scope: config key is obsolete: The canonical YAML key for scan targets is targets:, not scan_scope:. If scan_scope: appears in config, normalize_config() emits a WARNING (logging) and still ignores that block. Affected benchmark configs were fixed in commit 04d1896. Always use targets: in benchmark and scan YAML; treat "No findings" on a known-positive corpus as a config key trap until you confirm targets: is populated.
  • Lab host preflight (Rust + NFS/SMB/firewall scripts): maturin develop --release must be run on each lab host after uv sync — Rust extension NOT auto-built; silent Python fallback if missing. New scripts committed (2026-05): labop-nfs-server-ensure.sh, labop-smb-server-ensure.sh, labop-firewall-lib.sh (detects ufw/nftables/iptables/firewalld/none; ephemeral zero-trust rules open only for LAB_OP_SUBNET, revert after test; state tracked in ~/.labop-fw-ephemeral-*.json). LABOP_NFS_SERVER, LABOP_NFS_CLEANUP, LABOP_SMB_SERVER, LABOP_SMB_CLEANUP added to sudoers on manifest lab-op hosts. Validate sudoers with: sudo visudo -cf /etc/sudoers.d/labop-host-report (catches typos like LABOB vs LABOP). Build-ContainerArtefact.ps1 cache fix (commit 74e8c4a): was always rebuilding when Docker was online even with a fresh tar; fixed with $shouldBuild flag. Canonical ensure-script path fix (commit 99b6fdc): handler now strips version suffix from $Node.path (e.g. data-boar-v1.7.3) to use canonical data-boar path, which is what sudoers allow. Privileged ensure scripts and $HOME: under sudo -n, $HOME is typically the privileged account home, not the invoking operator. Tracked labop-*-ensure.sh scripts resolve the operator home via getent / SUDO_USER — do not teach $HOME as the scan-corpus root. Residual path defaults stay in gitignored operator homelab notes (#384).
  • A/B benchmark complete (2026-05-13); all fixes applied: v1.7.3=10816ms vs v1.7.4-rc=10330ms, ratio=0.955x on 10-file LGPD corpus (26 findings each, no regression). Rounds A+B both complete on four manifest lab-op hosts (five-host fleet from #821 — alpine-emachines E527 added after this benchmark). CIFS ensure: smbd not found on test host (expected diagnostic); NFS on a Void Linux lab host: no NFS service found — needs xbps-install nfs-utils. Commits: BenchRunId fix f366ae3, build-cache fix 74e8c4a, canonical-path fix 99b6fdc. maestro-benchmark-ab.ps1 must run in a native PowerShell window (20–25 min, exceeds terminal background limit). 0.574x Safe-Hold threshold requires a larger corpus — do not assert breach or pass from small runs. Web health check uses benchmark ports 18088/28088, not 8088. Edit gate (no continual-forgetting): do not shorten, archive-only, or strip this bullet until a new Maestro A/B uses tests/data/bench/synthetic_valid_cpf_3k.txt (or another operator-agreed corpus), docs/ops/LAB_LESSONS_LEARNED.md and a dated docs/ops/lab_lessons_learned/LAB_LESSONS_LEARNED_YYYY_MM_DD.md record the outcome, and the operator explicitly greenlights superseding the milestone (same additive discipline as Learned User Preferences).
  • Today-mode WORKBOARD + optional workflow zizmor lint: docs/ops/today-mode/WORKBOARD.md and WORKBOARD.pt_BR.md are the short routing hub to PLANS_TODO, CARRYOVER, and OPERATOR_TODAY_MODE_* without duplicating those tables. GitHub Actions YAML hygiene uses zizmor via scripts/workflow-security-lint.ps1 / workflow-security-lint.sh, optional manual-stage pre-commit hook workflow-security-lint, and .github/workflows/zizmor.yml; advisory by default and not part of check-all.ps1 — use -Enforce, DATA_BOAR_ENFORCE_ZIZMOR, or repo ZIZMOR_ENFORCE when the baseline is clean enough to fail the gate.
  • plans-stats.py horizon bucket tracks the latest H0–H5 in a heading line: The script walks PLANS_TODO.md top to bottom; any Markdown heading (# …) whose text contains H0–H5 updates the active horizon for subsequent dashboard status rows. A mid-file label such as #### H1 (meant only as a subsection) re-buckets all later rows until another heading carries a different H0–H5. Prefer inline tags like [H1] in prose or non-heading bullets instead of extra H0–H5 headings outside the file’s normal horizon structure.
  • THIN_SLICE_AGENT_PRIORITY_HANDOFF + duplicate issue closure: Canonical runbook docs/ops/THIN_SLICE_AGENT_PRIORITY_HANDOFF.md (.pt_BR.md) anchors assistant thin PR sequencing plus [P0] … [P3] headline-band hygiene, PLANS_TODO.md / gh issue list freshness, and escalation rules—cross-linked from docs/ops/README.md (.pt_BR.md) and docs/ops/COMMIT_AND_PR.md (.pt_BR.md). Echo duplicates close once the canonical fix ships with green CI via gh issue close <echo#> --duplicate-of <canonical#>—gh issue close --help is the authoritative flag reference (reject stale shorthand).
  • Maestro stack layout: Canonical orchestration lives in DataBoar/maestro (core/Maestro.ps1 + handlers/Handle-<persona>.ps1). Consumer wrappers under scripts/maestro-*.ps1 / scripts/Resolve-MaestroRoot.ps1 resolve the clone via MAESTRO_ROOT or sibling ../maestro. Inventory remains docs/private/homelab/data/inventory.json; -Deep uses tests/config/benchmark-rc.yaml. Do not conflate with lab-completao-orchestrate.ps1.
  • audit.ps1 vs check-all: Root audit.ps1 tees check-all into logs/audit-*.log—intended as optional manual Maestro/completão preflight on the Windows dev PC; Maestro.ps1 and lab-completao-orchestrate.ps1 are not wired to call it yet. Commits and PRs use check-all / lint-only per slice—not audit.ps1 on every commit.
  • Maestro persona taxonomy: Canonical term is handler (Handle-<persona>.ps1); avoid musical-metaphor labels (e.g. Capo/soloist) in scripts, tables, or docs.
  • Public databoar.com.br contact aliases: Tracked CoC/compliance surfaces use conduct@databoar.com.br and contact@databoar.com.br—no personal outlook.com in the public tree; provider-side mailbox setup remains an operator-manual step.
  • Windows Cursor hooks — PowerShell for beforeShellExecution: On the primary Windows dev PC, .cursor/hooks.json must invoke adr-protection.ps1 via powershell.exe -NoProfile -ExecutionPolicy Bypass -File — .sh hooks do not run under Cursor on Windows. Git-level ADR guard stays .cursor/hooks/pre-commit (POSIX/Git Bash); one-time git config core.hooksPath .cursor/hooks per clone (ADR-0055 / ADR-0056).
  • Instagram feed posts require media + durable private assets: Main-grid Instagram posts need photo or video (caption-only is not feed-postable). Copy lives in *_PASTE_READY.md under docs/private/social_drafts/drafts/; campaign screenshots must be copied from ephemeral Cursor assets/ into docs/private/social_drafts/drafts/media/<campaign>/ before relying on them and private-git-sync.
  • WSL2 lab symlinks resolve to the primary Windows dev tree: On L-series, paths like ~/dev → /mnt/c/.../Documents/dev/ (via WSL2) are the same canonical clone as the Windows workspace—apply PRIMARY_WINDOWS_WORKSTATION_PROTECTION.md blast-radius rules to destructive Git/repo ops there too.
  • VeraCrypt Z:\notes-sync.git bare mirror recovery: If private-git-sync.ps1 -Push fails on Z:/notes-sync.git with **fsync/Bad file descriptor errors, git fsck reports problems, or the bare tree is missing/corrupt, recreate Z:\notes-sync.git with git init --bare (same path **private-git-sync.ps1 probes Z: then Y:), run git -C Z:\notes-sync.git config core.fsync none, keep safe.directory for docs/private, git -C docs/private push Z:/notes-sync.git main to republish main, then rerun .\scripts\private-git-sync.ps1 -Push. lab-* SSH mirrors stay authoritative while VeraCrypt git fsck returns 0.
  • FOUND.000 / FOUND.001 debris on VeraCrypt (chkdsk): FOUND.* folders on Z:\ often come from Windows chkdsk recovery; Remove-Item / rd /s /q while mounted may surface 1392 (corrupted/unreadable entry) or 145 (“directory not empty” with no visible files). Usually these folders do not block a rebuilt notes-sync.git mirror when git fsck is clean — operator path is dismount VeraCrypt → reboot → chkdsk Z: /F ( or container repair, per private runbooks ) before retries.
  • Issue queue Mermaid map: Open-issue sequencing visualization lives at docs/ops/ISSUE_QUEUE_SEQUENCING_MAP.md (issue #654); refresh when NÃO INICIAR chains or wave counts change; linked from docs/plans/PLANS_TODO.md Wave 1 bullet and docs/ops/README.md.
  • ADR-0061 U-axis gate: Formal sub-order within same P+milestone and cross-milestone hard gate are documented in docs/adr/ADR-0061-u-axis-issue-suborder-and-cross-milestone-gate.md (implements .cursor/rules/execution-priority-and-pr-batching.mdc).
  • Repo truth over LLM consensus: For ADR numbers, filenames, and inventory, docs/adr/*.md + Get-ChildItem docs/adr/ADR-*.md beat converged model suggestions — three auditors can agree on a wrong filename until the repo is read.
  • SQLite schema migrations (_ensure_*): Every new Column() on an existing table requires a matching _ensure_*() method in LocalDBManager and a regression test that bootstraps a legacy DB without the column and asserts it is added on init — see docs/plans/PLAN_SCHEMA_MIGRATION.md.
  • Data Boar commercial ecosystem (bestiary, off-band vault): data-boar is the public core only. Sibling private repos: design-system, maestro (spinout complete — canonical .ps1 in DataBoar/maestro; consumer resolves via MAESTRO_ROOT / sibling), license-studio (issuer — spun out 2026-06-25), ten concept-only scaffolds. Locked bestials: Boar · Crow · Quati · Pangolin · Rikki · Maestro · License Studio. Cursor = executor; Claude = RO auditor. Map: docs/ops/CURSOR_ECOSYSTEM_ONBOARDING.md; spinout: docs/ops/LICENSE_STUDIO_SPINOUT.md. OPSEC off-band for private relay.
  • Maestro Deep 5-host gate marathon (#1021 / PR #1022) — E2E substance proven, bump NOT automatic (~66 days, closed 2026-06-24): Operator self-imposed Maestro re-Deep gate (A.I.I.D.C.O.B.P.P.) on branch fix/maestro-gate-bundle-1022. Evidence chain: full GitHub issue #1021 thread + PR #1022 commit history (R9b→R12.1 harness) + operator photo archive (private; index docs/private/author_info/RECENT_OPERATOR_SYNC_INDEX.pt_BR.md §2026-06-24) + lab logs under /tmp/maestro-deep-run-*-r12.log on the operator workstation. Ritual completed: two frozen invocations of Maestro-Deep-5Host-Gate.ps1 -Detach -IdempotentTwice → 4 SUMMARY passes with pass1_rows=pass2_rows=expected=6 and IDEMPOTENCY: match; graceful ALARM (expected NFS/SMB degradations on designated lab nodes) not moral FAIL; 9c DB oracle (lab_customers / lab_people counts) live. Not cleared / no semver bump until operator rested OK + R12.2 tail fix ($totalFails .Count scalar bug → exit code unreliable). Multi-agent credits (where each reached): Cursor executor; Claude Code / Claude.ai read-only Auditor (Web, Windows, mobile surfaces — caught false MISMATCH, enforced diff-before-rerun, row-count guard, réu-intacto); Gemini advisory reviews where context allowed. Do not weaken security gates or claim commercial release from lab E2E alone.

Known platform limitations and active workarounds (confirmed 2026-05-21)

Cursor Support (Nathan) confirmed three agent-safety gaps; forum thread: Three confirmed agent safety failures. Priority per ADR-0055 (G0·H·U·A·S). Implementation: #646.

  • Bug 1 — File-Deletion Protection inoperative: Platform failure. Compensating control: git pre-commit hook in .cursor/hooks/pre-commit (ADR staging guard) plus normal review discipline.
  • Bug 2 — Slack STOP signals ignored: Platform failure; Slack messages are not cancel signals. Workaround: use the Stop control on cursor.com/agents (or IDE stop) to halt a run.
  • Bug 3 — No beforeShellExecution hard boundary on stable: Repo implements .cursor/hooks.json → .cursor/hooks/adr-protection.ps1 (Windows: powershell.exe -File), plus git config core.hooksPath .cursor/hooks (one-time per clone) so the git-level pre-commit hook runs (Git Bash). ADR edits still require explicit operator authorization (ADR-0056); CI inv-adr.ps1 + ed25519 remain the cryptographic enforcement layer.

Defense layers for docs/adr/:

Layer Mechanism Type
1 .cursor/rules/ LLM steering (suggestion)
2 beforeShellExecution hook Shell-level intercept
3 pre-commit git hook Git-level intercept
4 inv-adr.ps1 + ed25519 Cryptographic CI enforcement

Ver ADR-0062 para o padrão A.I.I.D.C.O.B.P.P. de auditoria offband.