# PyCForge coordinated development roadmap

Revision 1.1 — 2026-10-31. Development baseline: PyCForge 1.3.78.

This is the standing development plan for CC's three agendas: PCFC11,
Crucible, and the default conversion imports. The SDK participates whenever
engine contracts or authoring needs change. The shared goal is reliable,
useful Python-to-C conversion followed by reliable C compilation.

This roadmap governs new work alongside AGENTS.md and the README guidelines.
It replaces the older separate UI/conversion sequences and the blanket pause
on import expansion. Memory correctness remains a gate for every capability.
The detailed sequence below is the working plan established from CC's stated
direction; future user instructions can reprioritize it. Stages express
dependencies, not promised dates, release numbers or completed capabilities.

## Responsibilities and common direction

| Agenda | Responsibility | How progress benefits the whole product |
| --- | --- | --- |
| PCFC11 | C language correctness, diagnostics, ABI, code generation, compiler resource limits and optimization | Compile both general C and fresh Crucible output correctly; give actionable failures and predictable build behavior. |
| Crucible | Supported Python semantics, Typed and Runtime lowering, ownership, errors, source provenance and reusable operation contracts | Make each admitted construct correct and composable, with explicit rejection outside its supported domain. |
| Default *imports | Useful, documented conversion packages built on Crucible contracts | Exercise shared capabilities through math, NumPy and JSON; expand coverage without separate semantic implementations for each library. |
| SDK support | Discover, author, verify, package and register extensions through public engine services | Prove the same capabilities work for independent authors and namespaces; update the SDK only when its own interface or behavior requires it. |

Crucible and the default imports advance together. A new import operation
needs an engine contract and regression coverage; a new reusable engine
contract needs a practical import or application example. PCFC11 receives
those generated programs as live integration tests while retaining its own
independent C test suite. Typed and Runtime support must be identified
separately rather than inferred from one another.

## Starting point

- PyCForge 1.3.78 contains pinned PCFC11 0.2.27 source. CC has reported successful
  Windows setup and personal stress attempts; that feedback does not replace
  a recorded native Windows compiler and application test matrix.
- Bundled defaults are math 0.3.0, NumPy 0.4.0 and JSON 0.1.0. NumPy currently
  uses the Runtime route and finite contiguous one-dimensional float64 arrays.
  Division, including atomic in-place division, is part of this bounded profile.
  JSON provides a bounded structured-value codec. Registration does not imply
  compatibility with an entire Python library.
- SDK 0.6.3 supports these contracts unchanged. Existing package identities,
  older profiles and explicit refusal of unsupported new profiles are retained.
- Runtime collection remains opt-in. Native helper scratch, resource lifetimes
  and any wider collection points need their own qualification.
- The Preparing-dialog resize trigger has a 1.3.77 correction; confirmation on
  the reported Windows display remains open. An oversized generated literal
  function exceeded a GCC optimization deadline. Investigate that workload
  across generation and compilation before attributing the cost to PCFC11.

The baseline evidence is recorded in
[PyCForge-1.3.78-Verification.txt](PyCForge-1.3.78-Verification.txt).
The roadmap describes planned work; its recorded increments identify actual changes.

## Coordinated progression

| Stage | PCFC11 | Crucible and default imports | Exit condition |
| --- | --- | --- | --- |
| 1. Consolidate trust | Continue the C11 constraint/diagnostic audit; preserve output on failed builds; broaden fresh generated-C and native platform checks. | Reconcile actual coverage, errors, evaluation order, memory and import behavior; retain reduced reproductions of current failures. | A shared, versioned baseline with reproducible defects, exact supported domains and explicit platform gaps. |
| 2. Deepen useful coverage | Qualify the scalar, pointer, conversion, floating-point and ABI behavior used by the chosen capability at supported optimization levels. | Strengthen reusable numeric, call, container and error contracts; extend math, NumPy and JSON through those contracts. | A complete practical capability works through conversion, native execution and independent SDK authoring. |
| 3. Expand data models | Verify layouts, indexing arithmetic, bounds, calling conventions and larger generated programs. | Introduce richer arrays and structured workflows in bounded steps, with ownership and failure behavior defined first. | Each new representation composes with existing operations and survives allocation failure, aliasing and collection tests. |
| 4. Improve measured performance | Extend verified IR, then live ranges/register allocation and bounded scalar/loop transformations; retain conservative fallback. | Reduce measured code growth, redundant work, copying and allocation; optimize shared kernels without changing their contracts. | Correctness is retained and representative measurements demonstrate a benefit without unexplained regressions. |
| 5. Broaden qualification | Expand real C/application workloads, platform evidence, debugger/toolchain behavior and long-run reliability. | Grow practical workflows and additional defaults where shared contracts justify them; qualify SDK stability against independent authors. | Repeatable release evidence supports the exact advertised scope on each claimed platform. |

