feat: consolidate Agentic Circuit into pyCircuit 6

.github/CODEOWNERS

@@ -7,3 +7,8 @@
 /CONTRIBUTING.md @PTO-ISA/pycircuit-maintainers
 /SECURITY.md @PTO-ISA/pycircuit-maintainers
 /CODE_OF_CONDUCT.md @PTO-ISA/pycircuit-maintainers
+
+# Agentic Circuit remains a separate semantic and package boundary in the
+# shared repository, but follows the same maintainer review authority.
+/components/agentic-circuit/ @PTO-ISA/pycircuit-maintainers
+/docs/acir/ @PTO-ISA/pycircuit-maintainers

.pre-commit-config.yaml

@@ -6,24 +6,27 @@ repos:
       - id: check-yaml
         args: [--unsafe]
       - id: end-of-file-fixer
+        exclude: ^components/agentic-circuit/
       - id: trailing-whitespace
+        exclude: ^components/agentic-circuit/
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.11.8
     hooks:
       - id: ruff
-        exclude: ^(designs/XiangShan-pyc/|designs/outerCube/|designs/BypassUnit/|designs/RegisterFile/)
+        exclude: ^(components/agentic-circuit/|designs/XiangShan-pyc/|designs/outerCube/|designs/BypassUnit/|designs/RegisterFile/)
 
   - repo: https://github.com/psf/black
     rev: 24.10.0
     hooks:
       - id: black
+        exclude: ^components/agentic-circuit/
 
   - repo: https://github.com/DavidAnson/markdownlint-cli2
     rev: v0.18.1
     hooks:
       - id: markdownlint-cli2
-        exclude: ^(docs/gates/logs/|designs/outerCube/.*\.md$|designs/XiangShan-pyc/docs/design_hierarchy_plan\.md$|docs/cycle_balance_improvement.*\.md$)
+        exclude: ^(components/agentic-circuit/|docs/gates/logs/|designs/outerCube/.*\.md$|designs/XiangShan-pyc/docs/design_hierarchy_plan\.md$|docs/cycle_balance_improvement.*\.md$)
 
   - repo: local
     hooks:

CMakeLists.txt

@@ -6,6 +6,8 @@ include(GNUInstallDirs)
 
 option(PYC_BUILD_MLIR_TOOLS "Build MLIR-based pyc tools" ON)
 option(PYC_BUILD_RUNTIME_LIB "Build pyc6 runtime library" ON)
+option(PYC_BUILD_AGENTIC_CIRCUIT "Build the integrated Agentic Circuit component" OFF)
+option(PYC_BUILD_AGENTIC_CIRCUIT_TESTS "Build Agentic Circuit tests" OFF)
 option(PYC_RUNTIME_ENABLE_ZLIB_TRACE "Enable gzip trace output in runtime (optional)" OFF)
 option(PYC_RUNTIME_BUILD_SHARED "Build shared pyc6 runtime library" OFF)
 option(PYC_INSTALL_TEMPLATES "Install runtime template libraries" ON)
@@ -34,6 +36,13 @@ if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.git")
   endif()
 endif()
 
+if(PYC_BUILD_AGENTIC_CIRCUIT)
+  # Discover LLVM/MLIR in the common parent scope so the PYC and ACIR sibling
+  # subprojects share one imported target graph.
+  find_package(LLVM 22.1.8 EXACT CONFIG REQUIRED)
+  find_package(MLIR 22.1.8 EXACT CONFIG REQUIRED)
+endif()
+
 if(PYC_BUILD_MLIR_TOOLS)
   add_subdirectory(compiler/mlir)
 endif()
@@ -42,6 +51,17 @@ if(PYC_BUILD_RUNTIME_LIB)
   add_subdirectory(runtime/cpp)
 endif()
 
