Add lifecycle hooks and agent context for BookStore project

- Introduced lifecycle hooks for PreToolUse, SessionStart, PreCompact, Stop, SubagentStart, and SubagentStop events.
- Implemented scripts for code rule checks, security checks, memory protocol enforcement, session context injection, and build validation.
- Created JSON configuration files for each hook to define their behavior and associated scripts.
- Added an audit log script to track user prompts for observability.
- Updated documentation to include details about the new GitHub Copilot agent team and lifecycle hooks.
- Enhanced .gitignore to exclude local audit logs.

Author: aalmada

.github/hooks/audit.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "python3 .github/hooks/scripts/audit_prompt.py",
+        "windows": "py -3 .github\\hooks\\scripts\\audit_prompt.py",
+        "timeout": 5
+      }
+    ]
+  }
+}

.github/hooks/code-rules.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "python3 .github/hooks/scripts/check_code_rules.py",
+        "windows": "py -3 .github\\hooks\\scripts\\check_code_rules.py",
+        "timeout": 10
+      }
+    ]
+  }
+}

.github/hooks/memory-protocol.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "python3 .github/hooks/scripts/check_memory_protocol.py",
+        "windows": "py -3 .github\\hooks\\scripts\\check_memory_protocol.py",
+        "timeout": 5
+      }
+    ]
+  }
+}

.github/hooks/scripts/audit_prompt.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""
+UserPromptSubmit hook: Append every prompt to a local audit log.
+
+Non-blocking — always exits 0. Used for observability only.
+The log file is gitignored and stays local to the developer's machine.
+
+Log location: .github/hooks/logs/audit.log
+
+Input (stdin): VS Code UserPromptSubmit JSON payload
+Output (stdout): nothing (non-blocking)
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+LOG_PATH = os.path.join(".github", "hooks", "logs", "audit.log")
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    prompt: str = data.get("prompt", "").strip()
+    session_id: str = data.get("sessionId", "unknown")
+    timestamp: str = datetime.now(timezone.utc).isoformat()
+
+    os.makedirs(os.path.dirname(LOG_PATH), exist_ok=True)
+
+    try:
+        with open(LOG_PATH, "a", encoding="utf-8") as f:
+            f.write(f"[{timestamp}] session={session_id}\n{prompt}\n---\n")
+    except Exception:
+        pass  # Never fail the hook on a logging error
+
+
+if __name__ == "__main__":
+    main()

.github/hooks/scripts/check_code_rules.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+PreToolUse hook: Block edits containing BookStore banned patterns.
+
+Scans .cs files in edit tool calls and denies the operation when
+any AGENTS.md code rule violation is detected.
+
+Input (stdin): VS Code PreToolUse JSON payload
+Output (stdout): JSON deny decision, or nothing on success
+"""
+
+import json
+import re
+import sys
+
+# (regex_pattern, human-readable fix message)
+RULES: list[tuple[str, str]] = [
+    (
+        r"\bGuid\.NewGuid\(\)",
+        "Use Guid.CreateVersion7() instead of Guid.NewGuid()",
+    ),
+    (
+        r"\bDateTime\.Now\b",
+        "Use DateTimeOffset.UtcNow instead of DateTime.Now",
+    ),
+    (
+        r"\b_logger\.Log(?:Information|Warning|Error|Debug|Critical|Trace)\s*\(",
+        "Use [LoggerMessage] source generator — never call _logger.Log*() directly",
+    ),
+    (
+        r"namespace\s+[\w.]+\s*\{",
+        "Use file-scoped namespaces: 'namespace BookStore.X;' not 'namespace BookStore.X { }'",
+    ),
+    (
+        r'"(?:\*DEFAULT\*|default)"',
+        'Use MultiTenancyConstants.* instead of hardcoded tenant strings "*DEFAULT*" or "default"',
+    ),
+]
+
+
+def check_content(content: str) -> list[str]:
+    return [msg for pattern, msg in RULES if re.search(pattern, content)]
+
+
+def extract_cs_files(tool_input: dict) -> list[tuple[str, str]]:
+    """Return (path, content) pairs for .cs files, handling multiple tool input shapes."""
+    results: list[tuple[str, str]] = []
+
+    # editFiles / createFile shape: { files: [{filePath, content}] }
+    for f in tool_input.get("files", []):
+        if isinstance(f, dict):
+            path = f.get("filePath", f.get("path", ""))
+            content = f.get("content", f.get("newContent", ""))
+        else:
+            path, content = str(f), ""
+        if path.endswith(".cs") and content:
+            results.append((path, content))
+
+    # replaceStringInFile shape: { filePath, newString }
+    fp = tool_input.get("filePath", "")
+    if fp.endswith(".cs"):
+        new_str = tool_input.get("newString", "")
+        if new_str:
+            results.append((fp, new_str))
+
+    return results
+
+
+def deny(reason: str) -> None:
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    cs_files = extract_cs_files(data.get("tool_input", {}))
+    if not cs_files:
+        sys.exit(0)
+
+    all_violations: list[str] = []
+    for path, content in cs_files:
+        for violation in check_content(content):
+            all_violations.append(f"  • {path}: {violation}")
+
+    if all_violations:
+        deny("BookStore code rule violations:\n" + "\n".join(all_violations))
+
+
+if __name__ == "__main__":
+    main()

.github/hooks/scripts/check_memory_protocol.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""
+PreToolUse hook: Enforce the agent memory handoff protocol.
+
+Agents may only write to the six designated /memories/session/ files.
+Writes to user memory (/memories/) or repo memory (/memories/repo/) are
+blocked to prevent agents corrupting persistent state.
+
+Input (stdin): VS Code PreToolUse JSON payload
+Output (stdout): JSON deny decision, or nothing on success
+"""
+
+import json
+import sys
+
+ALLOWED_FILES: frozenset[str] = frozenset(
+    {
+        "task-brief.md",
+        "plan.md",
+        "backend-output.md",
+        "frontend-output.md",
+        "test-output.md",
+        "review.md",
+    }
+)
+
+WRITE_COMMANDS: frozenset[str] = frozenset({"create", "str_replace", "insert", "delete"})
+
+
+def deny(reason: str) -> None:
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    tool_name: str = data.get("tool_name", "").lower()
+    if "memory" not in tool_name:
+        sys.exit(0)
+
+    tool_input: dict = data.get("tool_input", {})
+    command: str = tool_input.get("command", "")
+
+    # Read / view operations are always allowed
+    if command not in WRITE_COMMANDS:
+        sys.exit(0)
+
+    path: str = tool_input.get("path", tool_input.get("old_path", ""))
+
+    # Must be under /memories/session/
+    if not path.startswith("/memories/session/"):
+        deny(
+            f"Memory protocol violation: agents may only write to /memories/session/.\n"
+            f"  Attempted path : {path}\n"
+            f"  Allowed prefix : /memories/session/\n"
+            f"  Allowed files  : {', '.join(sorted(ALLOWED_FILES))}\n\n"
+            f"Writing to user memory (/memories/) or repo memory (/memories/repo/) "
+            f"requires explicit user intent — do not do this from an agent."
+        )
+
+    # Must be one of the designated handoff filenames
+    filename = path.rstrip("/").split("/")[-1]
+    if filename not in ALLOWED_FILES:
+        deny(
+            f"Memory protocol violation: '{filename}' is not a recognised session handoff file.\n"
+            f"  Attempted path : {path}\n"
+            f"  Allowed files  : {', '.join(sorted(ALLOWED_FILES))}"
+        )
+
+
+if __name__ == "__main__":
+    main()