Correctness and diagnostics continue through every stage. Performance
measurement starts in stage 1, even though larger optimizer changes come
later. Work that has no dependency on an unavailable platform may continue;
its platform qualification remains explicitly pending.

### Stage 1: establish one reliable baseline

Maintain two connected suites: independent C inputs for PCFC11 and freshly
transpiled applications for the complete PyCForge path. Keep historical fixtures,
but do not let them substitute for current conversion and installed-product tests.
Compare defined behavior against independent references and compiler profiles;
compiler agreement alone is not proof of language or numerical correctness.

Prioritize wrong results, crashes, incorrect acceptance, data loss and lifetime
faults. Retain small reproductions for signed/unsigned conversion, overflow,
evaluation order, floating-point edges, aliasing and failure cleanup as relevant.
Follow up the Windows dialog report and native GC/compiler matrices. Keep
ordinary build failures, cancellation and failed-output preservation covered.

Record transpile time, generated C size, compile time, peak memory and runtime
separately for the large-function case. This identifies whether the next fix
belongs in Crucible lowering, PCFC11, or a particular external compiler path.

### Stage 2: deepen shared conversion capabilities

Audit the implemented surface before adding APIs. Prioritize gaps that block
real programs and improvements reused by multiple operations or packages.

- Numeric work: deepen one-dimensional array operations and reductions. The
  preferred next new capability is bounded sum/mean support, after defining
  accumulation, rounding, cancellation, overflow, empty inputs and error bounds.
  It must not silently relax the current finite-value policy or promise bitwise
  agreement with every NumPy implementation.
- Calls and errors: improve reusable argument binding, optional/named arguments,
  source-order evaluation and precise source diagnostics where coverage gaps
  remain. Preserve profile-specific errors and the existing fatal resource policy.
- Structured values: strengthen composition among JSON, strings, containers and
  functions, including malformed inputs, Unicode, nesting/size limits, round
  trips and cleanup. Reuse the existing value representation and public services.
- Memory: qualify live roots, temporary ownership, aliases and rollback for each
  new operation. Extend active collection boundaries only after the affected
  helper scratch and resources can be traced safely.

Each increment includes its matching PCFC11 cases and a default-import example.
The SDK must also exercise the contract under an independent namespace; no
library-name special case belongs in SDK dispatch.

### Stage 3: expand representations in dependency order

Use owned contiguous two-dimensional arrays as the preferred next array model
after one-dimensional numeric contracts are sound. Define rank, shape, storage
size, layout, indexing, copying and error behavior before admitting new syntax.
Qualify construction, access, arithmetic and reductions together within the
declared subset; do not advertise general multidimensional NumPy support.

Treat views/strides, wider dtype and promotion rules, and general broadcasting
as separate later capabilities. Slicing must retain its documented ownership
semantics: do not implement a NumPy view expression as an undisclosed copy.
Views require parent lifetime, overlap/mutation, bounds and GC contracts first.
Native resources additionally require deterministic release and explicit ABI
and deployment contracts; collection must not become an implicit finalizer.

In the same stage, deepen structured records, containers, function boundaries
and supplied-module workflows according to demonstrated gaps. Keep Typed and
Runtime representations and interoperability promises explicit. Add another
bundled library only when it contributes a useful, maintainable capability;
the default set remains small, with no fixed library-count ceiling.

### Stage 4: optimize with evidence

For PCFC11, extend typed IR and effect verification before broader live-range
allocation, spills/reloads, scalar simplification and loop work. Bound analysis
cost and preserve working fallback paths. Investigate transformations using
both general C programs and current Crucible output.

For Crucible, measure generated-function size, repeated helper work, temporary
arrays, copies and GC costs. Apply shared kernels, bounded code generation or
helper extraction only where evaluation order, failure timing, ownership and
observable results remain correct. Record both small and large workloads.

Keep strict floating-point behavior as the default. Reassociation, contraction,
SIMD and other numerical transformations need explicit policies and accuracy
evidence. Separate compiler-generated kernels, calls into the same native
numeric library, and full application costs when benchmarking. BLAS/LAPACK
integration is conditional on real ABI, layout and deployment qualification;
it is not implied by a larger NumPy profile. PGO/LTO and new targets remain later
work. Do not promise speed multipliers before measurements exist.

### Stage 5: turn progress into repeatable releases

Broaden realistic application inputs, long-running workloads, compiler
hostile-input checks, diagnostics, debugger behavior and supported toolchain
interfaces. Record native Windows and Linux results separately, including exact
versions, flags, skips and known limits. Retain self-compilation, independent
compiler/reference checks and sanitizer coverage where supported.

Keep installation, compiler discovery, explicit build/cancel/failure, import
registration and old/new package compatibility in release qualification.
SDK general stability remains conditional on independent author use and the
arrays/views/native-resource contracts it claims. None of these stages implies
complete C11, arbitrary Python or full third-party-library compatibility.

