Scope agent context: extract conventions, enforce git restrictions via hooks

.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run python scripts/block_git_mutations.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

.github/code-conventions.md

@@ -0,0 +1,62 @@
+When generating Python code (e.g. when translating TypeScript to Python),
+follow these guidelines:
+
+* When creating a new file, add a copyright header to the top:
+```
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+```
+
+* Assume Python 3.12
+
+* Always strip trailing spaces
+
+* Keep class and type names in `PascalCase`
+* Use `python_case` for variable/field and function/method names
+
+* Use `Literal` for unions of string literals
+* Keep union notation (`X | Y`) for other unions
+* Use `Protocol` for interfaces whose name starts with `I` followed by a capital letter
+* Use `dataclass` for other classes and structured types
+* Use `type` for type aliases (`PascalCase` again)
+* Use `list`, `tuple`, `dict`, `set` etc., not `List` etc.
+
+* Translate `foo?: string` to `foo: str | None = None`
+
+* When writing tests:
+  - don't mock; use the regular implementation (maybe introduce a fixture to create it)
+  - assume `pytest`; use `assert` statements
+  - match the type annotations of the tested functions
+  - read the code of the tested functions to understand their behavior
+  - When using fixtures:
+    - Fully type-annotate the fixture definitions (including return type)
+    - Fully type-annotate fixture usages
+
+* Don't put imports inside functions.
+  Put them at the top of the file with the other imports.
+  Exception: imports in a `if __name__ == "__main__":` block or a `main()` function.
+  Another exception: pydantic and logfire.
+  Final exception: to avoid circular import errors.
+
+* **Import Architecture Rules**:
+  - **Never import a symbol from a module that just re-exports it**
+  - **Always import directly from the module that defines the symbol**
+  - **Exception**: Package `__init__.py` files that explicitly re-export with `__all__`
+  - **Exception**: Explicit re-export patterns like `from ... import X as X` or marked with "# For export"
+  - This prevents circular imports and makes dependencies clear
+
+* Order imports alphabetically after lowercasing; group them as follows
+  (with a blank line between groups):
+  1. standard library imports
+  2. established third-party libraries
+  3. experimental third-party libraries (e.g. `typechat`)
+  4. local imports (e.g. `from typeagent.knowpro import ...`)
+
+* **Error Handling**: Don't use `try/except Exception` to catch errors broadly.
+  Let errors bubble up naturally for proper error handling and debugging at higher levels.
+
+* **Code Validation**: Don't use `py_compile` for syntax checking.
+  Use `pyright` or `make check` instead for proper type checking and validation.
+
+* **Deprecations**: Don't deprecate things -- just delete them and fix the usage sites.
+  Don't create backward compatibility APIs or exports or whatever. Fix the usage sites.

.github/copilot-instructions.md

@@ -1 +1,3 @@
 Get your instructions from AGENTS.md in the repo root.
+
+For code generation and style conventions, see [code-conventions.md](code-conventions.md).

.gitignore

