knowcode 0.1.0__py3-none-any.whl

knowcode-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: knowcode
+Version: 0.1.0
+Summary: Structural cognition engine for code repositories
+Requires-Python: >=3.13
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=14.0.0
+Requires-Dist: ruamel-yaml>=0.18.0
+Requires-Dist: structlog>=25.0.0
+Requires-Dist: tree-sitter-javascript>=0.25.0
+Requires-Dist: tree-sitter-python>=0.25.0
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.25.2
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# KnowCode
+
+[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](#license)
+
+**KnowCode** is a structural cognition engine designed specifically for Agentic IDEs (like Cursor, Gemini, and Copilot). It bridges the gap between **physical repository code**, **deterministic structural snapshots**, and **semantic architectural knowledge**, allowing AI agents and human developers to seamlessly inspect, track, and maintain codebase architectures.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Usage: The Agentic Workflow](#usage-the-agentic-workflow)
+- [Ecosystem Layout](#ecosystem-layout)
+- [CLI Reference & Manual Execution](#cli-reference--manual-execution)
+- [License](#license)
+
+---
+
+## Overview
+
+KnowCode completely flips the traditional documentation model. Instead of forcing developers to write specs *before* they code, KnowCode uses an AI agent to track your intent during a development session. When you sync your physical code changes, the AI agent is automatically invoked to synthesize your intent against the deterministic reality of the codebase, ensuring your architectural knowledge naturally accumulates as a byproduct of development.
+
+KnowCode partitions codebase understanding into three clean domains:
+1. **Physical Reality:** The actual source files inside the repository.
+2. **Structural Truth:** Deterministic representation of files, components, and code symbols parsed via abstract syntax trees (ASTs).
+3. **Semantic Knowledge:** Permanent architectural rules, decisions, and constraints synthesized by your AI agent.
+
+---
+
+## Key Features
+
+- **Native Agent Integration:** Built-in slash commands (`/knowcode`, `/know-sync`) that plug directly into Agentic IDEs without configuration.
+- **Multi-Language AST Parsing**: Built on top of `tree-sitter`, with out-of-the-box support for **Python**, **JavaScript**, and **TypeScript**.
+- **Deterministic State & Revision Tracking**: Tracks codebase changes across sequential revisions (`S-001`, `S-002`, etc.).
+- **Diff & Report Generation**: Automatically computes additions, deletions, line-boundary modifications, and maps changes to their top-level affected components.
+
+---
+
+## Installation
+
+### Prerequisites
+- [Python 3.13+](https://www.python.org/)
+- [uv Package Manager](https://github.com/astral-sh/uv)
+
+### Installation
+
+You can install Knowcode directly via pip or npm.
+
+**Using pip:**
+```bash
+pip install knowcode
+```
+
+**Using npm:**
+```bash
+npm install -g knowcode
+```
+
+#### Development Setup
+
+If you want to contribute or modify the code, clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/knowiki/knowcode.git
+cd knowcode
+uv sync
+uv pip install -e .
+```
+
+---
+
+## Usage: The Agentic Workflow
+
+KnowCode is designed to be driven by you and your AI agent in tandem.
+
+### 1. Initialize the Repository
+Run the initialization command in your target repository terminal:
+```bash
+know .
+```
+This scaffolds the `.agent/` and `.knowcode/` directories, computes your first AST snapshot, and drops `knowcode.md` at your root. 
+
+*Note: To prevent polluting your repository, `know .` automatically adds `.knowcode/`, `.agent/`, and `knowcode.md` to your `.gitignore`. If you want to share your synthesized semantic knowledge with your team, you can selectively un-ignore `.knowcode/knowledge/`.*
+
+### 2. Activate the Agent
+In your AI chat (Cursor, Copilot, Gemini), simply type:
+```text
+/knowcode
+```
+The agent will instantly read `knowcode.md`, lock into the KnowCode governance rules, and begin silently tracking your intent in `.agent/memory/active_context.md` while you code.
+
+### 3. Sync & Synthesize
+After you finish a coding session or fix a bug, instruct the agent to synchronize by typing:
+```text
+/know-sync
+```
+The agent will orchestrate the entire lifecycle:
+1. Run `know sync` to compute structural AST diffs.
+2. Read the generated structural report (`R-XXX.md`).
+3. Reconcile the structural reality against your tracked intent.
+4. Distribute the extracted knowledge into the 5 semantic buckets (`architecture`, `decisions`, etc.).
+5. Run `know sync-semantic` to commit the knowledge and bump the revision.
+
+---
+
+## Ecosystem Layout
+
+When KnowCode is initialized in a repository via `know .`, it generates a governed agent architecture:
+
+```text
+/
+├── knowcode.md                # The Agent Ignition Switch (Read by the AI)
+├── .agent/                    # The Semantic Governance & Memory Layer
+│   ├── memory/
+│   │   ├── active_context.md  # The AI's short-term intent tracking buffer
+│   │   └── previous_context.md
+│   ├── skills/
+│   │   ├── track_intent.md    # Background skill for tracking architectural intent
+│   │   └── synthesize_knowledge.md
+│   └── workflows/
+│       ├── sync_reconciliation.md # The /know-sync workflow
+│       └── ingest_legacy.md       # The /know-ingest workflow
+│
+└── .knowcode/                 # The Deterministic Knowledge Artifact
+    ├── state.yaml             # Authoritative state registry (managed by the Engine)
+    ├── structure/             # Deterministic AST snapshots (e.g. S-001.json)
+    ├── reports/               # Change and diff analysis reports (e.g. R-001.md)
+    └── knowledge/             # Permanent semantic knowledge (AI synthesized)
+        ├── architecture/
+        ├── components/
+        ├── constraints/
+        ├── conventions/
+        ├── decisions/
+        └── raw/               # Inbox for legacy or unstructured documentation
+```
+
+---
+
+## CLI Reference & Manual Execution
+
+While the Agentic Workflow relies on slash commands to orchestrate operations, developers can bypass the AI entirely and execute any step manually using the `know` CLI. This is useful for CI/CD pipelines, programmatic integration, or direct inspection.
+
+- `know .`: Initializes Knowcode in the current directory.
+- `know status`: Displays current structural and semantic revisions.
+- `know sync`: Computes AST diffs, generates a report, and rolls over the memory buffer.
+- `know sync-semantic`: Bumps the semantic revision after the AI (or a human) finishes synthesis.
+- `know ingest-semantic .`: Wipes the raw documentation inbox and bumps the revision.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

knowcode-0.1.0.dist-info/RECORD

@@ -0,0 +1,63 @@
+runtime/__init__.py,sha256=0c4lglTsbtln7rOZLIn1ZU18mkFYYYf941b8Nagc-lA,302
+runtime/artifact/__init__.py,sha256=7wWPhT1BomXdMiT_PR_IsVx9xG8kWEgSVqOZUFIc1uA,22
+runtime/artifact/builder.py,sha256=49C89nSlHL1k1B8Lja2prb34YYJkqCbEbocvCw1s1kg,7502
+runtime/cli/__init__.py,sha256=OQHDp0zovdmwfBkZXBD3A0VQWrMm2Tko49uhMCL490Y,17
+runtime/cli/animation.py,sha256=gUgRj0qjq_dHxnnboLJSZ2VTB5Cpbsbt01H9mY88fUg,9310
+runtime/cli/app.py,sha256=SxPBHouRsvjOeLSh2kp3aH1Umm-irgM8UBZZCR7xRTs,9764
+runtime/cli/auth.py,sha256=d-n8yGTSwMSUd_v1snaIZ2IM4WBNokmf28P7xP52-J4,5817
+runtime/cli/telemetry.py,sha256=hJZn6sv00eqCb8AGaWFuaev71tmcKmVN2E5Tfxqibq4,2975
+runtime/exceptions/__init__.py,sha256=3MmXA3K6kXQJ_wuwnrbtABn-u_jcqjFunDR2AEd8Y3Y,31
+runtime/exceptions/errors.py,sha256=dbGbZNHm5MWHS3N-sXYQf9hVafeU_2K3NTFixZhurXA,2738
+runtime/repository/__init__.py,sha256=KUljhrbbh-lLfTQaOuvi7jvDQJ6E9EYo-0ZA_DhOpN4,426
+runtime/repository/discovery.py,sha256=yOV2picNIg63C5Q_q-w0MSZCrqHNPxn5g9Ii4cQIPEc,1657
+runtime/repository/models.py,sha256=s_6G3XfE9hUlVyXZjflY7QAAhOvaMs9lc9ZHCJXfA50,3324
+runtime/repository/paths.py,sha256=iw8tpw9JvDXBh2YBtRZhfTaiDsZ-AAMtCXc1o4KoVfc,1592
+runtime/repository/validator.py,sha256=VuIDL7wiACv9xZCVbTMzI27M2Obj3ejWORFRy99Cu-w,2961
+runtime/services/__init__.py,sha256=-xV5NeGY0BUta_C-nkGOx8vMYh8keyjl8lh3PHCFJao,22
+runtime/services/ingest_service.py,sha256=_8SZmx1xuFo5VLZBfgN_gqSxlZ5dQZQVcYOeMWDzV3Q,3372
+runtime/services/init_service.py,sha256=EMK_SX0jWKXe_98codpgAk149UXkmFP9lm27J0PCpDs,1152
+runtime/services/semantic_sync_service.py,sha256=KVw_W7PE-STyl9IEM3pHr-38ssyM67YN99kkgvqrY0o,1484
+runtime/services/status_service.py,sha256=-lpueT0VTbBZ-NXlNtZyQiDyBZ6Fgg2ex2lcViSUsgU,988
+runtime/services/sync_service.py,sha256=h1WgkDzobJ32px1vqB_diAg8-wpIrTttRxP3BpnZXng,1763
+runtime/templates/KNOWCODE_LOADER.md.j2,sha256=7b9mW8BM-BKyPjqsflMae_IGapLN_aOJvYqieUTrECs,1809
+runtime/templates/README_KNOWLEDGE.md.j2,sha256=q_QuWaD75drFpOnnSA6NMAmez-8qTyhh5o7-AY655w4,758
+runtime/templates/README_STRUCTURE.md.j2,sha256=8XqowEl1oa8qSwo9mIC6Mz80lR-KYfgpjkUIbA3OPtY,1118
+runtime/templates/__init__.py,sha256=NnQrQoGS3nEY-O-5f8x7OQV-SjGjsDD-KxuKdK4V70Y,28
+runtime/templates/active_context.md.j2,sha256=xMkGZltRsB2iHo82gc0Cng41FR3xC_jOFbIuQGaWolg,68
+runtime/templates/ingest_legacy.md.j2,sha256=up7bnA4qftnHwcnXPnZzC5nJ7sCzyMy0fZdWPE7TLVk,831
+runtime/templates/raw_readme.md.j2,sha256=0YviMTI0FGWxdDoLx3L9wTs50B0yEIvLGnqUw4rGAA0,695
+runtime/templates/sync_reconciliation.md.j2,sha256=s_pBhC1Oz-0REovU-13xy_0aVVT9HxibYatC_B48DRU,992
+runtime/templates/synthesize_knowledge.md.j2,sha256=cqpmWi02ZXK_4gARVhMp1ckzGhVNT9IfKYvWfocow8c,1808
+runtime/templates/track_intent.md.j2,sha256=IVsOleXActvBpF7m76Wl2knStE4I6naEEiyfC3xrSy8,925
+structural_engine/__init__.py,sha256=4aKD0XYPmynvdaQpQJUpYt0UEn1bp0irHwOWVKdKKbE,253
+structural_engine/engine.py,sha256=fvbkGy03MHH-0yDDBsph2T6D0Ymr9yxrdlxs9LQekc4,7150
+structural_engine/results.py,sha256=04FvN5ZfdBMn3rsdYdSsEp9tvjflndof-xeljTtXK00,1328
+structural_engine/diff/__init__.py,sha256=hRS19h1nMYrG35zz7Pd7Y7MrjFIXZ_s1hJzMVFbqGkU,18
+structural_engine/diff/generator.py,sha256=jIa1W9bR5vjrIio9-9EzeALJDOmwDFqje85EzsWFBOc,3159
+structural_engine/diff/models.py,sha256=Wkkabhs-SmwshJXkJw612r1UQ6jt5YamfqpxmnW-RUM,1650
+structural_engine/logs/__init__.py,sha256=Quhx3OvDpdExMbQ7wD9uO9oroa1VkPVEZXyoNo9AXJo,18
+structural_engine/logs/generator.py,sha256=RzQsRgTy0PLPUzXwkjdcghokXzqUKbG3revCm0YM6Hk,1025
+structural_engine/parser/__init__.py,sha256=Nu7spM-b8GfhOUaJGaZ7VKuHkkZfQlIUJzniYzsppFI,251
+structural_engine/parser/discovery.py,sha256=kHWHXeVPv8Mxmc8rVSj6sKV3WOsiObwrA2BLxGsYMYQ,4192
+structural_engine/parser/models.py,sha256=kEdF9Z4_NG9SyTqmI4K7cmFgEquF4Ely2EcPBN26Drc,5153
+structural_engine/parser/parser.py,sha256=2nBzGTT7Au0o78-HykZa0BSisCb98jzdsB5AkzG2G9M,5361
+structural_engine/parser/extractors/base.py,sha256=GoZOzgg23FFqjninj7gu6dNnkJOCA6IXEKAWMuQyfFM,1372
+structural_engine/parser/languages/javascript/adapter.py,sha256=OWoMV38xbyDRbzUzxaLoMr4dt95d8CE7rEXUHrdipOE,5960
+structural_engine/parser/languages/python/adapter.py,sha256=4WbzlB4ni5XTExt_gWK2h7Jm0ZMX2-u_I1B1FJKPURo,7680
+structural_engine/parser/languages/typescript/adapter.py,sha256=_XhhlQqSvRyPY-2DY86qGwQ73NZiBe1KHZ3aMryj10A,7320
+structural_engine/parser/resolvers/calls.py,sha256=NfymGRMz11I0bPV0512Vob43DpiGIQZ2XnJZwU5VIsA,3970
+structural_engine/parser/tree_sitter/registry.py,sha256=Kri5jSKPgAZYUlaKDEvZ0ec1ZiqClomj6NwbVbcc8FA,1570
+structural_engine/reports/__init__.py,sha256=rTUfl21P_LhmeHZNeXSz8JuLDQiLDkS3GMryNjdhFUA,21
+structural_engine/reports/generator.py,sha256=JNfblJ-Ko2ssyExrvXaNu33QBnE7Ajpdtybgf0dFKrs,2616
+structural_engine/revisions/__init__.py,sha256=gMA7cjs6m6BQGQVrwbGnZiRTSjG7sZQQq2Zl6vnkQwc,23
+structural_engine/revisions/tracker.py,sha256=qgS2HsmUVjbvucY1QfliWhqqMcLOJ8WUoKz_agJoJag,826
+structural_engine/snapshot/__init__.py,sha256=k8w3zMhIg-rLVW8NJ8PxLXfmyXVdvW90DRQoN8QpSOw,22
+structural_engine/snapshot/generator.py,sha256=a_HxuXyoDCHGLsX2859Vbl8Ng0ApZw3b7ZudnpQxNsQ,1689
+structural_engine/snapshot/loader.py,sha256=xb3vFDkmNvFWNPpLMFDn2y4XYsAE4vBgLBk_DXldBKc,1545
+structural_engine/state/__init__.py,sha256=6xEYvIwGtNsTnLsGeLYh-i8X9GIBMv1D_5Qwc1v7baQ,19
+structural_engine/state/manager.py,sha256=n12mxMpUQlQd8l75xxiXsvVj0fZ8aRWbQz7txEmVS8c,5137
+structural_engine/state/models.py,sha256=oF47LM32VgrVbi6BOTb966JXGXAQT4RsRhN-ZL5U6zM,997
+knowcode-0.1.0.dist-info/METADATA,sha256=-mA9BTqcwrOdOQxMSw4LKRW5v4OzkAAIRM7WyBe2Lx4,7181
+knowcode-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+knowcode-0.1.0.dist-info/entry_points.txt,sha256=AXPT3eqMqL_wZnTdfWiKBT-9bVltaIPaKjRIX5z_Rsc,45
+knowcode-0.1.0.dist-info/RECORD,,

knowcode-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

knowcode-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+know = runtime.cli.app:app

runtime/__init__.py

@@ -0,0 +1,4 @@
+# Runtime — the orchestration layer of the KnowCode ecosystem.
+# Owns: CLI, commands, services, repository discovery, artifact creation,
+#        validation, configuration, output, exception handling, delegation.
+# Never owns: parsing, snapshots, reports, logs, revisions, state, semantic knowledge.

runtime/artifact/__init__.py

@@ -0,0 +1 @@
+# Artifact subsystem.

runtime/artifact/builder.py

@@ -0,0 +1,179 @@
+"""Artifact Builder.
+
+Scaffolds the initial ``.knowcode/`` directory structure and renders
+static, human-facing knowledge templates.
+
+Invariants
+----------
+- **ZERO State Awareness:** This module never touches, reads, or writes
+  ``state.yaml``. State management belongs exclusively to the Structural Engine.
+- **Idempotency:** Re-running the builder over an existing initialized
+  directory will safely assert directories exist without destructive overwrites,
+  although the Validator usually prevents this.
+"""
+
+from __future__ import annotations
+
+import jinja2
+import structlog
+from importlib import resources
+
+from runtime.repository.models import RepositoryPaths
+
+logger = structlog.get_logger(__name__)
+
+
+class ArtifactBuilder:
+    """Scaffolds the KnowCode artifact directory structure."""
+
+    def __init__(self, paths: RepositoryPaths) -> None:
+        """Initialize the builder.
+
+        Parameters
+        ----------
+        paths : RepositoryPaths
+            The canonical path contract for the repository.
+        """
+        self.paths = paths
+        # Setup Jinja2 environment loading templates from the runtime package
+        self.jinja_env = jinja2.Environment(
+            loader=jinja2.PackageLoader("runtime", "templates"),
+            autoescape=jinja2.select_autoescape(["html", "xml"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+    def build(self) -> None:
+        """Execute the scaffolding pipeline.
+
+        Creates all required directories and renders static templates.
+        """
+        logger.info("artifact_builder.started", knowcode_root=str(self.paths.knowcode_root))
+
+        self._create_directories()
+        self._render_templates()
+        self._update_gitignore()
+
+        logger.info("artifact_builder.complete")
+
+    def _create_directories(self) -> None:
+        """Create the directory tree."""
+        # Define all required subdirectories
+        dirs_to_create = [
+            self.paths.knowcode_root,
+            self.paths.structure_dir,
+            self.paths.snapshots_dir,
+            self.paths.reports_dir,
+            self.paths.logs_dir,
+            self.paths.knowledge_dir,
+            self.paths.knowledge_dir / "architecture",
+            self.paths.knowledge_dir / "decisions",
+            self.paths.knowledge_dir / "constraints",
+            self.paths.knowledge_dir / "conventions",
+            self.paths.knowledge_dir / "components",
+            self.paths.agent_dir,
+            self.paths.skills_dir,
+            self.paths.workflows_dir,
+            self.paths.memory_dir,
+            self.paths.raw_knowledge_dir,
+        ]
+
+        for directory in dirs_to_create:
+            directory.mkdir(parents=True, exist_ok=True)
+            logger.debug("artifact_builder.mkdir", path=str(directory))
+
+    def _render_templates(self) -> None:
+        """Render and write static markdown templates."""
+        # 1. Render README_STRUCTURE.md (formerly KNOWCODE.md)
+        struct_template = self.jinja_env.get_template("README_STRUCTURE.md.j2")
+        project_name = self.paths.repo_root.name
+        
+        struct_content = struct_template.render(project_name=project_name)
+        struct_file = self.paths.knowcode_root / "README_STRUCTURE.md"
+        struct_file.write_text(struct_content, encoding="utf-8")
+        logger.debug("artifact_builder.render", file=str(struct_file))
+
+        # 2. Render README_KNOWLEDGE.md (formerly knowledge-maintenance.md)
+        km_template = self.jinja_env.get_template("README_KNOWLEDGE.md.j2")
+        km_content = km_template.render()
+        
+        km_file = self.paths.knowledge_dir / "README_KNOWLEDGE.md"
+        km_file.write_text(km_content, encoding="utf-8")
+        logger.debug("artifact_builder.render", file=str(km_file))
+
+        # 3. Render placeholder README.md files for knowledge subdirectories
+        knowledge_subdirs = {
+            "architecture": "Architecture",
+            "decisions": "Decisions",
+            "constraints": "Constraints",
+            "conventions": "Conventions",
+            "components": "Components",
+        }
+        for dirname, title in knowledge_subdirs.items():
+            readme_path = self.paths.knowledge_dir / dirname / f"{dirname}.md"
+            readme_path.write_text(f"# {title}\n\n", encoding="utf-8")
+            logger.debug("artifact_builder.render", file=str(readme_path))
+
+        # 4. Render raw inbox README
+        raw_template = self.jinja_env.get_template("raw_readme.md.j2")
+        raw_content = raw_template.render()
+        raw_file = self.paths.raw_knowledge_dir / "README.md"
+        raw_file.write_text(raw_content, encoding="utf-8")
+        logger.debug("artifact_builder.render", file=str(raw_file))
+
+        # 5. Render active_context.md
+        ac_template = self.jinja_env.get_template("active_context.md.j2")
+        ac_content = ac_template.render()
+        self.paths.active_context_file.write_text(ac_content, encoding="utf-8")
+        logger.debug("artifact_builder.render", file=str(self.paths.active_context_file))
+
+        # 6. Render knowcode.md (Agent Loader)
+        loader_template = self.jinja_env.get_template("KNOWCODE_LOADER.md.j2")
+        loader_content = loader_template.render()
+        loader_file = self.paths.repo_root / "knowcode.md"
+        loader_file.write_text(loader_content, encoding="utf-8")
+        logger.debug("artifact_builder.render", file=str(loader_file))
+
+        # 7. Render Skills
+        skills = {
+            "track_intent.md.j2": "track_intent.md",
+            "synthesize_knowledge.md.j2": "synthesize_knowledge.md"
+        }
+        for template_name, file_name in skills.items():
+            template = self.jinja_env.get_template(template_name)
+            file_path = self.paths.skills_dir / file_name
+            file_path.write_text(template.render(), encoding="utf-8")
+            logger.debug("artifact_builder.render", file=str(file_path))
+
+        # 8. Render Workflows
+        workflows = {
+            "sync_reconciliation.md.j2": "sync_reconciliation.md",
+            "ingest_legacy.md.j2": "ingest_legacy.md"
+        }
+        for template_name, file_name in workflows.items():
+            template = self.jinja_env.get_template(template_name)
+            file_path = self.paths.workflows_dir / file_name
+            file_path.write_text(template.render(), encoding="utf-8")
+            logger.debug("artifact_builder.render", file=str(file_path))
+
+    def _update_gitignore(self) -> None:
+        """Add knowcode directories to .gitignore if not present."""
+        gitignore_path = self.paths.repo_root / ".gitignore"
+        entries_to_add = [".knowcode/", ".agent/", "knowcode.md"]
+        
+        if not gitignore_path.exists():
+            content = "# Knowcode AI Governance\n" + "\n".join(entries_to_add) + "\n"
+            gitignore_path.write_text(content, encoding="utf-8")
+            logger.debug("artifact_builder.gitignore_created", path=str(gitignore_path))
+            return
+
+        content = gitignore_path.read_text(encoding="utf-8")
+        lines = set(line.strip() for line in content.splitlines())
+        
+        missing = [entry for entry in entries_to_add if entry not in lines]
+        if missing:
+            with gitignore_path.open("a", encoding="utf-8") as f:
+                f.write("\n\n# Knowcode AI Governance\n")
+                for entry in missing:
+                    f.write(f"{entry}\n")
+            logger.debug("artifact_builder.gitignore_updated", appended=missing)

runtime/cli/__init__.py

@@ -0,0 +1 @@
+# CLI subsystem.