norn 0.0.1.pre.20260715152924

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e31f003bf7e6fc8487ebc94d9f2fbbc88b2ad1daa26e7a6e50b1485208a49b4e
+  data.tar.gz: 65cb552ff6829cd2eb5a2c3067ddcff07b9ce787b02f64df3ebe80d7b3f8b485
+SHA512:
+  metadata.gz: 3674c6a776c1772fe201792d21ae952cd7f2e2c459e6c13a9ad08220f67b54ce779b392fb2f78de3127933f85b8d241a45102777c0b83877dd273de2801499de
+  data.tar.gz: cb0492372d37188c27df36252d8b4955f84c35242fe99e411efe07979bb128f7adf691fbcc50f1e2226ce9e556da8c5651bc6d92b4bc5ad6a02a535d7888f058

data/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  tester:
+    name: Tester
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,5 @@
+spec/examples.txt
+.norn.yml
+.norn.yaml
+.norn.json
+*.gem

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.5

data/ARCHITECTURE.md

@@ -0,0 +1,271 @@
+# Norn Architecture, Techniques, & Coding Practices Manual
+
+Welcome to the Norn Architecture and Engineering Manual. This document serves as the primary technical specification of Norn's core system architecture, design decisions, safety mechanics, and coding standards.
+
+---
+
+## 1. Core Architectural Philosophy
+
+Norn is built as a **stateless, extensible, dynamic software engineering agent**. Its engineering decisions are guided by three core pillars:
+
+1. **Zero Native C-Dependency Bindings:** Eliminates installation fragility and cross-compilation failures (e.g., `node-gyp` compilation errors, SQLite/LanceDB ABI mismatches, OpenSSL library clashes) by relying entirely on Ruby's robust standard library and stable pure-Ruby gems.
+2. **Object-Oriented Plugin-Centric Extension:** All major subsystems are completely decoupled. External LLM clients, tool libraries, and custom UI renderers register dynamically as self-contained classes.
+3. **Fail-Fast Bootstrapping:** Interface contracts and subclassing dependencies are verified at load time rather than deep inside runtime loops, ensuring any development or configuration error is caught immediately during startup.
+
+---
+
+## 2. Dependency Injection & Core Bootstrap Layout
+
+Norn avoids global state and singleton class structures by managing all components through a central Dependency Injection (DI) Container powered by the `dry-rb` ecosystem.
+
+```
+                        ┌────────────────────────┐
+                        │        bin/norn        │
+                        └───────────┬────────────┘
+                                    │
+                                    ▼
+                        ┌────────────────────────┐
+                        │   ConfigLoader.load    │
+                        └───────────┬────────────┘
+                                    │
+                                    ▼
+                        ┌────────────────────────┐
+                        │  PluginLoader.load_all │
+                        └───────────┬────────────┘
+                                    │
+                                    ▼
+                        ┌────────────────────────┐
+                        │   Normalize ARGV!      │
+                        └───────────┬────────────┘
+                                    │
+                                    ▼
+                        ┌────────────────────────┐
+                        │   Dry::CLI Dispatch    │
+                        └────────────────────────┘
+```
+
+### The DI Container (`lib/norn/container.rb`)
+* `Norn::Container` inherits from `Dry::System::Container` and manages standard components (like LLM clients under `llm.openai` or `llm.gemini`).
+* Resolving clients dynamically from the container decouples the command loop from specific API clients:
+  ```ruby
+  client = Norn::Container["llm.#{provider}"]
+  ```
+
+### Dynamic Global Options Registry (`lib/norn/global_options.rb`)
+To avoid hardcoding flags (like `--provider` or `--debug`) in Norn's core, external plugins can register their own command-line options dynamically during bootstrapping:
+```ruby
+Norn::GlobalOptions.register :provider, 
+                             type: :string, 
+                             aliases: ["-p"], 
+                             desc: "LLM provider to use"
+```
+
+### Flexible ARGV Normalization (`bin/norn`)
+To bypass `dry-cli`'s strict command-order limitations (which usually forces options *after* subcommands), an early-boot normalizer scans `ARGV`, maps registered global options dynamically, and moves them to the end of the argument array prior to dispatching:
+`./bin/norn --provider gemini chat` $\rightarrow$ `./bin/norn chat --provider gemini`
+
+---
+
+## 3. Class-Based Plugin System (`lib/norn/plugin.rb`)
+
+Norn's dynamic extensibility is powered by Object-Oriented class inheritance. 
+
+### The Subclass Registry Hook
+```ruby
+module Norn
+  class Plugin
+    @registered_plugins = []
+
+    def self.inherited(subclass)
+      super
+      @registered_plugins << subclass
+    end
+
+    def self.registered_plugins
+      @registered_plugins
+    end
+  end
+end
+```
+Any file loaded by the `PluginLoader` that subclasses `Norn::Plugin` is automatically registered in-memory on require.
+
+### Hook-Bridging Dispatcher (`lib/norn/plugin_manager.rb`)
+The `PluginManager` acts as a hybrid event-bus. When a lifecycle event is triggered (such as `:on_boot`, `:on_tool_register`, or `:on_render_response`), the manager:
+1. Executes all legacy block-based subscriptions registered via `subscribe`.
+2. Dynamically routes calls to matching instance methods on active `Norn::Plugin` objects, bridging OO designs with event-driven pipelines seamlessly.
+
+---
+
+## 4. Railway-Oriented Programming (ROP) in Ruby
+
+To eliminate fragile nested `begin/rescue/raise` loops, Norn implements **Railway-Oriented Programming** using `dry-monads` and `Dry::Monads::Do` notation.
+
+```
+Success track ──[Load Config]───►[Resolve Client]───►[LLM Call]───►[Execute Tool]──► Success(output)
+                      │                 │               │               │
+Failure track ────────┴─────────────────┴───────────────┴───────────────┴──────────► Failure(payload)
+```
+
+### The Result Monad Pipeline
+Every service, configuration loader, and LLM client returns a monadic `Result` (`Success` or `Failure`):
+```ruby
+# Example of flat, failure-safe loop execution in task.rb
+def execute_loop_step(system_prompt)
+  client = yield resolve_provider_client(Norn.config.llm_provider)
+  
+  response_result = client.call(active_messages, tools: Norn::ToolRegistry.registered_tools)
+  response = yield response_result.alt_map { |payload| payload.with_context(step: :llm_call) }
+
+  # ... proceed on the success track safely ...
+end
+```
+
+### Contextual Failures (`lib/norn/errors.rb`)
+Instead of propagating raw, unhelpful string messages, failures are wrapped inside a structured `Norn::FailurePayload`. This payload holds:
+* The original Ruby exception object (preserving stack traces).
+* A rich `context` Hash capturing the state (e.g., active provider, active prompt, step, original HTTP payloads) at the exact moment of failure, allowing for deep, diagnostic debugging.
+
+---
+
+## 5. Security & Capability-Based Sandboxing
+
+Norn implements a strict, robust **Capability-Based Security Model** to govern tool-calling and parameter accessibility:
+
+```
+[Agent Session Starts]
+        │
+        ├─► Pre-Flight Pruning: Only expose authorized tool schemas to LLM.
+        │
+        ▼
+[LLM decides to call a Tool]
+        │
+        ├─► In-Flight Gatekeeper: Evaluate required capabilities dynamically.
+        │
+        ├─► If Authorized: Execute tool.
+        │
+        └─► If Unauthorized:
+                 ├─► If Mode.interactive? ──► Prompt CLI for Y/N escalation.
+                 └─► If Non-Interactive  ──► Fail-Safe Block & return Failure.
+```
+
+### Standard Capabilities
+* `sys:read`: Read-only local file operations (`file_read`, `glob`, `grep`, `prompt_user`).
+* `sys:write`: Local filesystem writes and edits (`file_write`, `file_edit`).
+* `sys:execute`: Subprocess executions and local command lines.
+
+### Safe Chat Mode Tools
+By classifying tools like `file_read`, `glob`, `grep`, and `prompt_user` under `sys:read` and restricting Chat Mode's permitted capabilities to `[:sys_read, :vcs_read]`, **Chat Mode is securely empowered with read-only capabilities.** 
+
+Chat Mode dynamically maps, reads, and explains files within your codebase safely without any risk of file corruption or write modifications.
+
+### Pre-Flight Schema Pruning
+Before invoking any LLM provider client, Norn selectively filters out any tool whose required capabilities exceed the active mode's permitted profile. This prevents the model from wasting tokens trying to call completely forbidden tools.
+
+### Centralized In-Flight Gatekeeper (`lib/norn/mode.rb`)
+Every mode inherits a secure `#execute_tool` block:
+* If a tool requires unauthorized capabilities in an `interactive?` mode, Norn prompts the user on the CLI for **real-time escalation (Y/N)**. If approved, the permission is temporarily cached for that session.
+* In non-interactive modes, Norn **blocks by default** and aborts execution immediately with a `Failure` monad.
+
+---
+
+## 6. Dynamic In-Flight Danger Guards & Diff Previews
+
+For interactive coding workflows, Norn features a **Dynamic Parametric Danger Gatekeeper** to safeguard your local codebase from unintended modifications.
+
+### Parametric Danger Checking
+Tools can be statically designated as dangerous (like `file_write` or `file_edit`) or dynamically override `#dangerous?(args)` to evaluate their parameters at runtime (e.g. blocking destructive version-control resets while allowing safe status queries).
+
+### Unified Diff Color Helper (`lib/norn/diff_helper.rb`)
+When a dangerous write/edit tool is triggered in an interactive mode, Norn halts execution and:
+1. Resolves the proposed file modifications.
+2. Computes a lightweight, pure-Ruby, unified line diff.
+3. Renders the changes with **bold ANSI terminal formatting** (red `-` for removals, green `+` for additions) to let you audit the edits.
+4. Intercepts terminal input, defaulting to **Yes/Approval** if the user presses Enter immediately (`[Y/n]` prompt) or aborting cleanly on `n`.
+
+---
+
+## 7. Interactive Pairing & Pairing Mode (`lib/norn/modes/dev.rb`)
+
+To bring these features together under an optimal developer workflow, Norn features **Interactive Dev Mode** (`Norn::Modes::Dev`), triggered via `./bin/norn dev`.
+
+* **The Strategy:** Conforms to our full subclassing contracts, carrying full development capabilities (`[:sys_read, :sys_write, :sys_execute, :vcs_read, :vcs_write, :net_egress]`).
+* **The Interaction:** Operates as a live REPL pairing loop. Because it is `interactive?`, all dangerous tool calls (like writing code or running shell scripts) triggered by Gemini/OpenAI are automatically intercepted in-flight by **Section 6 danger guards**, printing diffs and prompting for validation right in your console before execution.
+
+---
+
+## 8. Dynamic Tool-Level System Instruction Injection
+
+To maintain clean plugin decoupling, Norn implements **dynamic system prompt injection**. 
+
+### Decentralized Directives
+Instead of hardcoding tool-use guidelines inside core files, **each tool defines its own instructions** upon initialization inside its respective plugin:
+```ruby
+Norn::Tool.new(
+  "prompt_user",
+  "Prompt the user...",
+  SCHEMA_JSON,
+  system_instructions: "If a user instruction is ambiguous, call the 'prompt_user' tool to obtain structured feedback..."
+)
+```
+
+### In-Flight Prompt Compilation (`lib/norn/mode.rb`)
+Before dispatching a conversational turn to the LLM client, Norn calls `#compile_system_prompt` on the active Mode:
+1. It identifies all tools **currently authorized** for the active Mode.
+2. It collects only those tools' `system_instructions` and joins them under a clean `TOOL EXECUTION DIRECTIVES` block.
+3. It appends this list to the core mode instructions and passes the fully-grounded instructions to the provider, keeping the LLM perfectly aware of its dynamic capabilities on every turn.
+
+---
+
+## 9. Interactive Prompts & The PromptUser Plugin
+
+To empower the LLM with the ability to query, ask, and present choices to the developer programmatically, Norn introduces the **`PromptUser` Plugin** (`plugins/prompt_user/plugin.rb`).
+
+* **Widgets Supported:** Maps the `"prompt_user"` tool directly to native, highly styled terminal elements via `TTY::Prompt`:
+  - `confirm`: Colored binary selector (`yes`/`no`).
+  - `select`: Multi-option cursor selector. Fully supports **explicit single-turn custom write-ins** via the `allow_custom` parameter, which dynamically appends a `"Custom (type your own...)"` option and prompts for inline text input in a single, frictionless conversational step.
+  - `multi_select`: Spacebar checkbox option selector.
+  - `input`: Free-text interactive input.
+* **Context Passing:** The Mode execution gatekeeper passes `self` (the active `Mode` instance) as the `context` parameter to the tool's block execution, enabling the plugin to cleanly access the REPL's `@input` and `@output` streams in a fully stateless, thread-safe manner.
+
+---
+
+## 10. Dynamic Hook Policies & Recovery Track
+
+We standardize Norn's lifecycle hooks and plugin events into two distinct categories:
+
+### A. Notifications (Parallel / Fire-and-Forget)
+Informational events that do not mutate state and execute in parallel (e.g., `:after_llm_call`).
+
+### B. Middlewares (Sequential ROP / Kleisli Reduction)
+Mutating pipelines where the output of one subscriber becomes the input of the next. The entire chain is wrapped in the `Success/Failure` monad track using a monadic `reduce` composed of `bind` operations.
+
+### Recoverable Fail-Safe Policies (`lib/norn/plugin.rb`)
+Plugins can declare their hook policies as `:recover` (recoverable/non-fatal) or `:fatal` (the default). If an optional `:recover` subscriber fails or throws an exception (such as `TTYMarkdownPlugin` parsing), Norn logs a dim grey console warning (`[Norn Warning] Optional hook... failed`) and safely recovers the pipeline, passing the last valid success payload forward.
+
+---
+
+## 11. Security & In-Memory Secret Scrubbing
+
+Norn operates a strict, multi-layered security model to ensure sensitive developer tokens (such as Gemini or OpenAI keys) are never leaked to logs, CLI traces, or API queries.
+
+### Multi-Layer Token Redactor (`lib/norn/secret_scrubber.rb`)
+1. **Dynamic Caching:** When Norn starts up, it registers standard environment keys in-memory. When processing any string, it scans for pattern matches (like Google `key=...` query params or OpenAI `sk-...` signatures), extracts the raw keys, and adds them to a secure in-memory `Set`.
+2. **Deep-Sanitization (`Norn::FailurePayload`):** Raw exceptions (such as `Faraday::BadRequestError`) are recursively traversed. Non-basic objects (like exception variables containing the raw request params with the API keys) are converted to string representations and sanitized before the context is stored.
+3. **Console Boundary Protection (`Norn::ErrorRenderer`):** Just before debug metrics or backtraces are written to standard error, they are scrubbed of all registered secret values.
+
+---
+
+## 12. Multimodal Part Preservation
+
+Gemini's conversation structure relies on an array of `parts` where reasoning chains (thought signatures) and `functionCall` blocks are logically bound.
+
+* **Unified Message Schema:** To prevent structure violations (`INVALID_ARGUMENT: Function call is missing a thought_signature`), the Gemini client extracts and returns the raw API response `parts` in the `Success` monad.
+* **History Preservation:** The `Task` and `Chat` mode loops capture these raw `:parts` and store them in the conversation history, which the Gemini adapter echoes back exactly as received on subsequent turns, keeping Google's backend integrity checks satisfied without polluting other provider formats (like OpenAI).
+
+---
+
+## 13. Coding Practices & Testing Standards
+
+1. **TDD Interface Isolation:** Unit tests (`rspec`) must mock external API requests to return monadic results (`Success(...)` / `Failure(...)`) to ensure perfect compatibility with ROP pipelines.
+2. **Dynamic Spec Cleanups:** Test states are strictly isolated using `config.before(:each)` hooks inside `spec_helper.rb` to clear the `ToolRegistry`, `Plugin.registered_plugins`, and `PluginManager` state.
+3. **Efficiency Overriding:** Directives are explicitly tuned to command immediate writes on file creation requests, preventing the LLM from executing redundant, token-heavy filesystem searches or double-reading files back from disk.