+if(PYC_BUILD_AGENTIC_CIRCUIT)
+  if(NOT PYC_BUILD_MLIR_TOOLS OR NOT PYC_BUILD_RUNTIME_LIB)
+    message(FATAL_ERROR
+      "PYC_BUILD_AGENTIC_CIRCUIT requires PYC_BUILD_MLIR_TOOLS=ON and "
+      "PYC_BUILD_RUNTIME_LIB=ON so ACIR-to-PYC uses the repo-local pyc6 toolchain")
+  endif()
+  set(ACIR_BUILD_TESTING "${PYC_BUILD_AGENTIC_CIRCUIT_TESTS}" CACHE BOOL
+    "Build Agentic Circuit tests" FORCE)
+  add_subdirectory(components/agentic-circuit)
+endif()
+
 if(PYC_INSTALL_TEMPLATES)
   install(
     DIRECTORY runtime/cpp

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2026, Kevin Zhou
+Copyright (c) 2026, PTO-ISA
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

README.md

@@ -1,20 +1,23 @@
 # pyCircuit 6
 
 <p align="center">
-  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
+  <img src="https://img.shields.io/badge/License-BSD--3--Clause-blue.svg" alt="License">
   <img src="https://img.shields.io/badge/Python-3.10%2B-green.svg" alt="Python">
   <img src="https://img.shields.io/badge/MLIR-22-orange.svg" alt="MLIR">
   <a href="https://github.com/PTO-ISA/pyCircuit/actions"><img src="https://github.com/PTO-ISA/pyCircuit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://github.com/PTO-ISA/pyCircuit/actions/workflows/release.yml"><img src="https://github.com/PTO-ISA/pyCircuit/actions/workflows/release.yml/badge.svg" alt="Release"></a>
   <a href="https://github.com/PTO-ISA/pyCircuit/releases"><img src="https://img.shields.io/github/v/release/PTO-ISA/pyCircuit?display_name=tag" alt="Latest release"></a>
 </p>
 
-pyCircuit is a Python hardware construction language. It lowers cycle-aware
-designs to a verified MLIR dialect, then emits synthesizable Verilog and a C++
-cycle model from the same IR.
+pyCircuit is a Python hardware construction and architecture-modeling
+repository. The `pycircuit` frontend lowers cycle-aware designs to verified PYC
+MLIR and emits synthesizable Verilog and a C++ cycle model. The retained
+`agentic_circuit` frontend lowers architecture/process/queue descriptions to
+ACIR, then targets either ACSim/gfsim or the pyCircuit 6 hardware flow.
 
 [`PTO-ISA/pyCircuit`](https://github.com/PTO-ISA/pyCircuit) is the canonical
-repository, release authority, and only source of truth.
+repository, release authority, and only active source of truth for both
+pyCircuit and Agentic Circuit.
 [`LinxISA/pyCircuit`](https://github.com/LinxISA/pyCircuit) is its downstream
 fork for Linx integration work.
 
@@ -43,6 +46,14 @@ pre-commit install
 bash flows/scripts/pyc build
 ```
 
+The Agentic Circuit frontend remains a separate distribution and Python
+namespace in the same source repository:
+
+```bash
+python3 -m pip install -e components/agentic-circuit
+agentic-circuit --help
+```
+
 Release wheels, once published, use the distribution name `pycircuit-hisi`;
 the Python import remains `pycircuit`. The repository does not claim a PyPI
 release until the corresponding PTO-ISA release workflow has completed.
@@ -51,6 +62,24 @@ The staged compiler is installed under
 `.pycircuit_out/toolchain/install/`. Set `PYC_TOOLCHAIN_ROOT` to that directory
 when running end-to-end builds from a source checkout.
 
+## Agentic Circuit and ACIR
+
+ACIR remains an independent, upper-level MLIR dialect. It is not folded into
+the PYC dialect and does not replace the Cycle-Aware Signal model:
+
+```text
+agentic_circuit frontend -> ACPy 0.3 -> ACIR
+                                         |-> ACSim -> gfsim
+                                         `-> PYC -> pycc -> pyc6 C++ / Verilog
+
+pycircuit frontend -> Cycle-Aware Signal -> PYC -> pycc -> pyc6 C++ / Verilog
+```
+
+The public `agentic_circuit` import and `agentic-circuit` CLI remain distinct
+from `pycircuit`. AC symbols are not re-exported from `pycircuit.__init__`.
+See the [ACIR architecture overview](docs/acir/index.md) and
+[migration record](docs/acir/migration.md).
+
 ## First cycle-aware design
 
 ```python
@@ -108,6 +137,15 @@ bash flows/scripts/run_examples.sh
 bash flows/scripts/run_sims.sh
 ```
 
+Run the Agentic Circuit frontend and contract lane:
+
+```bash
+PYTHONPATH=components/agentic-circuit/src \
+python3 -m unittest discover \
+  -s components/agentic-circuit/tests \
+  -p 'test_*.py'
+```
+
 System tests require a built toolchain and Verilator:
 
 ```bash
@@ -124,12 +162,16 @@ pytest tests/system -m system
 - [IR specification](docs/IR_SPEC.md)
 - [pyCircuit 6 decisions](docs/rfcs/pyc6-decisions.md)
 - [pyCircuit 6 evolution plan](docs/pyc6-plan.md)
+- [ACIR architecture and frontend](docs/acir/index.md)
+- [Agentic Circuit migration](docs/acir/migration.md)
 
 ## Repository governance
 
-PTO-ISA owns product decisions, releases, package publication, and the default
-branch. Linx integration changes should be developed so they can be reviewed
-upstream; the LinxISA fork follows the upstream default branch.
+PTO-ISA owns product decisions, both Python distributions, releases, package
+publication, and the default branch. Linx integration changes should be
+developed so they can be reviewed upstream; the LinxISA fork follows the
+upstream default branch. The former standalone Agentic Circuit repository is
+retired only after both AC and PYC closure gates pass.
 
 - [Contribution workflow](docs/development/contributing-workflow.md)
 - [Testing and gates](docs/development/testing-and-gates.md)
@@ -146,6 +188,7 @@ trace, and gate contracts use `libpyc6_runtime`, `PYC6TRC3`, and
 pyCircuit/
 ├── compiler/frontend/pycircuit/  # Python language frontend
 ├── compiler/mlir/                # pyc dialect, passes, pycc, and emitters
+├── components/agentic-circuit/   # AC frontend, ACIR/ACSim, gfsim, and AC tools
 ├── runtime/                      # C++ simulation and Verilog primitives
 ├── designs/examples/             # Supported product examples
 ├── flows/                        # Build and validation orchestration
@@ -155,4 +198,6 @@ pyCircuit/
 
 ## License
 
-pyCircuit is licensed under the MIT License. See [LICENSE](LICENSE).
+pyCircuit, including the integrated Agentic Circuit sources, is licensed under
+the BSD 3-Clause License. See [LICENSE](LICENSE) and the
+[relicensing record](docs/legal/AC-RELICENSE-BSD-3-CLAUSE.md).

components/agentic-circuit/.clang-format

@@ -0,0 +1 @@
+BasedOnStyle: LLVM

components/agentic-circuit/.clang-tidy

@@ -0,0 +1,47 @@
+# clang-tidy gate for Agentic Circuit owned sources.
+#
+# The gate enforces the static analyzer plus high-signal bugprone/performance
+# checks that hold across the entire owned tree. Noise-heavy checks whose
+# findings are dominated by MLIR/gtest idioms (macro parentheses, optional
+# access heuristics, generated enum sizing, gtest static initialization) are
+# intentionally out of scope for the CI gate.
+Checks: >
+  -*,
+  clang-analyzer-*,
+  bugprone-assert-side-effect,
+  bugprone-bool-pointer-implicit-conversion,
+  bugprone-dangling-handle,
+  bugprone-exception-escape,
+  bugprone-implicit-widening-of-multiplication-result,
+  bugprone-inc-dec-in-conditions,
+  bugprone-inaccurate-erase,
+  bugprone-infinite-loop,
+  bugprone-misplaced-operator-in-strlen-in-alloc,
+  bugprone-misplaced-widening-cast,
+  bugprone-not-null-terminated-result,
+  bugprone-optional-value-conversion,
+  bugprone-posix-return,
+  bugprone-string-constructor,
+  bugprone-stringview-nullptr,
+  bugprone-suspicious-missing-comma,
+  bugprone-suspicious-realloc-usage,
+  bugprone-suspicious-string-compare,
+  bugprone-swapped-arguments,
+  bugprone-undelegated-constructor,
+  bugprone-undefined-memory-manipulation,
+  bugprone-unhandled-self-assignment,
+  bugprone-use-after-move,
+  bugprone-virtual-near-miss,
+  performance-faster-string-find,
+  performance-implicit-conversion-in-loop,
+  performance-inefficient-algorithm,
+  performance-inefficient-string-concatenation,
+  performance-move-const-arg,
+  performance-no-automatic-move,
+  performance-no-int-to-ptr,
+  performance-trivially-destructible,
+  performance-type-promotion-in-math-fn,
+  performance-unnecessary-copy-initialization,
+  -clang-analyzer-core.StackAddressEscape
+WarningsAsErrors: '*'
+HeaderFilterRegex: '.*agentic-circuit/(include|lib|tools|unittests)/.*'

components/agentic-circuit/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

components/agentic-circuit/.gitattributes

@@ -0,0 +1,9 @@
+* text=auto eol=lf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.pdf binary
+references/davincioo-gfsim/upstream/** whitespace=-trailing-space

components/agentic-circuit/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"