# Luna Forge

> Source: <https://github.com/RealAhmedOsama/Luna-Forge>
> Published: 2026-08-04 22:08:43+00:00

**Evidence-driven execution for GPT-5.6 Luna.**

A compact Codex Skill and custom worker that convert clear engineering requests into bounded tasks, minimal patches, deterministic proof, and auditable delivery.

[ Results](#results-at-a-glance) ·

[·](#the-three-source-study)

**Research**[·](#how-luna-forge-works)

**Architecture**[·](#cost-model)

**Economics**[·](#benchmark-protocol)

**Benchmark**[·](#installation)

**Install**

**Publish** Important

Luna Forge does **not** claim that prompting can make Luna universally more capable than Sol, Claude Fable, or any frontier model. It targets a narrower, testable objective: **more independently accepted bounded engineering work per unit of cost**. Cost figures are derived from reviewed rate cards. The quality uplift is **Projected, not measured** until the included repository benchmark is completed.

GPT-5.6 Luna is attractive for high-volume, cost-sensitive engineering work, but the right strategy is not to paste a frontier product's entire system prompt into a smaller model. That would front-load tens of thousands of tokens of foreign tools, schemas, UI protocols, runtime metadata, duplicated instructions, and product-specific policy before Luna reaches the repository evidence that actually matters.

Luna Forge began with a harder question:

What remains useful after every non-portable line is removed, every retained idea is traced to an implementation, and every performance claim is forced to show its evidence class?

The answer was surprisingly small:

```
~95,248–95,459 estimated source tokens
                ↓
7,009 physical source lines classified
                ↓
301 portable or distillable lines (4.29%)
                ↓
~2,964-token activated Skill + agent core
                ↓
8 references loaded only when the task needs them
```

The project rejected **95.71%** of the reviewed source corpus. That rejection is the core design achievement: the workflow keeps transferable execution mechanisms and discards host-specific mass.

| Result | Value | Evidence class | Proof |
|---|---|---|---|
| Source snapshots reviewed | 3 |
Measured |
`docs/audit-summary.json` |

**7,009**`docs/line-by-line-audit.csv`

**100%****301****4.29%**`301 / 7,009`

**6,708****95.71%**`6,708 / 7,009`

**6,398**`docs/source-line-fingerprints-first-two.csv`

**Git blob SHA-1**`d5434648e7d859969403cbb3d8e4209390ce001b`

**95,248–95,459 tokens**`docs/metrics.json`

**~2,964 tokens****96.89–96.90%****~9,141 tokens****90.40–90.42%****21**`evals/cases.yaml`

**18**`tests/`

**14****96%****96%****5–15% relative**`docs/IMPACT_MODEL.md`

**0.65****Not claimed**

```
pie showData
    title Disposition of 7,009 reviewed lines
    "Portable or distilled" : 301
    "Excluded, deferred, or structural" : 6708
```

Every material claim is labeled as one of four classes.

| Label | Meaning | Examples |
|---|---|---|
Measured |
Counted, hashed, executed, or observed directly in this package | Audit rows, source anchors, tests, manifest, archive hash |
Derived |
Reproducible arithmetic from measured inputs or a cited rate card | 4.29% portability, 96.9% context reduction, 96% equal-token savings on both reviewed rate cards |
External |
Reported by another source under its own workload | OpenAI's directional lean-prompt study |
Projected |
A falsifiable hypothesis awaiting repository runs | 5–15% relative score uplift on eligible tasks |

The machine-readable ledger is [ docs/claim-evidence.csv](/RealAhmedOsama/Luna-Forge/blob/main/docs/claim-evidence.csv). The narrative rules are in

[.](/RealAhmedOsama/Luna-Forge/blob/main/docs/EVIDENCE_LEDGER.md)

`docs/EVIDENCE_LEDGER.md`

Note

The 5–15% range is not a completed benchmark, statistical confidence interval, or promise. It is a pre-benchmark engineering hypothesis with **0.65 judgment confidence**. The included protocol is designed to prove, narrow, or reject it.

The reviewed repository presents these files as captured system prompts. Luna Forge treats them as **unverified third-party snapshots**, not authenticated vendor documentation. Integrity anchors prove which snapshot was reviewed; they do not prove the repository's provenance claim.

| Snapshot | Lines | Portable / distilled | Portable share | Token-volume basis | Integrity anchor |
|---|---|---|---|---|---|
| Claude Fable 5 | 3,736 | 135 | 3.61% | ~57,832 | SHA-256 `d9943f…3b375` |
| GPT-5.6 Sol Extra High | 2,662 | 141 | 5.30% | ~28,616 | SHA-256 `ac9bb8…90d98` |
| Kimi K3 | 611 | 25 | 4.09% | ~8,800–9,011 | Git blob SHA-1 `d54346…001b` |
Combined |
7,009 |
301 |
4.29% |
~95,248–95,459 |
Three anchors |

| Disposition | Lines | Meaning |
|---|---|---|
`KEEP_PRINCIPLE` |
46 | Directly portable execution principle |
`DISTILL` |
255 | Useful idea rewritten into a host-neutral rule |
`DROP_SCHEMA` |
3,627 | Tool or function schema supplied by another host |
`DROP_PRODUCT` |
1,118 | Product, UI, path, or vendor-specific behavior |
`DEFER_HOST_POLICY` |
178 | Safety or policy that must remain host-owned |
`DROP_EXAMPLE` |
155 | Large example corpus that duplicates a principle |
`DROP_RUNTIME` |
37 | Identity, date, classifier, or runtime plumbing |
`DROP_PERSONAL` |
5 | Embedded personal metadata |
`IGNORE` |
1,588 | Blank or structural lines retained for complete physical coverage |
Total |
7,009 |
100% decision coverage |

Luna Forge excludes:

- foreign tool and connector schemas;
- vendor identity, model marketing, product UI behavior, and runtime metadata;
- host-specific safety and policy that Codex already owns;
- personal context and unrelated user metadata;
- artifact-rendering tags, sandbox paths, app-specific protocols, and hidden frontend contracts;
- examples that consume context without adding a new execution rule;
- any instruction that assumes a capability not proven in the current environment.

This is why Luna Forge is an original workflow rather than a prompt compilation.

Kimi added the most value where execution control intersects context efficiency. Only **25 of 611 lines (4.09%)** were retained or distilled.

| Kimi-derived mechanism | Luna Forge implementation | Failure mode targeted |
|---|---|---|
| Milestone progress on long work | Short updates only at material findings, decisions, blockers, or completed phases | Agent appears to disappear or floods the user with commands |
| Outcome over machinery | Final report leads with changed behavior, proof, risk, and commit state | Tool transcript hides whether acceptance was actually met |
| Immediate correction | Contradicted hypotheses are replaced as soon as evidence disproves them | Patch is forced to match stale issue wording |
| Time-stability gate | Version-sensitive assumptions are verified from current authoritative sources | Stale SDK, API, pricing, policy, or role claims |
| Capability availability gate | A tool, path, API, file, or permission must be observed before use | Invented capabilities and invalid commands |
| Progressive skill loading | Domain references load at the stage that needs them | Context pollution from irrelevant guidance |
| Active-context authority | Task contract and repository evidence outrank passive background material | Irrelevant context steers implementation |

Kimi-specific tool registries, plugin paths, rendering tags, sandbox conventions, website-delivery rules, and **476 schema lines** were rejected.

See [ docs/KIMI_REVIEW.md](/RealAhmedOsama/Luna-Forge/blob/main/docs/KIMI_REVIEW.md) for the focused analysis.

The two earlier snapshots are anchored by SHA-256. Kimi is anchored by the exact Git blob SHA-1 returned by GitHub.

The first two snapshots additionally have **6,398 exact per-line content_sha12 fingerprints** in

[. Kimi is not redistributed and is therefore verified at whole-blob level; each Kimi decision locator still binds the blob anchor, line number, rule, and action.](/RealAhmedOsama/Luna-Forge/blob/main/docs/source-line-fingerprints-first-two.csv)

`docs/source-line-fingerprints-first-two.csv`

Every source line from `1`

through the source's final physical line receives one deterministic decision row. The validator rejects:

- missing or duplicated lines;
- unexpected source names or line ranges;
- unknown actions or rules;
- changed snapshot anchors;
- changed decision locators;
- totals that do not reproduce the published statistics.

The audit CSV intentionally contains **no prompt text**. Its schema is:

```
source
line
rule_id
action
reason
snapshot_integrity_type
snapshot_integrity
decision_locator_sha12
```

A source idea survives only when it:

- improves bounded repository execution;
- remains valid in Codex without a foreign host feature;
- does not duplicate Codex host policy or repository instructions;
- can be represented compactly as a behavior, gate, or proof requirement;
- maps to an observable implementation location;
- can be evaluated through repository evidence or run behavior.

[ docs/principle-traceability.csv](/RealAhmedOsama/Luna-Forge/blob/main/docs/principle-traceability.csv) maps all

**301** retained or distilled lines into the Skill, agent, references, validator, or eval suite. Validation requires exact one-time coverage: no missing portable line and no double counting.

Static validation can prove package consistency, audit coverage, cost arithmetic, and release integrity. It cannot prove a quality uplift. That requires paired repository executions under controlled conditions, so quality claims are gated by [ docs/BENCHMARK_PROTOCOL.md](/RealAhmedOsama/Luna-Forge/blob/main/docs/BENCHMARK_PROTOCOL.md).

Read the complete method in [ docs/METHODOLOGY.md](/RealAhmedOsama/Luna-Forge/blob/main/docs/METHODOLOGY.md) and the full report in

[.](/RealAhmedOsama/Luna-Forge/blob/main/docs/REVIEW_REPORT.md)

`docs/REVIEW_REPORT.md`

A **Skill** is the smallest correct authoring unit because Luna Forge is one reusable workflow with no required MCP server. Codex Skills also support progressive disclosure: the workflow is loaded when selected, while task-specific references can remain out of context until needed.

The custom agent binds the workflow to GPT-5.6 Luna with a bounded worker profile:

```
name = "luna_worker"
model = "gpt-5.6-luna"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
```

A Plugin may become useful later for broad distribution or bundled connectors. It is unnecessary overhead for the current package.

``` php
flowchart TD
    U[Engineering request] --> S{Bounded, owned, observable?}
    S -->|No| E[Recon, split, or escalate]
    S -->|Yes| C[Micro-contract]
    C --> A[Authority and approval boundaries]
    A --> G[Capability and freshness gates]
    G --> R[Targeted repository evidence]
    R --> B[Baseline or reproduction]
    B --> H{Hypothesis supported?}
    H -->|No| X[Correct assumption immediately]
    X --> R
    H -->|Yes| P[Smallest defensible patch]
    P --> V[Focused tests, compiler, analyzers]
    V --> D[Adversarial diff review]
    D --> Q{Acceptance proven?}
    Q -->|Bounded correction| P
    Q -->|Scope or authority blocker| E
    Q -->|Yes| K[Focused local commit]
    K --> O[Outcome-first evidence report]
    O --> N[Never push automatically]
```

Before editing, the worker establishes:

```
Goal
Authorized scope
Acceptance evidence
Non-goals
Approval boundaries
Risk flags
Validation commands
Delivery requirement
```

That contract becomes the task's routing, scope, and completion boundary.

```
Contract
→ Verify authority
→ Verify capability and freshness
→ Gather causal evidence
→ Establish baseline
→ Patch minimally
→ Prove with deterministic checks
→ Review the full diff adversarially
→ Commit locally when authorized
→ Report outcome and evidence
```

Only the relevant domain file is loaded:

| Reference | Loaded when |
|---|---|
`task-routing.md` |
The task is broad, ambiguous, cross-cutting, or delegated |
`engineering-loop.md` |
A non-trivial implementation or bug fix begins |
`context-budget.md` |
The repository, files, logs, or tool output are large |
`research-verification.md` |
External facts are current, unfamiliar, or version-sensitive |
`dotnet-10.md` |
C# or .NET work is in scope |
`risk-and-rollback.md` |
Database, auth, tenancy, billing, concurrency, production, secrets, or destructive work is involved |
`git-delivery.md` |
Staging, commit, or handoff is required |
`output-contracts.md` |
Final delivery or review findings are prepared |

Luna Forge does not attempt to manufacture model capability. It reallocates a smaller model's attention away from avoidable failure modes and toward repository truth.

| Mechanism | Failure targeted | Observable metric |
|---|---|---|
| Suitability gate | Luna starts work that requires unresolved frontier reasoning | Correct recon or escalation rate |
| Micro-contract | Missing acceptance, scope, non-goals, or approvals | Contract compliance |
| Capability gate | Invented tools, paths, APIs, or permissions | Invalid-capability attempt rate |
| Freshness gate | Stale external assumptions | Authoritative-source evidence rate |
| Evidence before editing | Symptom patch or wrong ownership theory | Reproduction and causal-proof score |
| Immediate correction | Persistence after the premise is disproved | Disproven-premise persistence rate |
| Smallest defensible patch | Unrelated cleanup and regression surface | Changed files, diff size, scope violations |
| Validation ladder | Confident but unsupported completion | Independent acceptance rate |
| Adversarial diff review | Missed edge cases or accidental changes | Post-run reviewer findings |
| One-worker rule | Duplicate scans and coordination overhead | Repeated reads and total tokens |
| Progressive references | Irrelevant prompt mass | Activated context and input tokens |
| Outcome-first delivery | Process narration hides proof | Human-review minutes and evidence completeness |

The worker gets one bounded correction pass. Repeated retries without new evidence trigger escalation instead of unbounded token spend.

| Layer | Approximate tokens | Loading behavior |
|---|---|---|
Core `SKILL.md` |
2,288 | Loaded when invoked |
`luna_worker` instructions |
676 | Loaded for the custom agent |
Activated core |
2,964 |
Normal baseline |
| Eight references | 6,177 total | Loaded only when relevant |
All content worst case |
9,141 |
Unrealistic upper bound |

```
Source estimate: 95,248–95,459 tokens
Activated core:            ~2,964 tokens

Core reduction = 1 - activated_core / source_estimate
               = 96.89–96.90%
All references loaded: ~9,141 tokens
Worst-case reduction:  90.40–90.42%
```

These are context-volume results, not quality results. Their practical purpose is to let Luna reach code, tests, and task evidence before irrelevant instruction mass consumes its budget.

OpenAI separately reports that leaner prompts improved a sample of internal coding-agent evaluation scores by roughly **10–15%**, while reducing total tokens by **41–66%** and cost by **33–67%**. OpenAI describes those results as directional and workload-dependent. Luna Forge uses them as external support for the design direction, not as proof of its own uplift.

API dollars and Codex credits are separate pricing surfaces and are never mixed into one percentage.

Official per-million-token rates verified on 2026-08-05:

| Model | Input | Cached input | Output |
|---|---|---|---|
| GPT-5.6 Sol | $5.00 | $0.50 | $30.00 |
| GPT-5.6 Terra | $2.00 | $0.20 | $12.00 |
| GPT-5.6 Luna | $0.20 | $0.02 | $1.20 |

Every Luna category is `0.04 ×`

Sol.

```
Equal-token saving = 1 - 0.04 = 0.96 = 96%
```

Verified below-threshold example:

```
100,000 input tokens + 10,000 output tokens
Sol:  $0.50 + $0.30  = $0.800
Luna: $0.02 + $0.012 = $0.032
Saving: $0.768 = 96%
```

For API requests with more than 272K input tokens, OpenAI applies `2×`

input and `1.5×`

output pricing to the full request. Cache writes are billed at `1.25×`

the uncached input rate. The calculator models both rules; separately metered tools remain additional costs.

Verified long-context example:

```
1,000,000 input tokens + 100,000 output tokens
Sol:  ($5.00 × 2) + ($3.00 × 1.5) = $14.50
Luna: ($0.20 × 2) + ($0.12 × 1.5) =  $0.58
Saving: $13.92 = 96%
```

Official per-million-token credit rates verified on 2026-08-05:

| Model | Input | Cached input | Output |
|---|---|---|---|
| GPT-5.6 Sol | 125 | 12.5 | 750 |
| GPT-5.6 Terra | 50 | 5 | 300 |
| GPT-5.6 Luna | 5 | 0.5 | 30 |

Every Luna category is also `0.04 ×`

Sol.

```
Equal-token saving = 1 - 0.04 = 0.96 = 96%
```

Verified example:

```
100,000 input tokens + 10,000 output tokens
Sol:  12.5 + 7.5 = 20.0 credits
Luna:  0.5 + 0.3 =  0.8 credits
Saving: 19.2 credits = 96%
```

The current Codex rate card states that Codex does not charge for cache writes. Fast mode consumes credits at a higher rate where supported.

At a 4% equal-token ratio, Luna may consume up to five times the weighted token usage of the Sol reference and still retain an 80% reduction:

```
0.04 × 5.00 = 0.20
```

The five-times figure is a maximum cost envelope, not a recommended token target. Parent-agent usage, retries, separately metered tools, fast-mode multipliers, and repair work consume part of that headroom.

```
successful_task_cost = total cost of every attempt / independently accepted tasks
```

A cheap failed run followed by an expensive repair is not a saving. The benchmark therefore records acceptance, retries, human-review time, and repair cost—not token price alone.

Run the unit-tested calculator:

```
python scripts/benchmark_cost.py --basis api-usd --compare
python scripts/benchmark_cost.py --basis codex-credits --compare
```

See [ docs/cost-model.md](/RealAhmedOsama/Luna-Forge/blob/main/docs/cost-model.md) for formulas and caveats.

Warning

Rate cards, plan limits, long-context multipliers, fast modes, and tool charges can change. Recheck official pricing before making a financial commitment.

```
Projected relative score uplift: 5–15%
Confidence:                      0.65 judgment confidence
Comparator:                      Unstructured GPT-5.6 Luna
Eligible work:                   Clear, bounded, observable repository tasks
Status:                          Projected, not measured
```

- OpenAI's external directional result reports roughly 10–15% higher coding-agent eval scores after prompt simplification.
- Luna Forge removes approximately 96.9% of the studied source context from the normal activated core.
- It adds explicit routing, capability, freshness, evidence, scope, verification, and correction controls.
- Those controls also add overhead, especially on trivial tasks.
- Luna remains a cost-optimized model; the workflow cannot erase its limits on ambiguity and long-horizon synthesis.

The lower bound discounts for overhead and transfer uncertainty. The upper bound is anchored to the external directional result rather than extrapolating beyond it.

The range must be reduced or rejected when representative paired runs show:

- no material composite-score improvement;
- lower independent acceptance;
- higher hard-failure or scope-violation rates;
- more tokens without a reliability gain;
- human-review overhead that erases the cost advantage;
- repeated Sol repair after Luna execution;
- task categories that consistently require unresolved architecture or product judgment.

The target is not the highest raw score at any price. It is a higher rate of accepted work per cost unit while preserving correctness and scope.

The package ships **21 controlled cases** across routing, implementation, .NET, tenancy, concurrency, approvals, research, Git, verification, capability, freshness, epistemic correction, communication, and cost control.

| Configuration | Model | Skill | Purpose |
|---|---|---|---|
`luna-baseline` |
GPT-5.6 Luna | None | Unstructured Luna comparator |
`luna-forge` |
GPT-5.6 Luna | Explicit `$luna-forge` |
Treatment |
`sol-reference` |
GPT-5.6 Sol | None | Frontier reference, not the primary uplift comparator |

- independent acceptance rate;
- hard-failure rate;
- median composite score;
- median successful-task API cost and Codex-credit cost;
- scope violations and unauthorized writes;
- retries and repair attempts;
- input, cached-input, and output tokens;
- human-review minutes;
- latency and diff size.

The benchmark protocol requires at least:

**30 paired runs** across at least 10 representative repository cases;- at least three runs per case and configuration for the initial gate;
- identical repository snapshots and controlled permissions;
- hidden independent acceptance checks;
- no material increase in hard failures;
- no material correctness regression;
- lower successful-task cost;
- publication of the raw scorecard before aggregate claims.

For a durable public claim, [ docs/BENCHMARK_PROTOCOL.md](/RealAhmedOsama/Luna-Forge/blob/main/docs/BENCHMARK_PROTOCOL.md) recommends at least five paired runs per task and configuration.

Run the analyzer:

```
python scripts/analyze_evals.py evals/scorecard.csv
```

The analyzer reports configuration summaries and deterministic bootstrap intervals for median score. The packaged scorecard is intentionally empty; it returns `benchmark_complete: false`

rather than inventing a result.

Full benchmark assets:

`docs/BENCHMARK_PROTOCOL.md`

`evals/cases.yaml`

`evals/rubric.md`

`evals/acceptance-gates.md`

`evals/runbook.md`

`evals/scorecard.csv`

| Claim | Confidence | Basis | Main uncertainty |
|---|---|---|---|
| Package structure and release integrity | 0.99 |
Validator, unit tests, manifest, deterministic rebuild, extraction recheck | Undiscovered validator defect |
| API equal-token saving is 96% at reviewed rates | 0.99 |
Published rates + exact arithmetic + unit tests | Future rate, long-context, cache-write, or tool-charge changes |
| Codex-credit equal-token saving is 96% at reviewed rates | 0.99 |
Published rates + exact arithmetic + unit tests | Future rate, fast-mode, or plan-specific changes |
| One decision exists for every 7,009 reviewed line | 0.99 |
Audit CSV, range checks, action totals | Source provenance, not row coverage |
| First-two per-line fingerprints cover 6,398 lines | 0.99 |
Fingerprint CSV + exact validator coverage | Kimi has only whole-blob anchoring |
| Semantic portability classification is reasonable | 0.90 |
Rule map, rationales, traceability, review | Human judgment |
| Source context is ~95,248–95,459 tokens | 0.92 |
Transparent character and size heuristic | Not measured with the model tokenizer |
| Activated core is ~2,964 tokens | 0.98 |
Character heuristic over exact package files | Tokenizer variance |
| Luna Forge improves eligible-task score by 5–15% | 0.65 |
Mechanism analysis + external directional evidence | No completed repository benchmark |
| Luna Forge beats Sol or Fable on every task | 0.00 |
Unsupported and explicitly prohibited | Model capability differences |

These confidence values are engineering judgments, not statistical intervals or Bayesian posteriors.

- A current Codex release with Agent Skills and custom-agent support.
- Python 3.11 or newer.
- No third-party Python packages.

```
python -m unittest discover -s tests -v
python scripts/validate.py
python scripts/install.py --scope user --dry-run
python scripts/install.py --scope user
```

Installed paths:

```
~/.agents/skills/luna-forge/
~/.codex/agents/luna-worker.toml
python scripts/install.py \
  --scope project \
  --project-root /absolute/path/to/repository \
  --dry-run

python scripts/install.py \
  --scope project \
  --project-root /absolute/path/to/repository
```

The installer validates first, treats identical files as a no-op, refuses conflicting files by default, and creates timestamped backups before an explicitly authorized `--force`

replacement. It does not edit `~/.codex/config.toml`

, delete unrelated files, commit, or push.

See [ INSTALL.md](/RealAhmedOsama/Luna-Forge/blob/main/INSTALL.md) or use

[as a self-contained Codex task.](/RealAhmedOsama/Luna-Forge/blob/main/CODEX_INSTALL_PROMPT.md)

`CODEX_INSTALL_PROMPT.md`

```
$luna-forge

Goal:
Fix cancellation propagation in the campaign dispatch path.

Authorized scope:
- src/Campaigns
- related unit and integration tests only

Acceptance evidence:
- Add a focused regression test.
- Prove the test fails against the baseline when feasible.
- The regression test and relevant build pass after the fix.
- The final diff contains no unrelated changes.

Non-goals:
- No public API redesign.
- No package changes.
- No schema or production configuration changes.

Delivery:
Create one focused local Git commit after validation. Never push automatically.
Resolve only the architecture or requirement ambiguity that Luna should not own.
Then delegate one complete bounded task capsule to luna_worker.
Do not duplicate the worker's repository scan.
After it returns, inspect the critical claims, final diff, and acceptance evidence.
Never push automatically.

<complete task capsule>
$luna-forge

Review the current branch for correctness defects in the changed execution path.
Do not edit, stage, commit, or push.
Return only evidence-backed findings with file and line references, or explicitly state that no finding was validated.
$luna-forge

The request is not yet safe to implement.
Perform bounded reconnaissance only.
Identify the real execution path, unresolved decisions, approval boundaries, and one to three implementation slices with observable acceptance criteria.
Do not modify files.
```

Stay in reconnaissance, split the task, or escalate when the work requires:

- open-ended architecture across multiple subsystems;
- unresolved product, pricing, legal, policy, or risk judgment;
- multi-repository coordination without explicit ownership boundaries;
- destructive migration, production write, deletion, or secret rotation without authorization;
- an unavailable tool, permission, environment, or authoritative fact;
- speculative fixing without reproduction, invariant, or causal evidence;
- a long-horizon plan whose correctness cannot be proved in a bounded loop.

Luna Forge is deliberately selective. Routing a task away from Luna can be the correct result.

```
python scripts/audit_sources.py \
  --metadata-only \
  --output-csv /tmp/line-by-line-audit.csv \
  --output-summary /tmp/audit-summary.json

cmp docs/line-by-line-audit.csv /tmp/line-by-line-audit.csv
cmp docs/audit-summary.json /tmp/audit-summary.json
```

When the exact source snapshots are available locally, pass them to `scripts/audit_sources.py`

; the script verifies their integrity before producing the decision map.

```
python scripts/generate_metrics.py
python -m unittest discover -s tests -v
python scripts/validate.py
python scripts/validate.py --json
python scripts/analyze_evals.py evals/scorecard.csv
python scripts/build_release.py --output-dir /absolute/output/path
```

The release builder:

- removes transient bytecode;
- regenerates the audit and metrics;
- rebuilds
`MANIFEST.sha256`

; - runs all unit tests and validation;
- runs seven isolated installer lifecycle checks;
- creates a deterministic ZIP with fixed timestamps and a single
`luna-forge/`

root; - builds the ZIP a second time and requires byte-for-byte equality;
- rejects path traversal and symlink archive members;
- performs ZIP CRC validation and safe extraction;
- compares every extracted package file byte-for-byte with the source tree;
- reruns tests, validation, and all seven installer checks on the extracted package;
- writes the archive SHA-256 and a machine-readable validation report.

That is **18 automated unit tests**, **14 isolated installer lifecycle checks**, two complete package validation passes, a deterministic rebuild comparison, safe extraction, and a source-to-archive round trip in every release.

The validator checks, among other invariants:

- package version consistency;
- required file presence;
- English-only package-authored text;
- no bundled source-prompt files;
- valid Skill frontmatter and local references;
- custom-agent TOML schema and Luna model settings;
- explicit Skill invocation and no nested agents;
- no automatic push instruction;
- 7,009 unique source-line decisions with exact action totals;
- 6,398 exact per-line fingerprints for the first two sources;
- complete one-time traceability for all 301 portable lines;
- 21 eval cases and benchmark assets;
- cost formulas and known price vectors;
- README local links, JSON documents, and SVG XML;
- claim-ledger evidence levels and prohibited claims;
- manifest hashes for every packaged file.

The final archive is not considered valid merely because it can be opened. It must pass the same validator and installer lifecycle after extraction.

The GitHub-ready archive preserves the complete local repository, including `.git`

, eleven focused commits on `main`

, the annotated `v2.2.1`

tag, and a preconfigured `origin`

for `RealAhmedOsama/luna-forge`

.

```
git status --short --branch
git log --oneline --decorate --graph --all
git tag --list --format='%(refname:short) %(subject)'
git remote -v
```

After creating an empty GitHub repository named `luna-forge`

under `RealAhmedOsama`

, publication remains an explicit maintainer action:

```
git push -u origin main
git push origin v2.2.1
```

The branch push starts validation. The tag push starts the release workflow, which rebuilds and revalidates the deterministic distribution archive before creating the GitHub Release. No package script pushes commits or tags. See [ PUBLISHING.md](/RealAhmedOsama/Luna-Forge/blob/main/PUBLISHING.md) for the complete handoff.

```
luna-forge/
├── VERSION                           Single package version source
├── README.md                         GitHub project page and evidence summary
├── INSTALL.md                        Installation and verification guide
├── CODEX_INSTALL_PROMPT.md           Self-contained Codex installation task
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── CODE_OF_CONDUCT.md
├── CITATION.cff
├── PUBLISHING.md
├── NOTICE.md
├── LICENSE
├── .editorconfig
├── .gitattributes
├── .gitignore
├── .github/                         Issues, ownership, CI, and tagged releases
├── MANIFEST.sha256                   Hash for every packaged file
├── codex/agents/
│   └── luna-worker.toml              GPT-5.6 Luna custom agent
├── skill/luna-forge/
│   ├── SKILL.md                      Core bounded-execution workflow
│   ├── agents/openai.yaml            Skill metadata; implicit invocation disabled
│   └── references/                   Eight progressive domain references
├── docs/
│   ├── REVIEW_REPORT.md              Full research and engineering report
│   ├── METHODOLOGY.md                Source audit and synthesis method
│   ├── BENCHMARK_PROTOCOL.md         Quality-claim promotion protocol
│   ├── IMPACT_MODEL.md               Mechanisms and quality hypothesis
│   ├── EVIDENCE_LEDGER.md            Claim-by-claim evidence boundaries
│   ├── KIMI_REVIEW.md                Kimi-specific contribution review
│   ├── line-by-line-audit.csv        7,009 deterministic line decisions
│   ├── source-line-fingerprints-first-two.csv
│   │                                     6,398 exact per-line content fingerprints
│   ├── principle-traceability.csv    Portable-line implementation map
│   ├── audit-summary.json            Machine-readable audit totals
│   ├── metrics.json                  Machine-readable project metrics
│   ├── claim-evidence.csv            Machine-readable claim ledger
│   └── assets/
│       ├── luna-forge-hero.svg
│       └── evidence-funnel.svg
├── evals/
│   ├── cases.yaml                    21 controlled task cases
│   ├── rubric.md                     100-point rubric and hard failures
│   ├── acceptance-gates.md           Per-run and benchmark gates
│   ├── runbook.md                    Controlled benchmark procedure
│   └── scorecard.csv                 Raw-run capture template
├── scripts/
│   ├── audit_sources.py              Deterministic source decision-map generator
│   ├── analyze_evals.py              Paired-run benchmark analyzer
│   ├── benchmark_cost.py             API and Codex cost calculator
│   ├── generate_metrics.py           Derived metric generator
│   ├── validate.py                   Package integrity and consistency validator
│   ├── build_release.py              Deterministic release and round-trip builder
│   └── install.py                    Safe user or repository installer
└── tests/
    ├── test_audit_rules.py
    ├── test_cost_model.py
    ├── test_eval_analysis.py
    └── test_repository_metadata.py
```

- An original, compact execution workflow.
- A reproducible study of portable agent-execution mechanisms.
- A cost and benchmark framework for bounded engineering work.
- A Skill and custom agent subordinate to Codex host policy, repository instructions, and user authorization.

- An authenticated vendor system prompt.
- A merged copy of the reviewed snapshots.
- A bypass for safety, approvals, sandboxing, or repository policy.
- A guarantee of universal model superiority.
- A completed empirical quality benchmark.
- A replacement for tests, code review, deployment controls, or rollback planning.

- The third-party source repository's provenance was not independently authenticated.
- Portability classification includes human semantic judgment.
- Kimi has whole-blob integrity anchoring rather than bundled per-line content fingerprints.
- Token counts use a transparent character/size heuristic, not the GPT-5.6 tokenizer.
- OpenAI's lean-prompt finding is external, directional, and workload-specific.
- Models, pricing, multipliers, and plan behavior can change.
- Repository results depend on task selection, harness, tools, tests, permissions, and independent review.
- A structured workflow can reduce avoidable failure; it cannot remove fundamental model capability differences.

- No automatic push.
- No nested or parallel agents inside
`luna_worker`

. - No destructive, production, secret, dependency, schema, deletion, or external write without explicit authorization.
- No success claim without observed evidence.
- No invented tool, file, path, API, command result, deployment state, or citation.
- No source prompt text distributed in the package.

[GPT-5.6 model guidance](https://developers.openai.com/api/docs/guides/latest-model)— Luna positioning and the directional lean-prompt study.[GPT-5.6 Luna](https://developers.openai.com/api/docs/models/gpt-5.6-luna)— API pricing and workload positioning.[GPT-5.6 Sol](https://developers.openai.com/api/docs/models/gpt-5.6-sol)— frontier-model positioning and API pricing.[GPT-5.6 Terra](https://developers.openai.com/api/docs/models/gpt-5.6-terra)— balanced-tier positioning and API pricing.[Codex Skills](https://developers.openai.com/codex/skills)— reusable workflows and progressive disclosure.[Codex subagents and custom agents](https://developers.openai.com/codex/agent-configuration/subagents)— task fit, reasoning effort, token overhead, and agent configuration.[Codex rate card](https://help.openai.com/en/articles/20001106-codex-rate-card)— token-credit rates and plan caveats.

The third-party repository is used only as an analysis corpus. Luna Forge does not authenticate its provenance and does not redistribute the reviewed prompt text.

**Use the smallest model that can reliably satisfy the contract—then prove the result.**

Built and maintained by [Ahmed Osama](https://github.com/RealAhmedOsama).

Luna Forge v2.2.1 · English-only package · MIT-licensed original workflow · Never pushes automatically