@@ -1,5 +1,6 @@
-# Editor settings
-.vscode
+# Editor settings (but .vscode/settings.json is tracked for Copilot hooks)
+.vscode/*
+!.vscode/settings.json
 
 # Python
 __pycache__

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "github.copilot.chat.agent.hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "uv run python scripts/block_git_mutations.py",
+        "windows": "uv run python scripts\\block_git_mutations.py",
+        "timeout": 5
+      }
+    ]
+  }
+}

AGENTS.md

@@ -2,38 +2,10 @@
 
 **NEVER use TEST_MODEL_NAME or "test" embedding model outside of test files**
 
-Never run git commands that make any changes. (`git status` and `git diff` are fine)
-Exceptions: `git push`, `git worktree`, `git branch` (for tracking setup), as instructed below.
-
-**NEVER COMMIT CODE.** Do not run `git commit` or any other git commands
-that make changes to the repository. Exception: Worktrees/Branches below.
-`git add` is fine.
+Git mutations are blocked by a PreToolUse hook (`scripts/block_git_mutations.py`).
 
 When moving, copying or deleting files, use the git commands: `git mv`, `git cp`, `git rm`
 
-## Worktrees and Branches
-
-- Each session uses its own worktree with a feature branch
-- Create worktrees with: `git worktree add ../<repo>-<branch-name> -b <branch-name>`
-- Push the branch to the `me` remote: `git push me <branch-name>`
-- Set upstream to `me/<branch-name>`: `git branch --set-upstream-to me/<branch-name>`
-- **Never** upstream to `me/main` — that must stay identical to `origin/main`
-- The worktree directory name should be `<repo>-<branch-name>` (sibling of the main checkout)
-- **Work in the worktree directory**, not the main checkout — edit files there, run tests there
-- VS Code may show buffers from the main checkout; ignore those when working in a worktree.
-  When in doubt, verify edits landed on disk with `cat` or `grep` in the terminal.
-
-## Debugging discipline
-
-- When a bug seems impossible, suspect stale files or wrong working directory — not exotic causes.
-- If you're tempted to blame installed package versions, `__pycache__`, or similar,
-  **stop and ask the user** before investigating further. You're probably on the wrong track.
-
-**Whenever the user tells you how to do something, states a preference, or corrects you,
-extract a general rule and add it to AGENTS.md** (unless it's already covered -- maybe
-reformulate since it apparently didn't work). This applies even without being asked.
-In all cases show what you added to AGENTS.md.
-
 - Don't use '!' on the command line, it's some bash magic (even inside single quotes)
 - When running 'make' commands, do not use the venv (the Makefile uses 'uv run')
 - To get API keys in ad-hoc code, call `load_dotenv()`
@@ -59,67 +31,4 @@ In all cases show what you added to AGENTS.md.
 
 **IMPORTANT! YOU ARE NOT DONE UNTIL `make format check test` PASSES**
 
-# Code generation
-
-When generating Python code (e.g. when translating TypeScript to Python),
-please follow these guidelines:
-
-* When creating a new file, add a copyright header to the top:
-```
-# Copyright (c) Microsoft Corporation.
-# Licensed under the MIT License.
-```
-
-* Assume Python 3.12
-
-* Always strip trailing spaces
-
-* Keep class and type names in `PascalCase`
-* Use `python_case` for variable/field and function/method names
-
-* Use `Literal` for unions of string literals
-* Keep union notation (`X | Y`) for other unions
-* Use `Protocol` for interfaces whose name starts with `I` followed by a capital letter
-* Use `dataclass` for other classes and structured types
-* Use `type` for type aliases (`PascalCase` again)
-* Use `list`, `tuple`, `dict`, `set` etc., not `List` etc.
-
-* Translate `foo?: string` to `foo: str | None = None`
-
-* When writing tests:
-  - don't mock; use the regular implementation (maybe introduce a fixture to create it)
-  - assume `pytest`; use `assert` statements
-  - match the type annotations of the tested functions
-  - read the code of the tested functions to understand their behavior
-  - When using fixtures:
-    - Fully type-annotate the fixture definitions (including return type)
-    - Fully type-annotate fixture usages
-
-* Don't put imports inside functions.
-  Put them at the top of the file with the other imports.
-  Exception: imports in a `if __name__ == "__main__":` block or a `main()` function.
-  Another exception: pydantic and logfire.
-  Final exception: to avoid circular import errors.
-
-* **Import Architecture Rules**:
-  - **Never import a symbol from a module that just re-exports it**
-  - **Always import directly from the module that defines the symbol**
-  - **Exception**: Package `__init__.py` files that explicitly re-export with `__all__`
-  - **Exception**: Explicit re-export patterns like `from ... import X as X` or marked with "# For export"
-  - This prevents circular imports and makes dependencies clear
-
-* Order imports alphabetically after lowercasing; group them as follows
-  (with a blank line between groups):
-  1. standard library imports
-  2. established third-party libraries
-  3. experimental third-party libraries (e.g. `typechat`)
-  4. local imports (e.g. `from typeagent.knowpro import ...`)
-
-* **Error Handling**: Don't use `try/except Exception` to catch errors broadly.
-  Let errors bubble up naturally for proper error handling and debugging at higher levels.
-
-* **Code Validation**: Don't use `py_compile` for syntax checking.
-  Use `pyright` or `make check` instead for proper type checking and validation.
-
-* **Deprecations**: Don't deprecate things -- just delete them and fix the usage sites.
-  Don't create backward compatibility APIs or exports or whatever. Fix the usage sites.
+For code generation and style conventions, see [.github/code-conventions.md](.github/code-conventions.md).