## SDK update rule

First test every additive engine capability with the unchanged SDK. Engine-owned
catalogues, forms, signatures, templates and Help should carry ordinary additions.
Release an SDK update when it needs a new protocol/format, required field or
widget, verification/result behavior, or a client bug fix. Define compatibility
and refusal behavior before changing a contract; retain old profile meanings.

Exercise the installed engine and SDK in separate environments: discovery,
authoring, verification, deterministic packaging, registration, stale evidence,
old-package admission and prior-engine refusal of unsupported new profiles.
SDK verification and PyCForge admission remain distinct. Browsing metadata must
not execute examples. Avoid version bumps that merely mirror a PyCForge release.

## Selecting and completing the next increment

The 1.3.78 reliability increment fixes Classes & Functions, source outlines and
function folding for valid *import declarations. It preserves original editor
text, nested definitions, copy/jump positions and inert package handling. The
current engine/default-import inventory and platform gaps are recorded together.

The retained 68,135-byte literal workload emits 2,016,111 bytes of C in about
2.15 seconds on the measured Linux host. PCFC11 O0/O1 compile it in about 2.9
seconds and its results match the Python/NumPy reference. GCC O0/O1 exceed the
30-second observation deadline. The compact loop workload and a practical
math/NumPy/JSON class workflow compile and run correctly on all four profiles.
These are single diagnostic observations; giant-function code growth remains
open and there is no general speedup or native Windows claim. Reproduce them
with tools/benchmark_conversion_pipeline.py; detailed evidence is under
evidence/navigation_1_3_78. The harness currently requires POSIX supervision.

The next development queue is:

1. Define and implement the shared one-dimensional sum/mean contract, subject to
   higher-priority defects. Qualify NumPy and an independent SDK namespace with
   PCFC11 and an independent C compiler. Continue compiler correctness/diagnostic
   work and the pending native Windows navigation, compiler and GC follow-up.
2. Investigate bounded lowering for large literal-generated functions using the
   recorded phase costs. Preserve evaluation order, allocation/error behavior
   and ownership before adopting helper extraction or another transformation.
3. Specify the owned two-dimensional model after the one-dimensional numerical
   contracts are qualified, while deepening JSON/structured workflows and
   compiler behavior needed by actual examples.

Prefer one bounded capability and a focused correctness batch per increment.
Urgent defects take precedence. Every implementation increment must record:

- Exact supported/rejected forms, representation, evaluation order, errors,
  ownership, aliasing, numerical policy and resource limits.
- Reproductions plus positive, negative, boundary and differential checks;
  allocation-failure/GC checks where relevant; defined reference expectations.
- Fresh conversion and native compilation/execution with PCFC11 and an
  independent compiler, at relevant optimization levels; platform gaps named.
- Applicable installed SDK compatibility evidence and updated Help, completion,
  catalogue, examples and contract identities, without rewriting old profiles.
- The actual versions, fixtures, results, remaining limitations and final
  artifact hashes. Measure performance claims against a recorded baseline.

Use focused checks while developing; run the required project release checks
for a release. Mark evidence as verified, user-reported, pending or deferred.
Do not convert a pending platform result into a pass to close a stage.

PCFC11 retains its independent test-pcfc11.sh workflow and pinned-source
provenance. PyCForge retains one wheel/source distribution, the versioned
per-user compiler destination and builds only on explicit request. No installer,
startup build or toolchain download is introduced. CC alone publishes releases.
Keep planning and verification records outside the public README and user Help.

## Governing records and preserved history

- [Project instructions](AGENTS.md) and
  [README guidelines](PyCForge-README-Guidelines.txt).
- [Conversion work map](CONVERSION_ROADMAP.md).
- [Current import contract](specifications/PyCForge-SDK-Framework-0.9.md),
  [structured-value contract](specifications/PyCForge-SDK-Framework-0.8.md),
  [SDK workbench](specifications/PyCForge-SDK-Workbench-1.0.md) and
  [default-import/UI standards](docs/UI_IMPORT_STANDARDS.md).
- [Runtime memory contract](specifications/runtime_memory_1_3_72.md).
- PCFC11's docs/UPGRADE_OBJECTIVES.md inside the bundled
  pycforge/pcfc11/PCFC11-0.2.27-source.zip remains the detailed compiler ledger.
  Its older installer/separate-packaging proposals are superseded by current
  project instructions; its compiler engineering objectives remain useful.
- The previous [general roadmap](specifications/roadmap-history/ROADMAP-before-coordination-2026-10-31.txt)
  and [conversion roadmap](specifications/roadmap-history/CONVERSION_ROADMAP-before-coordination-2026-10-31.txt)
  are preserved verbatim as history. Paths inside those snapshots refer to
  their original project-root context. Historical priorities are not current
  instructions, and historical backlog entries require a current coverage audit.