data/COLLABORATIVE_WORKFLOW.md

@@ -0,0 +1,185 @@
+# Collaborative Development Workflow (Humans & Agents)
+
+This document defines the development process for this repository. It serves as a unified execution manual and collaboration standard for Human Developers and AI Agents alike. In our ecosystem, both are treated as co-equal team members (referred to as **Implementers**) who collaborate asynchronously through **Basecamp** as our tracking engine, using **Gherkin/Cucumber** as our shared, executable specifications language.
+
+---
+
+## 1. Core Principles
+
+1. **Co-Equal Partnership**: Humans and agents use the same boards, follow the same pipeline, and are held to the same standards of test coverage, code quality, and documentation.
+2. **Basecamp as the Single Source of Truth**: Requirements, active state, implementation checklists, discussions, and technical decisions live in Basecamp.
+3. **Behavior-Driven Development (BDD)**: All non-trivial functional changes must be described using Gherkin syntax (Given-When-Then). Gherkin serves as both the unambiguous requirement specification and the automated test suite.
+
+---
+
+## 2. Basecamp Card Table Structure (The State Machine)
+
+Our development pipeline is managed via a Basecamp Card Table. The columns represent distinct phases of development and establish clear transitions of ownership:
+
+```
+[ Backlog ] ➔ [ Triage & Planning ] ➔ [ Up Next ] ➔ [ In Progress ] ➔ [ Blocked / On Hold ] ➔ [ Under Review ] ➔ [ Done ]
+```
+
+### Column Definitions & Transition Rules
+
+#### 1. Backlog
+* **Purpose**: A holding zone for raw ideas, bug reports, feature requests, and refactoring notes.
+* **Who can add**: Anyone (humans, monitoring tools, automation scripts).
+* **Requirements**: No strict format is required; entries can be unstructured.
+
+#### 2. Triage & Planning
+* **Purpose**: Active refinement zone where raw Backlog ideas are transformed into actionable, specified tickets.
+* **Who manages**: Tech Leads, Product Owners, or Senior Agents.
+* **Transition rule**: Cards are moved here from the Backlog to be refined. Once Gherkin scenarios are completed and approved, the card moves to **Up Next**.
+
+#### 3. Up Next (The Queue)
+* **Purpose**: The prioritized queue of structured, actionable cards ready for execution.
+* **Who manages**: Product Owners (prioritization).
+* **Requirements to enter**: To be moved into *Up Next*, a card must have:
+  * An action-oriented **Title**.
+  * A **Description** containing business context and **Gherkin Specifications**.
+  * A high-level **Card Steps checklist** for core deliverables.
+
+#### 4. In Progress
+* **Purpose**: Active implementation phase.
+* **Who manages**: The assigned Implementer (Human or Agent).
+* **Transition rule**: An Implementer claims a card by **assigning it to themselves** and **moving it to In Progress** (moving out of *Up Next*).
+
+#### 5. Blocked / On Hold (Human-in-the-Loop Gate)
+* **Purpose**: A parking zone for active cards that cannot proceed due to ambiguity, missing environment secrets, upstream dependencies, or unresolved test failures.
+* **Who manages**: The current Implementer + the requested Unblocker.
+* **Transition rule**: When moving a card here from *In Progress*, the Implementer **must** leave a comment explaining the blocker in detail, provide diagnostic context (e.g., test logs, stack traces), and `@mention` the teammate (human or agent) needed to resolve the issue.
+
+#### 6. Under Review
+* **Purpose**: Code is complete, all local tests pass, and a Pull Request is ready for peer review.
+* **Who manages**: The Peer Reviewer (Human or Agent).
+* **Transition rule**: The Implementer pushes their branch, opens a PR, posts the PR link in a Basecamp card comment, and moves the card here from *In Progress*.
+
+#### 7. Done
+* **Purpose**: The Pull Request has been reviewed, approved, merged, and verified in production.
+* **Who manages**: The Peer Reviewer, Tech Lead, or Deployment Automation.
+* **Transition rule**: Moved here from *Under Review* after the code is merged and verified.
+
+---
+
+## 3. Card Anatomy (Executable Specifications)
+
+To ensure that both humans and AI agents understand requirements without ambiguity, every card in **Up Next** must conform to this structured layout.
+
+### A. Clear, Action-Oriented Title
+Avoid vague titles like "User Invitations". Instead, use active verbs: "Implement user invitation expiration logic".
+
+### B. Business Context & Gherkin Scenarios
+The description must frame the business value and define the acceptance criteria in Gherkin format.
+
+```markdown
+### Business Context
+Currently, user invitation tokens last indefinitely. To improve security and clean up stale pending users, invitation tokens should expire 48 hours after they are generated.
+
+### Acceptance Criteria
+Feature: Expire User Invitations
+
+  Scenario: Invitation is still valid within 48 hours
+    Given a user invitation was created "24 hours ago"
+    When the user attempts to accept the invitation
+    Then the invitation should be accepted successfully
+    And the user account should be activated
+
+  Scenario: Invitation is expired after 48 hours
+    Given a user invitation was created "50 hours ago"
+    When the user attempts to accept the invitation
+    Then the system should refuse the invitation with an "expired" error
+    And the user account should remain inactive
+```
+
+### C. Card Steps (The Checklist)
+Steps serve as granular checkpoints. They provide visual tracking for teammates and structure the execution path for agents.
+
+* [ ] Write regression/integration tests matching the Gherkin specifications
+* [ ] Implement token generation timestamp in database migration
+* [ ] Implement token expiration check in `UserInvitation` model
+* [ ] Handle expired token exceptions in the UI/Controller
+* [ ] Verify the entire test suite passes green locally
+* [ ] Push branch and open Pull Request
+
+---
+
+## 4. The Collaborative Execution Loop
+
+When an Implementer (Human or Agent) begins working on a card, they follow this exact, disciplined loop. This loop directly drives the state transitions of the Basecamp Card Table:
+
+### Workflow State Matrix
+
+| Execution Step | Starting Column | Ending Column | Key Action / Tooling |
+| :--- | :--- | :--- | :--- |
+| **Step 1: Claim & Branch** | `Up Next` | `In Progress` | Assign self, move card, checkout local branch |
+| **Step 2: Refine Plan** | `In Progress` | `In Progress` | Expand/add sub-steps to Card checklist |
+| **Step 3: Edit & Verify** | `In Progress` | `In Progress` | Write tests first, implement, verify locally |
+| **Step 4: Block Escalation** *(Optional)* | `In Progress` | `Blocked / On Hold` | Comment with diagnostics, @mention supervisor, pause |
+| **Step 5: PR & Hand-off** | `In Progress` | `Under Review` | Push branch, open PR, link PR in comment, move card |
+| **Step 6: Merge & Close** | `Under Review` | `Done` | Peer review approval, merge PR, move card |
+
+---
+
+### Step-by-Step Execution Guide
+
+#### Step 1: Claiming & Branching
+1. Take the top card from the **Up Next** column.
+2. Assign the card to yourself.
+3. Move the card to **In Progress**.
+4. Check out a local feature branch named after the card (e.g., `feature/invitation-expiration-789`).
+
+#### Step 2: Refining the Plan
+* Read the Gherkin scenarios carefully.
+* If the pre-authored **Card Steps** are too high-level, the Implementer should add sub-steps (e.g., `[ ] Generate ActiveRecord migration`, `[ ] Refactor token lookup query`) directly to the Basecamp Card Steps checklist. This acts as a collaborative implementation plan.
+
+#### Step 3: Local Edit & Verify Loop (BDD Execution)
+1. **Write Tests First**: Translate the Gherkin specs into automated executable test files (e.g., Cucumber features or RSpec integration specs). Run them and observe them fail.
+2. **Implement Code**: Write the minimal code necessary to make the tests pass.
+3. **Verify Locally**: Run the test suite and linters locally.
+4. **Self-Correction**: If tests fail, analyze the error output, inspect logs, make adjustments, and rerun. The Implementer must iterate locally until all tests pass.
+5. **Asynchronous Updates**: As steps are completed, check them off on the Basecamp card. This keeps the entire team aligned on progress in real time without distracting status meetings.
+
+#### Step 4: Handling Blocks (The Escape Hatch)
+If the Implementer cannot make a test pass, detects an edge-case contradiction in the Gherkin spec, or lacks access to a required key/secret:
+1. Stop local execution.
+2. Move the card to **Blocked / On Hold**.
+3. Write a comment on the card detailing the block:
+   > 🤖 **AGENT UPDATE**: I have implemented the model logic, but the controller test is failing because the Mock API requires a client ID secret.
+   >
+   > **Blocker**: Missing `API_CLIENT_ID` in test environment.
+   > @Jane Smith, could you help me configure this or point me to where test credentials are stored?
+4. Do not block yourself; return to **Up Next** and claim a different card.
+
+#### Step 5: Submission & Hand-off
+1. Verify all tests, linters, and type-checkers are completely green.
+2. Commit changes with clean, atomic commit messages detailing *what* was done and *why*.
+3. Push the feature branch to the remote repository.
+4. Open a Pull Request.
+5. Post a comment on the Basecamp card containing a brief summary of the solution and a link to the PR.
+6. Move the card to **Under Review**.
+
+#### Step 6: Merge & Close
+1. Teammates review the Pull Request and offer feedback.
+2. Once the PR is approved, it is merged into the main branch.
+3. The card is moved to **Done** (and eventually archived).
+
+---
+
+## 5. Basecamp as a Project Knowledge Base
+
+Beyond progress tracking, Basecamp acts as the central knowledge graph for our system. Developers and agents use it to document and retrieve high-level system state:
+
+### A. Architecture Decision Records (ADRs)
+* Major architectural decisions, design patterns, or database modeling choices must be documented in **Basecamp Docs** (within the project's **Vault**).
+* ADRs must be assigned a unique ID (e.g., `ADR-004: Event-Driven Auditing`).
+
+### B. Discussions & RFCs
+* When a design requires open discussion, an Implementer posts a message on the **Basecamp Message Board** labeled as an RFC (Request for Comments).
+* Human team members and AI agents participate in the comment thread to brainstorm, resolve design trade-offs, and reach consensus before code is written.
+
+### C. Contextual Linking
+* Every card in **Up Next** that depends on a specific design pattern must link to the corresponding ADR in its description.
+* Conversely, once an ADR or discussion is closed with a consensus, the concluding message or document must link back to the resulting Basecamp card(s).
+
+This bi-directional linking guarantees that human developers and agents have immediate, rich context for *every single line of code* they are asked to write.

data/GAPS.md

@@ -0,0 +1,6 @@
+# Norn Architectural Gaps & Refactoring Registry
+
+This backlog and gaps registry has been fully migrated to **Basecamp**, which serves as our co-equal async **Single Source of Truth** for requirements and planning.
+
+Please refer to the active work items and specifications on our Basecamp Board:
+👉 **[Norn Card Table](https://app.basecamp.com/5717936/buckets/48052540/card_tables/10089221034)**

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec