contextcompass 2.15.0__py3-none-any.whl

contextcompass_cli/__init__.py

@@ -0,0 +1,74 @@
+"""Context Compass - durable, file-backed execution state for coding agents.
+
+This module is the INSTALLER and CLI. It is deliberately NOT named
+`contextcompass`, even though that is the distribution name, because the payload
+directory in this repository is `src/contextcompass/` and two things claiming one
+import name resolve differently depending on how Python was invoked. Keeping the
+module name distinct means no collision is possible.
+
+Three names are in play here and they are not interchangeable:
+
+    contextcompass         the DISTRIBUTION on PyPI, and the repository
+    contextcompass_cli     this MODULE - what `import` sees
+    context_compass        the DIRECTORY, both in `src/` and in a consuming repo
+
+The last one keeps its underscore. 119 shipped documents cite paths like
+`context_compass/tools/...` - 546 mentions - plus a config filename and two
+tool filenames carrying the same name. Renaming it is a migration, not a
+rename, and it buys nothing now that this module is named distinctly.
+
+`src/` mirrors the install deliberately: what you see there is what lands in a
+repository, with no translation step. The one thing that must NOT match either
+is this module's name, because a module sharing a name with a directory in the
+user's repo resolves differently depending on how Python was invoked.
+
+The payload ships inside this module as `_package/`.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+# Single source of truth for the version. `MANIFEST.md` inside the payload
+# records the same number, and a test asserts they agree - a version maintained
+# in two places is a version that will disagree, which is the whole reason the
+# manifest is derived rather than declared.
+__version__ = "2.15.0"
+
+# What `init` creates in the user's repository. Distinct from both the source
+# directory and the module name; see the docstring above.
+INSTALL_DIRNAME = "context_compass"
+
+# Where the payload lives in THIS repository's source tree. Deliberately the
+# same as INSTALL_DIRNAME: what you see in `src/` is what lands in a repo, with
+# no translation step to hold in your head.
+SOURCE_DIRNAME = "context_compass"
+
+_HERE = pathlib.Path(__file__).resolve().parent
+
+
+def _find_payload() -> pathlib.Path:
+    """Where the shipped package files live, installed or in a source checkout.
+
+    In a wheel the build maps `src/contextcompass/` to `_package/` beside this
+    module. In a source tree that directory does not exist and the payload is
+    the sibling `src/contextcompass/`. Without this fallback the CLI works only
+    after a build, so every source-run and every test would exercise a different
+    code path from the one users get.
+
+    The older layout put the payload at `src/context_compass/`. That is still
+    accepted, because a checkout mid-rename should not fail obscurely.
+    """
+    installed = _HERE / "_package"
+    if (installed / "AGENTS.MD").is_file():
+        return installed
+    for sibling in (SOURCE_DIRNAME, INSTALL_DIRNAME):
+        checkout = _HERE.parent / sibling
+        if (checkout / "AGENTS.MD").is_file():
+            return checkout
+    return installed          # report the installed path in the error message
+
+
+PAYLOAD = _find_payload()
+
+__all__ = ["__version__", "PAYLOAD", "INSTALL_DIRNAME", "SOURCE_DIRNAME"]

contextcompass_cli/__main__.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""The `contextcompass` command.
+
+    contextcompass init                 put context_compass/ into this repo
+    contextcompass upgrade --check      what an upgrade would change
+    contextcompass upgrade --apply      do it
+    contextcompass migrate-boards ...   one-time board migration
+    contextcompass version              installed and on-disk versions
+
+WHY A CLI AT ALL
+
+Without it, adopting Context Compass means cloning a repository and copying a
+directory out of it by hand, and upgrading means keeping a second checkout
+around at the right version so `--new` has somewhere to point. As a command, the
+installed package IS the new version, so there is nothing to keep in sync.
+
+The subcommands delegate to the same scripts that ship inside the payload. They
+are not reimplemented here: one copy of the logic, exercised by the same tests,
+whether it is reached through the CLI or run directly from a repository.
+"""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import runpy
+import shutil
+import sys
+
+from . import PAYLOAD, INSTALL_DIRNAME, __version__
+
+TOOLS = PAYLOAD / "tools"
+
+
+def _run_tool(script: pathlib.Path, argv: list[str]) -> int:
+    """Run a payload script in-process with the argv it expects.
+
+    `runpy` rather than a subprocess: the scripts bootstrap their own imports by
+    inserting their directory on `sys.path`, and this keeps that behaviour
+    identical whether they are reached through the CLI or invoked directly.
+    """
+    old_argv = sys.argv
+    sys.argv = [str(script), *argv]
+    try:
+        runpy.run_path(str(script), run_name="__main__")
+        return 0
+    except SystemExit as exc:
+        return int(exc.code or 0)
+    finally:
+        sys.argv = old_argv
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    target = args.into.resolve() / INSTALL_DIRNAME
+    if target.exists():
+        print(f"REFUSED: {target} already exists.")
+        print("  This command creates a new install; it will not write over one.")
+        print("  To bring an existing install up to date:  contextcompass upgrade --check")
+        return 2
+
+    if not PAYLOAD.is_dir():
+        print(f"ERROR: payload missing from the installed package ({PAYLOAD}).")
+        print("  This is a packaging fault, not a usage error - the wheel was built")
+        print("  without its data files.")
+        return 2
+
+    # Importing the payload's tools compiles bytecode INTO the installed
+    # package, so a pip-installed copy grows `__pycache__` directories that are
+    # not part of the package. Copying those into someone's repository puts 29
+    # untracked binary files in their first commit and makes the install
+    # disagree with its own manifest.
+    ignore = shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo")
+
+    if args.check:
+        n = sum(1 for p in PAYLOAD.rglob("*")
+                if p.is_file() and "__pycache__" not in p.parts)
+        print(f"WOULD CREATE: {target}  ({n} files, version {__version__})")
+        return 0
+
+    shutil.copytree(PAYLOAD, target, ignore=ignore)
+    n = sum(1 for p in target.rglob("*") if p.is_file())
+    print(f"CREATED: {target}")
+    print(f"  {n} files, version {__version__}")
+    print()
+    print("Next:")
+    print(f"  1. Point your agent at {INSTALL_DIRNAME}/AGENTS.MD and ask it to onboard")
+    print("     as `engineer`.")
+    print("  2. Commit the directory. It is your repository's memory now, and it is")
+    print("     meant to be reviewed and diffed like any other source.")
+    return 0
+
+
+def cmd_upgrade(args: argparse.Namespace) -> int:
+    install = args.install.resolve()
+    if not (install / "AGENTS.MD").is_file():
+        print(f"ERROR: {install} is not a Context Compass install (no AGENTS.MD).")
+        print(f"  Pass --install, or run from a repo containing {INSTALL_DIRNAME}/.")
+        return 2
+    argv = ["--install", str(install), "--new", str(PAYLOAD)]
+    argv += ["--apply"] if args.apply else ["--check"]
+    for flag in ("keep_retired", "preserve_local", "seed_instance"):
+        if getattr(args, flag):
+            argv.append("--" + flag.replace("_", "-"))
+    return _run_tool(TOOLS / "update_context_compass.py", argv)
+
+
+def cmd_migrate_boards(args: argparse.Namespace) -> int:
+    install = args.install.resolve()
+    if not (install / "AGENTS.MD").is_file():
+        print(f"ERROR: {install} is not a Context Compass install (no AGENTS.MD).")
+        return 2
+    argv = ["--install", str(install), "--new", str(PAYLOAD)]
+    argv += ["--apply"] if args.apply else ["--check"]
+    if args.diff:
+        argv.append("--diff")
+    return _run_tool(TOOLS / "migrate_boards.py", argv)
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    print(f"contextcompass {__version__}")
+    manifest = PAYLOAD / "MANIFEST.md"
+    if manifest.is_file():
+        for line in manifest.read_text(encoding="utf-8").splitlines():
+            if line.startswith("| package_version |"):
+                print(f"  payload manifest: {line.split('|')[2].strip()}")
+                break
+    install = args.install.resolve() / "MANIFEST.md" if args.install else None
+    if install and install.is_file():
+        for line in install.read_text(encoding="utf-8").splitlines():
+            if line.startswith("| package_version |"):
+                print(f"  installed here  : {line.split('|')[2].strip()}")
+                break
+    return 0
+
+
+def default_install() -> pathlib.Path:
+    """`./context_compass` if it exists, else `.` - so both layouts just work."""
+    here = pathlib.Path.cwd()
+    nested = here / INSTALL_DIRNAME
+    return nested if (nested / "AGENTS.MD").is_file() else here
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="contextcompass", description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--version", action="version", version=f"contextcompass {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help=f"create {INSTALL_DIRNAME}/ in a repository")
+    p.add_argument("--into", type=pathlib.Path, default=pathlib.Path("."),
+                   help="repository root (default: current directory)")
+    p.add_argument("--check", action="store_true", help="report only, write nothing")
+    p.set_defaults(func=cmd_init)
+
+    # Flags are declared, not forwarded blindly. `parse_known_args` would pass a
+    # typo straight through to a tool that ignores it, and the run would look
+    # like it honoured a flag it never saw.
+    p = sub.add_parser("upgrade", help="upgrade an install to this version")
+    p.add_argument("--install", type=pathlib.Path, default=None)
+    p.add_argument("--check", action="store_true",
+                   help="report only, write nothing (the default)")
+    p.add_argument("--apply", action="store_true", help="perform the upgrade")
+    p.add_argument("--keep-retired", action="store_true",
+                   help="do not sweep files the new version no longer ships")
+    p.add_argument("--preserve-local", action="store_true",
+                   help="do not conform package files you have edited")
+    p.add_argument("--seed-instance", action="store_true",
+                   help="create INSTANCE files the manifest lists but disk lacks")
+    p.set_defaults(func=cmd_upgrade)
+
+    p = sub.add_parser("migrate-boards",
+                       help="one-time board migration into USER-DEFINED regions")
+    p.add_argument("--install", type=pathlib.Path, default=None)
+    p.add_argument("--check", action="store_true",
+                   help="report only, write nothing (the default)")
+    p.add_argument("--apply", action="store_true", help="rewrite the boards")
+    p.add_argument("--diff", action="store_true", help="print a unified diff per board")
+    p.set_defaults(func=cmd_migrate_boards)
+
+    p = sub.add_parser("version", help="show installed and on-disk versions")
+    p.add_argument("--install", type=pathlib.Path, default=None)
+    p.set_defaults(func=cmd_version)
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if getattr(args, "install", "missing") is None:
+        args.install = default_install()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

contextcompass_cli/_package/AGENTS.MD

@@ -0,0 +1,310 @@
+
+
+# AGENTS.MD - Prime Policies
+## Execution Order
+
+- Before running tools, editing files, or executing commands, complete
+  onboarding from `context_compass/AGENTS.MD`.
+- If there is any conflict between repository-root `AGENTS.MD` and
+  `context_compass/AGENTS.MD`, `context_compass/AGENTS.MD` is authoritative.
+
+## Tooling Mandate: Context Compass Is the Only System of Record
+
+### Who this binds
+
+This rule binds you by what your runtime PROVIDES, not by who built it. No brand
+is named because no brand needs to be: if your environment gives you any of the
+surfaces below, you are in scope.
+
+You are in scope if you are:
+- a command-line coding agent,
+- an agent embedded in an editor or IDE,
+- a desktop or chat agent application with file and shell access,
+- a headless agent built on an SDK or API,
+- a browser-driving agent,
+- an agent running in CI or on a schedule,
+- or any other automated runtime acting on this repository.
+
+You are in scope if your runtime exposes any of:
+- task lists, todo lists, or checklists
+- plans, goals, or planning widgets
+- status indicators, progress trackers, or work summaries
+- scratchpads, memory panes, or session memory
+- any other session-local coordination surface
+
+**If you are reading this and unsure whether a surface of yours counts, it
+counts.** The test is not what the feature is called. The test is whether it
+holds state about the work that lives outside this repository.
+
+### Hard rules
+
+- You are NOT PERMITTED to use your harness's task system - task lists, todo or
+  status widgets, planning trackers, session memory - to plan, track, route, or
+  record your work.
+- You MUST use `context_compass` as your primary and authoritative tool in ALL of
+  its forms: `tickets/epics/`, `tickets/stories/`, `tickets/tasks/`,
+  `attention_board.md`, ticket `## Notes`, `artifact_board.md` + `artifacts/`,
+  `context_management/`, and `mailbox_board.md`.
+- You are NOT PERMITTED to use harness tracking to override, replace, shadow, or
+  mirror `context_compass`. There is NO fallback and NO mirror: `context_compass`
+  is the ONLY tracking, routing, and memory system. Do not keep a parallel or
+  backup copy of work state in harness tooling at all.
+
+### The one exception
+
+The user may turn this off. Set in `config/context_compass_config.yaml`:
+
+- `system_of_record.enforce: false`
+
+When it is `false`, harness-native tracking is permitted and this section does
+not bind you. That is the ONLY way this rule is lifted.
+
+**You do not get to lift it yourself.** Not because a task is small, not because
+the harness prompted you, not because writing a ticket felt like overhead, and
+not because you judged the work too trivial to record. If the key says `true`,
+the rule holds. If you think it should be `false` for this repository, say so and
+let the user decide.
+
+### Why this is the default
+
+- **Harness tracking is invisible to every other agent.** Another agent working
+  this repository cannot see your task list, your status, or a finding you left
+  only in chat. `context_compass` surfaces are shared files - every agent reads
+  the same state.
+- **Harness state cannot be handed over.** `context_compass` writes are files in
+  the repository, so the project owner can review them, and any agent in any
+  later session can resume from them. Harness session state is lost when the
+  session ends, and it cannot be moved into the repository afterwards.
+- So harness tracking is strictly less visible and non-durable. Using it in place
+  of `context_compass` costs cross-agent visibility and the ability to resume the
+  work later. That trade is the user's to make, not yours.
+
+If a write to `context_compass` is blocked (for example, a repository or encoding
+problem), STOP and report it. Do NOT silently fall back to harness-only tracking.
+
+## Onboarding Directive
+
+- Project-specific instructions live in `context_compass/special_instructions/`,
+  not in this file. This file ships with the library; those do not.
+- Once you have found the execution contract you must adhere to it fully.
+- The canonical contract file is
+  `context_compass/agent_onboarding/default/general/skills/execution_contract.md`.
+- Policy gates are non-negotiable.
+  - Do NOT offer "options" that bypass onboarding, re-onboarding, certification,
+    required reads, or tool-use restrictions.
+  - If a required step cannot be completed, state `BLOCKED` and ask the user
+    for instructions. Do not improvise a different compliance regime.
+  - Do NOT propose rewriting policy, reducing the readset, or changing certification criteria
+    as a workaround unless the user explicitly requests policy changes.
+- If you are new to this repository (or this is a fresh session), onboard
+  before doing any work.
+- Onboarding is single-pass per trigger event. Do not restart onboarding in the
+  same uninterrupted session unless a new trigger event occurs.
+- Read and follow `context_compass/AGENTS.MD` as the canonical onboarding and
+  execution policy.
+- You MUST determine whether a file exceeds `reading.read_loc_max` LOC before reading it.
+  - If the file might exceed `reading.read_loc_max`, compute the line count (LOC) first.
+  - If the file is clearly <= `reading.read_loc_max`, do NOT waste tool calls on LOC counting.
+- You must read every required **baseline** onboarding file completely.
+  - Do not skip required-baseline files.
+  - Do NOT claim a file was read unless it was actually read.
+  - On-demand files are required only when the active task triggers them.
+- Loop-based document reads are forbidden except for line counts. Content reads
+  must be manual per file path.
+- Files larger than `reading.read_loc_max` LOC must be read in sequential chunks
+  with each read operation at or below `reading.viewer_tool_read_limit`.
+- Repository-root `AGENTS.MD` is a pointer only. The canonical onboarding and
+  execution policy lives in `context_compass/AGENTS.MD`, and that file wins on
+  any conflict.
+
+## Compaction Directive
+
+- Highest priority adherence: after any context compaction or handoff,
+  immediately re-onboard before any action.
+- Re-read `context_compass/AGENTS.MD` and
+  `context_compass/agent_onboarding/default/general/skills/compaction_requirements.md`
+  before continuing work.
+- For compaction/handoff summaries, you MUST keep summaries empty when the runtime allows it;
+  otherwise you MUST use minimal file-pointer summaries only.
+- Post `REONBOARD: COMPLETE` attestation **with read-integrity proof** before any action:
+  - `ROLE_SKILLS_READ`
+  - `READ_INTEGRITY_PROOF`
+  - `NO_ACTION_TAKEN_YET: true`
+
+## Highest Priority Adherence (Compaction Re-Onboarding)
+
+After any context compaction or handoff:
+
+- Stop and re-onboard before any tooling, edits, execution, or planning.
+- Re-onboarding is single-pass per trigger event. Do not repeat the same
+  `AGENTS.MD` + `execution_contract.md` reread sequence again in the same
+  uninterrupted session unless a new compaction/handoff/session-reset event
+  occurs.
+- Re-onboarding is reserved for compaction/handoff recovery only.
+- Fresh-session startup uses ONBOARD flow, not REONBOARD flow.
+- Re-read `agent_onboarding/default/general/skills/execution_contract.md` in
+  full immediately after `AGENTS.MD`.
+- Start from `config/context_compass_config.yaml`, then `SKILLS.MD`.
+- Re-read and follow every Markdown document in `context_compass/special_instructions/` using relative repo paths only.
+- Re-read `agent_onboarding/default/general/skills/compaction_requirements.md`.
+- Re-check-in on `context_compass/mailbox_board.md` (update your row,
+  consume messages addressed to you) per
+  `agent_onboarding/default/general/skills/mailbox_protocol.md`.
+- README reads are allowed for `new` first-time onboarding only; non-`new`
+  roles use policy/skills docs.
+- Re-certify with a message that includes:
+  - `AGENT_NAME: <name>`
+  - the exact phrase `CERTIFY: APPROVED`
+  before acting.
+- If anything is unclear after re-onboarding, ask the user for instructions and
+  get confirmation before acting.
+- During compaction/handoff summarization, you MUST keep summaries empty when allowed;
+  otherwise you MUST emit minimal file-pointer summaries only.
+- Before any action, publish a Re-Onboarding Attestation message with:
+  - `REONBOARD: COMPLETE`
+  - `ROLE_SKILLS_READ` (resolved role chain in parent-first order)
+  - `AGENT_NAME` (`<name>` if already supplied for this re-onboarding cycle,
+    otherwise `REQUIRED_FROM_USER`)
+  - `FILES_REREAD` (at minimum: `attention_board.md` + active ticket paths)
+  - `READ_INTEGRITY_PROOF` (concise comprehension proof; NOT tool logs)
+  - `NO_ACTION_TAKEN_YET: true`
+
+Performative compliance is forbidden during re-onboarding:
+
+- marker-only loops (for example, `$null = Get-Content ...` plus `REREAD:`
+  output) do not count as re-reading
+- parallel/bulk reading is allowed only when document contents are actually read
+- onboarding claims are valid only when required source documents were actually
+  read
+- onboarding dump files are non-canonical artifacts and do not satisfy
+  onboarding requirements
+
+## Onboarding Gate (Required)
+
+Before any tooling, edits, or execution:
+
+- Read `agent_onboarding/default/general/skills/execution_contract.md` in full
+  immediately after `AGENTS.MD`.
+- Do not perform duplicate end-of-onboarding rereads of `AGENTS.MD` or
+  `execution_contract.md` in the same uninterrupted session.
+- Read `config/context_compass_config.yaml`.
+- Read `SKILLS.MD`.
+- Read and follow every Markdown document in `context_compass/special_instructions/` using relative repo paths only.
+- Check in on `context_compass/mailbox_board.md` (add/update your
+  checked-in row; read messages addressed to you if other agents are
+  active) per
+  `agent_onboarding/default/general/skills/mailbox_protocol.md`.
+- When `SKILLS.MD` is read, list the roles in its registry table and ask the
+  user which role to take on unless the user already selected one explicitly.
+- Resolve the selected role to its `SKILLS.MD` path from the `SKILLS.MD`
+  registry table. `SKILLS.MD` is the single role registry;
+  `config/context_compass_config.yaml` does not enumerate roles.
+- Read the selected role `SKILLS.MD` and all inherited parent `SKILLS.MD`
+  files in parent-first order, walking each file's `INHERITS_SKILLS_FROM`
+  header.
+- Treat every path in every section a resolved `SKILLS.MD` marks as **baseline**
+  as an active skill doc, and read all of them.
+  - **The test is the label, not the heading.** Roles name their baseline
+    sections differently - **Active skills**, **Required baseline skills**,
+    **Baseline system orientation** - and a role may introduce another. Read
+    what the role marks baseline; do not match against a fixed list of headings.
+  - Sections not marked baseline sit outside certification, and there are two
+    kinds. **On-demand** states a trigger: those paths become mandatory once it
+    fires, and MUST be read before any work in that scope. **Self-directed** has
+    no trigger at all: read those at your own initiative whenever the work needs
+    them, without asking permission.
+  - **Do not treat Self-directed as On-demand-with-no-trigger-yet.** That reading
+    produces an agent that never opens the document, and it has already happened.
+- If first-time onboarding is active and selected role is `new`, complete
+  onboarding then set:
+  - `profiles.onboarding.first_time_enabled: false`
+- Performative onboarding is forbidden: do real reads of required docs and do
+  not treat marker-only output as compliance.
+- Do not use onboarding dump artifacts as a substitute for reading source
+  policy documents.
+
+Onboarding readset authority:
+
+- `context_compass/config/context_compass_config.yaml`
+- `context_compass/SKILLS.MD`
+- `context_compass/special_instructions/` (read every Markdown document under this directory using relative repo paths only)
+- resolved `SKILLS.MD` chain under `context_compass/agent_onboarding/`
+
+Onboarding completion attestation (first onboarding in a fresh session):
+
+- Publish this before requesting certification:
+  - `ONBOARD: COMPLETE`
+  - `ROLE_SKILLS_READ` (resolved role chain in parent-first order)
+  - `AGENT_NAME` (`<name>` if already supplied for this onboarding cycle, otherwise `REQUIRED_FROM_USER`)
+  - `READ_INTEGRITY_PROOF` (concise comprehension proof; NOT tool logs)
+  - `NO_ACTION_TAKEN_YET: true`
+
+Certification gating:
+
+- Obey certification gating from
+  `agent_onboarding/default/general/policies/policy_skills.md` and
+  `agent_onboarding/default/general/skills/self_certification.md`.
+- Do not use tools or edit files until the user replies with a message that
+  includes:
+  - `AGENT_NAME: <name>`
+  - the exact phrase `CERTIFY: APPROVED`
+  except tools needed to read onboarding docs.
+- If certification is missing, stop and request it before edits or tool use.
+
+## Communication Style and Feedback Standards
+
+- Be direct and technical. No polite padding, no motivational fluff.
+- Do not mirror insults. Stay professional and blunt.
+- Professional baseline only. Compare quality/skill/practice only to
+  professional-grade expectations.
+- Never handwave. State evidence, uncertainty, and next verification step when
+  needed.
+- When the user asks "why" (e.g., why we are re-reading or gating):
+  - You MUST answer with the underlying rationale first (decision quality, correctness, safety, trust),
+    THEN cite the policy requirement.
+  - A reply that only cites policy ("because policy says so") is non-compliant.
+  - If you cannot explain the rationale, STOP and ask for clarification rather than bluffing.
+- Use collaborative voice. Speak as "we" when aligning on shared goals without
+  slipping into fluff.
+- Treasure context. Treat durable context as a top priority.
+
+## Direction Recall / Path Correction
+
+When the user signals that the direction has been lost - scope feels unbounded,
+the goal has gone fuzzy, or the remaining work reads as one undifferentiated
+mass:
+
+- Re-anchor to the active ticket, the `attention_board.md` route, and any
+  documents in `context_compass/special_instructions/`.
+- Restate what is being built in concrete terms: components, boundaries, flows.
+- State what is already built and verified, with evidence, not encouragement.
+- Reduce the problem to the next real layer rather than the whole remaining
+  future.
+- Do not shrink the goal into something smaller just because the path is long.
+  Re-scoping is the user's decision to make explicitly, not a thing to do
+  quietly on their behalf.
+- Keep the language grounded and high-signal. Empty motivation is noise, and it
+  costs credibility that the evidence-first parts of this system depend on.
+
+This is a direction-setting protocol, not emotional support. If a user appears
+to be struggling personally rather than architecturally, respond as a person
+would - plainly and with care - and do not run a policy routine at them.
+
+## Special Instructions Directory
+
+- Project-specific instructions live in `context_compass/special_instructions/`.
+- Read and follow every Markdown document in that directory.
+- Use relative repo paths only.
+
+## Compliance Challenge Protocol (Anti-Drift)
+
+When the user signals distrust or drift (e.g., "performative compliance", "playing games",
+"you're lying", "box-checking"):
+
+1) STOP. Do not continue the current action stream.
+2) State current status plainly: ONBOARD/REONBOARD complete? If uncertain, treat as NOT complete.
+3) Cite the controlling rule(s) (file + section name).
+4) Execute the single compliant next step. Do not present options unless multiple compliant paths truly exist.
+5) Prove, don't posture: repair/provide `READ_INTEGRITY_PROOF` (no tool-log theatre).
+   If proof cannot be produced, mark `BLOCKED` and ask for instructions.
+